Code cleanup

1 files changed, 53 insertions, 6 deletions

diff --git a/docs/tweens.org b/docs/tweens.org
index 9ac87cd..213b3ee 100644
--- a/docs/tweens.org
+++ b/docs/tweens.org
@@ -18,31 +18,79 @@ Durations and delays are in **milliseconds**, matching the =dt= argument to =upd
 ** ~make-tween~
 
 #+begin_src scheme
-(make-tween entity #!key props duration (delay 0) ease (on-complete #f))
+(make-tween entity #!key props duration (delay 0) ease
+            (on-complete #f) (repeat 0) (yoyo? #f))
 #+end_src
 
 | Keyword | Meaning |
 |---------+---------|
 | ~props~ | Alist =((#:x . 200) (#:y . 40))= — keyword keys, numeric targets |
 | ~duration~ | Positive integer, milliseconds of interpolation (after ~delay~) |
-| ~delay~ | Non-negative integer ms before interpolation starts |
+| ~delay~ | Non-negative integer ms before interpolation starts (first cycle only) |
 | ~ease~ | Easing symbol (see table below) or ~(lambda (t) ...)= with ~t~ in $[0,1]$ |
-| ~on-complete~ | Optional ~(lambda (entity) ...)=, called **once** when the tween reaches its targets |
+| ~on-complete~ | Optional ~(lambda (entity) ...)=, called **once** when the tween fully ends (not called with ~repeat: -1~) |
+| ~repeat~ | ~0~ = play once (default), ~N~ = replay N additional times, ~-1~ = loop forever |
+| ~yoyo?~ | ~#f~ (default) = replay same direction, ~#t~ = reverse direction each cycle |
 
 Start values are captured from ~entity~ at construction time. While the tween runs, intermediate values may be **inexact** (flonums) even if starts and ends are integers.
 
+*** Repeat and yoyo
+
+~repeat:~ controls how many extra times the tween replays after the initial play. ~yoyo?: #t~ swaps start and end values on each cycle, creating a ping-pong effect.
+
+| ~repeat~ | ~yoyo?~ | Behavior |
+|------+-------+----------|
+| ~0~ | either | Play once and finish (default) |
+| ~1~ | ~#f~ | Play forward twice, then finish |
+| ~1~ | ~#t~ | Play forward, then backward, then finish |
+| ~-1~ | ~#f~ | Play forward forever |
+| ~-1~ | ~#t~ | Ping-pong forever |
+
+~delay:~ only applies before the first cycle. ~on-complete~ fires once when the last repeat finishes; it never fires with ~repeat: -1~. Overflow time from a completed cycle carries into the next cycle for smooth transitions.
+
 ** ~tween-step~
 
 #+begin_src scheme
 (tween-step tween entity dt)
 #+end_src
 
-Returns ~(values new-tween new-entity)~. Advance time by ~dt~ (ms). Before ~delay~ elapses, ~entity~ is unchanged. After completion, further steps return the same values (idempotent). When the tween completes, ~on-complete~ runs with the **final** entity (targets applied), then the callback slot is cleared.
+Returns ~(values new-tween new-entity)~. Advance time by ~dt~ (ms). Before ~delay~ elapses, ~entity~ is unchanged. After completion, further steps return the same values (idempotent). When the tween completes, ~on-complete~ runs with the **final** entity (targets applied), then the callback slot is cleared. With ~repeat:~ / ~yoyo?:~, the tween automatically resets for the next cycle.
 
 ** ~tween-finished?~ / ~tween-active?~
 
 Predicates on the tween struct.
 
+** ~step-tweens~ (pipeline step)
+
+#+begin_src scheme
+(step-tweens entity dt)
+#+end_src
+
+Auto-advances ~#:tween~ on an entity. If the entity has no ~#:tween~ key, returns the entity unchanged. When the tween finishes (no more repeats), ~#:tween~ is removed from the entity. Respects ~#:skip-pipelines~: skipped when ~'tweens~ is in the list.
+
+This is the recommended way to run tweens in most games. Attach a tween to an entity and include ~step-tweens~ in your per-entity pipeline:
+
+#+begin_src scheme
+(scene-update-entities scene
+  (lambda (e) (step-tweens e dt)))
+#+end_src
+
+** Entity key: ~#:tween~
+
+Attach a tween directly to an entity for automatic advancement by ~step-tweens~:
+
+#+begin_src scheme
+(list #:type 'platform
+      #:x 100 #:y 300 #:width 48 #:height 16
+      #:solid? #t #:immovable? #t #:gravity? #f
+      #:tween (make-tween (list #:x 100)
+                props: '((#:x . 300))
+                duration: 3000 ease: 'sine-in-out
+                repeat: -1 yoyo?: #t))
+#+end_src
+
+The platform ping-pongs between x=100 and x=300 forever. No manual tween management needed.
+
 * Easing
 
 Each ease maps normalized time ~t ∈ [0,1]~ to an interpolation factor (usually in ~[0,1]~; ~back-out~ may exceed ~1~ briefly).
@@ -85,6 +133,5 @@ Example skip list for “kinematic shove” while keeping tile collisions:
 
 * Limitations (current version)
 
-- Single segment per tween (no built-in chains or yoyo).
+- Single segment per tween (no built-in chains or sequences).
 - Numeric properties only.
-- No engine integration — you wire ~tween-step~ yourself.