Added tweens

1 files changed, 66 insertions, 9 deletions

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