Feat/fishing

CHANGELOG.md

@@ -10,6 +10,13 @@
 
 ---
 
+#### New Effects (0.16.0)
+
+---
+
+* Added Fishing, where concurrent hooks catch scattered swimming characters and reel them into their final text
+  positions, with reusable fishing lines, bite ripples, and bounded optional junk catches.
+
 #### 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,fishing,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}
                         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.
@@ -203,6 +203,7 @@ View the [Documentation](https://chrisbuilds.github.io/terminaltexteffects/) for
     errorcorrect        Some characters start in the wrong position and are corrected in sequence.
     expand              Expands the text from a single point.
     fireworks           Characters launch and explode like fireworks and fall into place.
+    fishing             Fishing hooks catch scattered characters and reel them into place.
     highlight           Run a specular highlight across the text.
     laseretch           A laser etches characters onto the terminal.
     matrix              Matrix digital rain effect.

docs/effects/fishing.md

@@ -0,0 +1,18 @@
+# Fishing
+
+Several fishing lines cast from the top of the canvas, catch scattered swimming characters, and reel them into their
+correct final text positions. Hooks briefly tug at each catch, transport it across the canvas, and cleanly disappear
+after the text settles. Each hook also has a small, bounded chance to catch harmless junk before retrying its target.
+
+## Quick Start
+
+``` py title="fishing.py"
+from terminaltexteffects.effects import Fishing
+
+effect = Fishing("YourTextHere")
+with effect.terminal_output() as terminal:
+    for frame in effect:
+        terminal.print(frame)
+```
+
+::: terminaltexteffects.effects.effect_fishing

docs/showroom.md

@@ -500,6 +500,40 @@ Launches characters up the screen where they explode like fireworks and fall int
     ```
 ---
 
+## Fishing
+
+Fishing hooks catch scattered, swimming characters and reel them into their correct text positions.
+
+[Reference](./effects/fishing.md){ .md-button } [Config](./effects/fishing.md#terminaltexteffects.effects.effect_fishing.FishingConfig){ .md-button }
+
+??? example "Fishing Command Line Arguments"
+
+    ```
+    --hook-count (int > 0)
+                        Maximum number of fishing hooks working concurrently. (default: 3)
+    --line-color (XTerm [0-255] OR RGB Hex [000000-ffffff])
+                        Color used for fishing lines and hooks. (default: D6F6FF)
+    --water-colors (XTerm [0-255] OR RGB Hex [000000-ffffff]) [(XTerm [0-255] OR RGB Hex [000000-ffffff]) ...]
+                        Colors used while input characters swim before being caught. (default: 0B7285 1098AD 66D9E8)
+    --cast-speed (float > 0)
+                        Speed at which hooks slide and cast toward swimming characters. (default: 0.75)
+    --reel-speed (float > 0)
+                        Speed used while reeling catches and returning hooks. (default: 1.25)
+    --cast-delay (int >= 0)
+                        Frames between casts and between each hook's initial start. (default: 4)
+    --wrong-catch-chance (0 <= float(n) <= 1)
+                        One-time probability that each hook catches harmless junk before a real target. (default: 0.05)
+    --final-gradient-stops (XTerm [0-255] OR RGB Hex [000000-ffffff]) [(XTerm [0-255] OR RGB Hex [000000-ffffff]) ...]
+                        Final character gradient colors. (default: 1E90FF 00D1B2 FFE66D)
+    --final-gradient-steps (int > 0) [(int > 0) ...]
+                        Number of steps in the final gradient. (default: 12)
+    --final-gradient-direction (diagonal, horizontal, vertical, radial)
+                        Direction of the final gradient across the text. (default: horizontal)
+
+    Example: terminaltexteffects fishing --hook-count 3 --line-color D6F6FF --water-colors 0B7285 1098AD 66D9E8 --cast-speed 0.75 --reel-speed 1.25 --cast-delay 4 --wrong-catch-chance 0.05 --final-gradient-stops 1E90FF 00D1B2 FFE66D --final-gradient-steps 12 --final-gradient-direction horizontal
+    ```
+---
+
 ## Highlight
 
 Run a specular highlight across the text.

mkdocs.yml

@@ -111,6 +111,7 @@ nav:
       - effects/errorcorrect.md
       - effects/expand.md
       - effects/fireworks.md
+      - effects/fishing.md
       - effects/highlight.md
       - effects/laseretch.md
       - effects/matrix.md

terminaltexteffects/effects/__init__.py

@@ -12,6 +12,7 @@
 from terminaltexteffects.effects.effect_errorcorrect import ErrorCorrect
 from terminaltexteffects.effects.effect_expand import Expand
 from terminaltexteffects.effects.effect_fireworks import Fireworks
+from terminaltexteffects.effects.effect_fishing import Fishing
 from terminaltexteffects.effects.effect_highlight import Highlight
 from terminaltexteffects.effects.effect_laseretch import LaserEtch
 from terminaltexteffects.effects.effect_matrix import Matrix