Feat/snake

CHANGELOG.md

@@ -10,6 +10,13 @@
 
 ---
 
+#### New Effects (0.16.0)
+
+---
+
+* Added Snake, an orthogonal grid animation in which multiple edge-entering snakes carry input characters and
+  deposit them into their final positions while their bodies shrink.
+
 #### Development Tooling (0.16.0)
 
 ---

README.md

@@ -189,7 +189,7 @@ View the [Documentation](https://chrisbuilds.github.io/terminaltexteffects/) for
   Effect:
   Name of the effect to apply. Use <effect> -h for effect specific help.
 
-  {beams,binarypath,blackhole,bouncyballs,bubbles,burn,colorshift,crumble,decrypt,errorcorrect,expand,fireworks,highlight,laseretch,matrix,middleout,orbittingvolley,overflow,pour,print,rain,randomsequence,rings,scattered,slice,slide,smoke,spotlights,spray,swarm,sweep,synthgrid,thunderstorm,unstable,vhstape,waves,wipe}
+  {beams,binarypath,blackhole,bouncyballs,bubbles,burn,colorshift,crumble,decrypt,errorcorrect,expand,fireworks,highlight,laseretch,matrix,middleout,orbittingvolley,overflow,pour,print,rain,randomsequence,rings,scattered,slice,slide,smoke,snake,spotlights,spray,swarm,sweep,synthgrid,thunderstorm,unstable,vhstape,waves,wipe}
                         Available Effects
     beams               Create beams which travel over the canvas illuminating the characters behind them.
     binarypath          Binary representations of each character move towards the home coordinate of the character.
@@ -218,6 +218,7 @@ View the [Documentation](https://chrisbuilds.github.io/terminaltexteffects/) for
     slice               Slices the input in half and slides it into place from opposite directions.
     slide               Slide characters into view from outside the terminal.
     smoke               Smoke floods the canvas colorizing any characters it crosses.
+    snake               Snakes carry characters through the canvas and assemble the input text.
     spotlights          Spotlights search the text area, illuminating characters, before converging in the center and expanding.
     spray               Draws the characters spawning at varying rates from a single point.
     swarm               Characters are grouped into swarms and move around the terminal before settling into position.

docs/effects/snake.md

@@ -0,0 +1,16 @@
+# Snake
+
+Multiple snakes enter from the canvas edges, carry the input characters through orthogonal paths, and deposit them into the final text.
+
+## Quick Start
+
+``` py title="snake.py"
+from terminaltexteffects.effects.effect_snake import Snake
+
+effect = Snake("YourTextHere")
+with effect.terminal_output() as terminal:
+    for frame in effect:
+        terminal.print(frame)
+```
+
+::: terminaltexteffects.effects.effect_snake

docs/showroom.md

@@ -1214,6 +1214,36 @@ Smoke floods the canvas colorizing any characters it crosses.
     ```
 ---
 
+## Snake
+
+Multiple snakes enter from the canvas edges, carry the input characters through orthogonal paths, and deposit them into the final text.
+
+[Reference](./effects/snake.md){ .md-button } [Config](./effects/snake.md#terminaltexteffects.effects.effect_snake.SnakeConfig){ .md-button }
+
+??? example "Snake Command Line Arguments"
+
+    ```
+    --snake-count (int > 0)
+                        Maximum number of snakes. The effective count is limited by the number of input characters. (default: 4)
+    --snake-colors (XTerm [0-255] OR RGB Hex [000000-ffffff]) [(XTerm [0-255] OR RGB Hex [000000-ffffff]) ...]
+                        Colors assigned to snakes in sequence. (default: (Color('22c55e'), Color('84cc16'), Color('a3e635')))
+    --movement-speed (float > 0)
+                        Speed of snake head movement along the grid. (default: 1.0)
+    --spawn-delay (int >= 0)
+                        Number of frames between snake spawns. (default: 3)
+    --head-symbol (ASCII/UTF-8 character)
+                        Symbol used for each snake head. (default: ●)
+    --final-gradient-stops (XTerm [0-255] OR RGB Hex [000000-ffffff]) [(XTerm [0-255] OR RGB Hex [000000-ffffff]) ...]
+                        Space separated, unquoted, list of colors for the character gradient (applied across the canvas). If only one color is provided, the characters will be displayed in that color. (default: (Color('22c55e'), Color('84cc16'), Color('fde047')))
+    --final-gradient-steps (int > 0) [(int > 0) ...]
+                        Space separated, unquoted, list of the number of gradient steps to use. More steps will create a smoother and longer gradient animation. (default: 12)
+    --final-gradient-direction (diagonal, horizontal, vertical, radial)
+                        Direction of the final gradient across the text. (default: Direction.HORIZONTAL)
+
+    Example: terminaltexteffects snake --snake-count 4 --snake-colors 22c55e 84cc16 a3e635 --movement-speed 1 --spawn-delay 3 --head-symbol ● --final-gradient-stops 22c55e 84cc16 fde047 --final-gradient-steps 12 --final-gradient-direction horizontal
+    ```
+---
+
 ## Spotlights
 
 Spotlights search the text area, illuminating characters, before converging in the center and expanding.

mkdocs.yml

@@ -126,6 +126,7 @@ nav:
       - effects/slice.md
       - effects/slide.md
       - effects/smoke.md
+      - effects/snake.md
       - effects/spotlights.md
       - effects/spray.md
       - effects/swarm.md

terminaltexteffects/effects/__init__.py

@@ -27,6 +27,7 @@
 from terminaltexteffects.effects.effect_slice import Slice
 from terminaltexteffects.effects.effect_slide import Slide
 from terminaltexteffects.effects.effect_smoke import Smoke
+from terminaltexteffects.effects.effect_snake import Snake
 from terminaltexteffects.effects.effect_spotlights import Spotlights
 from terminaltexteffects.effects.effect_spray import Spray
 from terminaltexteffects.effects.effect_swarm import Swarm