diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/api.org | 20 | ||||
| -rw-r--r-- | docs/entities.org | 3 | ||||
| -rw-r--r-- | docs/tweens.org | 59 |
3 files changed, 71 insertions, 11 deletions
diff --git a/docs/api.org b/docs/api.org index c418ec8..d4dc074 100644 --- a/docs/api.org +++ b/docs/api.org @@ -430,7 +430,8 @@ All entities can have these keys. Not all are required: | ~#:on-ground?~ | boolean | Is entity touching a solid tile below? | | ~#:facing~ | integer | 1 (right) or -1 (left) | | ~#:solid?~ | boolean | Participate in AABB entity collisions? | -| ~#:skip-pipelines~ | list | Symbols naming pipeline steps to skip; physics defines the built-in set (~docs/physics.org~) | +| ~#:skip-pipelines~ | list | Symbols naming pipeline steps to skip; physics defines the built-in set (~docs/physics.org~); ~'tweens~ skips ~step-tweens~ | +| ~#:tween~ | tween/false | Active tween struct, auto-advanced by ~step-tweens~ | | ~#:anim-name~ | symbol | Current animation name | | ~#:anim-frame~ | integer | Current frame index | | ~#:anim-tick~ | integer | Ticks in current frame | @@ -1046,16 +1047,19 @@ Time-based interpolation of numeric entity properties. Library-only — call fro ** ~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 | Description | |---------+-------------| | ~props~ | Alist ~((#:key . target-number) ...)~ | | ~duration~ | Milliseconds of interpolation after ~delay~ | -| ~delay~ | Initial wait in ms (default 0) | +| ~delay~ | Initial wait in ms (default 0, first cycle only) | | ~ease~ | Symbol (e.g. ~quad-in-out~) or ~(lambda (t) ...)~ with ~t~ in [0,1] | -| ~on-complete~ | Optional ~(lambda (entity) ...)~ once at completion | +| ~on-complete~ | Optional ~(lambda (entity) ...)~ once at final completion (not called with ~repeat: -1~) | +| ~repeat~ | ~0~ = play once (default), ~N~ = replay N extra times, ~-1~ = loop forever | +| ~yoyo?~ | ~#f~ (default) = same direction, ~#t~ = reverse each cycle | ** ~tween-step~ @@ -1067,6 +1071,14 @@ Returns two values: updated tween struct and updated entity. ~dt~ is elapsed mil ** ~tween-finished?~ / ~tween-active?~ +** ~step-tweens~ + +#+begin_src scheme +(step-tweens entity dt) +#+end_src + +Pipeline step: auto-advances ~#:tween~ on an entity. No-op if ~#:tween~ is absent. Removes ~#:tween~ when the tween finishes. Skipped when ~'tweens~ is in ~#:skip-pipelines~. See ~docs/tweens.org~ for patterns. + ** Easing exports ~ease-linear~, ~ease-quad-in~, ~ease-quad-out~, ~ease-quad-in-out~, ~ease-cubic-in~, ~ease-cubic-out~, ~ease-cubic-in-out~, ~ease-sine-in-out~, ~ease-expo-in~, ~ease-expo-out~, ~ease-expo-in-out~, ~ease-back-out~, ~ease-named~, ~ease-resolve~. diff --git a/docs/entities.org b/docs/entities.org index 3cdae6e..048cd8e 100644 --- a/docs/entities.org +++ b/docs/entities.org @@ -114,7 +114,8 @@ The engine recognizes these standard keys. Use them to integrate with the physic | ~#:on-ground?~ | boolean | Whether the entity is supported from below (set by ~detect-on-solid~): solid tile under the feet and/or standing on another solid entity when you pass the scene entity list. Use this to gate jump input. | | ~#:solid?~ | boolean | Whether this entity participates in entity-entity collision. If ~#t~, ~resolve-entity-collisions~ will check it against other solid entities. | | ~#:immovable?~ | boolean | If ~#t~ with ~#:solid? #t~, entity–entity resolution only moves the *other* entity (static platforms). Two overlapping immovable solids are not separated. | -| ~#:skip-pipelines~ | list of symbols | Optional. Each symbol names a physics step to skip for this entity (e.g. ~gravity~, ~velocity-x~). See ~docs/physics.org~. | +| ~#:skip-pipelines~ | list of symbols | Optional. Each symbol names a pipeline step to skip (e.g. ~gravity~, ~velocity-x~, ~tweens~). See ~docs/physics.org~ and ~docs/tweens.org~. | +| ~#:tween~ | tween struct or ~#f~ | Optional. When present, ~step-tweens~ auto-advances the tween each frame. Removed automatically when the tween finishes. See ~docs/tweens.org~. | | ~#:tile-id~ | integer | Sprite index in the tileset (1-indexed). Used by ~render-scene!~ when the scene has a tileset texture and tile metadata (from the tilemap or ~scene-tileset~). Updated automatically by animation (~animate-entity~). | | ~#:color~ | list | Optional ~(r g b)~ or ~(r g b a)~ (0–255 each). When ~#:tile-id~ is not drawn as a sprite (missing ~#:tile-id~, or no tileset texture), ~render-scene!~ fills the entity rect with this color. | | ~#:facing~ | number | Horizontal flip direction: ~1~ = right (default), ~-1~ = left. Used by renderer to flip sprite horizontally. Update when changing direction. | 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. |