From 618ed5fd6f5ae9c9f275c1e3cfb74762d7d51a01 Mon Sep 17 00:00:00 2001 From: Gene Pasquet Date: Tue, 7 Apr 2026 19:30:08 +0100 Subject: Added tweens --- docs/api.org | 75 ++++++++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 66 insertions(+), 9 deletions(-) (limited to 'docs/api.org') diff --git a/docs/api.org b/docs/api.org index f18b80a..f6cfe50 100644 --- a/docs/api.org +++ b/docs/api.org @@ -287,7 +287,7 @@ Returns the tile ID at grid position ~(col, row)~ across all layers. Returns ~0~ (import downstroke-entity) #+end_src -The entity module provides property list (plist) accessors for game objects. Entities are immutable plists, never modified in place. +The entity module provides property list (plist) accessors for game objects. Entities are immutable plists, never modified in place. It also defines ~entity-skips-pipeline?~ and the ~define-pipeline~ macro for frame pipeline steps that respect ~#:skip-pipelines~ (see ~docs/physics.org~ for the built-in physics step names). ** ~entity-ref~ @@ -344,6 +344,22 @@ Example: ; Equivalent to (entity-set player #:x (+ 10 (entity-ref player #:x 0))) #+end_src +** ~entity-skips-pipeline?~ + +#+begin_src scheme +(entity-skips-pipeline? entity step-symbol) +#+end_src + +Returns true if ~step-symbol~ appears in the entity’s ~#:skip-pipelines~ list (and that list is non-empty). The built-in physics step names are documented in ~docs/physics.org~; other engine modules may reserve additional symbols for their own frame phases (rendering, animation, etc.) using the same plist key. + +** ~define-pipeline~ + +#+begin_src scheme +(define-pipeline (procedure-name skip-symbol) (entity-formal extra-formal ...) body ...) +#+end_src + +Syntax for authors of per-entity pipeline steps: expands to a ~define~ that returns the **first** formal (the entity) unchanged when ~skip-symbol~ is listed in ~#:skip-pipelines~; otherwise runs ~body ...~ inside ~(let () ...)~. Used throughout ~downstroke-physics~; other modules can use it for consistent skip behavior. The procedure name and skip symbol differ when needed (e.g. ~detect-ground~ vs ~ground-detection~). + ** Shared Entity Keys All entities can have these keys. Not all are required: @@ -363,6 +379,7 @@ 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~) | | ~#:anim-name~ | symbol | Current animation name | | ~#:anim-frame~ | integer | Current frame index | | ~#:anim-tick~ | integer | Ticks in current frame | @@ -377,15 +394,19 @@ The physics module provides functions for movement, collision detection, and gro ** Physics Pipeline Order -The built-in physics runs in this order each frame: +The built-in physics functions are normally run in this order each frame (after reading input, before rendering): -1. ~apply-acceleration~ — consume ~#:ay~ into ~#:vy~ -2. ~apply-gravity~ — add gravity to ~#:vy~ -3. ~apply-velocity-x~ — move by ~#:vx~ -4. ~resolve-tile-collisions-x~ — snap against horizontal tile collisions -5. ~apply-velocity-y~ — move by ~#:vy~ -6. ~resolve-tile-collisions-y~ — snap against vertical tile collisions -7. ~detect-ground~ — set ~#:on-ground?~ if standing on a tile +1. ~apply-jump~ — if jump pressed and on ground, set ~#:ay~ +2. ~apply-acceleration~ — consume ~#:ay~ into ~#:vy~ +3. ~apply-gravity~ — add gravity to ~#:vy~ +4. ~apply-velocity-x~ — move by ~#:vx~ +5. ~resolve-tile-collisions-x~ — snap against horizontal tile collisions +6. ~apply-velocity-y~ — move by ~#:vy~ +7. ~resolve-tile-collisions-y~ — snap against vertical tile collisions +8. ~detect-ground~ — set ~#:on-ground?~ if standing on a tile +9. ~resolve-entity-collisions~ — push apart solid entities (whole list) + +Entities may list ~#:skip-pipelines~ to omit specific steps; see ~entity-skips-pipeline?~ under ~downstroke-entity~ and ~docs/physics.org~. (This separation ensures smooth sliding along walls.) @@ -963,6 +984,42 @@ Changes the music volume while it is playing. ~volume~ is 0.0 to 1.0. Releases all audio resources. Call at shutdown or in a cleanup hook. +* Tweens (~downstroke-tween~) + +#+begin_src scheme +(import downstroke-tween) +#+end_src + +Time-based interpolation of numeric entity properties. Library-only — call from ~update:~; see ~docs/tweens.org~ for patterns with ~#:skip-pipelines~. + +** ~make-tween~ + +#+begin_src scheme +(make-tween entity #!key props duration (delay 0) ease (on-complete #f)) +#+end_src + +| Keyword | Description | +|---------+-------------| +| ~props~ | Alist ~((#:key . target-number) ...)~ | +| ~duration~ | Milliseconds of interpolation after ~delay~ | +| ~delay~ | Initial wait in ms (default 0) | +| ~ease~ | Symbol (e.g. ~quad-in-out~) or ~(lambda (t) ...)~ with ~t~ in [0,1] | +| ~on-complete~ | Optional ~(lambda (entity) ...)~ once at completion | + +** ~tween-step~ + +#+begin_src scheme +(tween-step tween entity dt) +#+end_src + +Returns two values: updated tween struct and updated entity. ~dt~ is elapsed milliseconds for this frame. + +** ~tween-finished?~ / ~tween-active?~ + +** 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~. + * Animation (~downstroke-animation~) #+begin_src scheme -- cgit v1.2.3