diff options
Diffstat (limited to 'docs/tweens.org')
| -rw-r--r-- | docs/tweens.org | 59 |
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. |