Added tweens

1 files changed, 44 insertions, 13 deletions

diff --git a/docs/physics.org b/docs/physics.org
index a267d6d..2a82210 100644
--- a/docs/physics.org
+++ b/docs/physics.org
@@ -22,38 +22,69 @@ The =tilemap= argument is required by collision functions, since collision data
 
 * Physics Pipeline
 
-The canonical 9-step physics pipeline is:
+The canonical **per-entity** physics pipeline (what you typically call from =update:=) is:
 
 #+begin_src
-input
+apply-jump                  (set #:ay if jump pressed and on-ground)
   ↓
-apply-jump         (set #:ay if jump pressed and on-ground)
+apply-acceleration          (consume #:ay into #:vy)
   ↓
-apply-acceleration (consume #:ay into #:vy)
+apply-gravity               (add gravity constant to #:vy)
   ↓
-apply-gravity      (add gravity constant to #:vy)
+apply-velocity-x          (add #:vx to #:x)
   ↓
-apply-velocity-x   (add #:vx to #:x)
+resolve-tile-collisions-x   (snap off horizontal tiles, zero #:vx)
   ↓
-resolve-tile-collisions-x (snap off horizontal tiles, zero #:vx)
-  ↓
-apply-velocity-y   (add #:vy to #:y)
+apply-velocity-y          (add #:vy to #:y)
   ↓
 resolve-tile-collisions-y (snap off vertical tiles, zero #:vy)
   ↓
-detect-ground      (probe 1px below feet, set #:on-ground?)
-  ↓
-resolve-entity-collisions (push apart overlapping solid entities)
+detect-ground             (probe 1px below feet, set #:on-ground?)
   ↓
-render
+resolve-entity-collisions (push apart overlapping solid entities; whole list)
 #+end_src
 
+Input and rendering live **outside** this list — you read input first, then run the steps you need, then render.
+
 **Not all steps are needed for all game types.** See the examples section for three different patterns:
 
 - **Platformer**: uses all 9 steps
 - **Top-down**: skips gravity, acceleration, jump, ground detection
 - **Physics Sandbox**: uses all steps, applies them to multiple entities
 
+* Skipping steps (~#:skip-pipelines~)
+
+An entity may include ~#:skip-pipelines=, a list of **symbols** naming steps to **omit** for that entity only. Absent or empty means no steps are skipped.
+
+| Symbol | Skipped call |
+|--------+----------------|
+| ~jump~ | ~apply-jump~ |
+| ~acceleration~ | ~apply-acceleration~ |
+| ~gravity~ | ~apply-gravity~ |
+| ~velocity-x~ | ~apply-velocity-x~ |
+| ~velocity-y~ | ~apply-velocity-y~ |
+| ~tile-collisions-x~ | ~resolve-tile-collisions-x~ |
+| ~tile-collisions-y~ | ~resolve-tile-collisions-y~ |
+| ~ground-detection~ | ~detect-ground~ |
+| ~entity-collisions~ | participation in ~resolve-entity-collisions~ / ~resolve-pair~ |
+
+**Entity–entity collisions:** if *either* entity in a pair lists ~entity-collisions~ in ~#:skip-pipelines=, that pair is not resolved (no push-apart). Use this for “ghost” actors or scripted motion that should not participate in mutual solid resolution.
+
+**Legacy ~apply-velocity~:** skips each axis independently if ~velocity-x~ or ~velocity-y~ is listed.
+
+Helper: ~(entity-skips-pipeline? entity step-symbol)~ (from ~downstroke-entity~) returns ~#t~ if ~step-symbol~ is in the entity’s skip list.
+
+** ~define-pipeline~ (~downstroke-entity~)
+
+Physics steps are defined with ~(define-pipeline (procedure-name skip-symbol) (formals ...) body ...)~ from the entity module. The first formal must be the entity. The procedure name and skip symbol are separate so names like ~detect-ground~ can use the skip key ~ground-detection~. ~apply-velocity~ is still written by hand because it consults ~velocity-x~ and ~velocity-y~ independently.
+
+The renderer and other subsystems do **not** use ~#:skip-pipelines~ today; they run after your ~update:~ hook. If you add render-phase or animation-phase skips later, reuse the same plist key and helpers from ~downstroke-entity~ and document the new symbols alongside physics.
+
+Use cases:
+
+- **Tweens / knockback:** skip ~jump~, ~acceleration~, ~gravity~, ~velocity-x~, ~velocity-y~ while a tween drives ~#:x~ / ~#:y~, but keep tile resolution so the body does not rest inside walls.
+- **Top-down:** omit gravity, jump, acceleration, ground detection from your *call order*; you usually do not need ~#:skip-pipelines= unless some entities differ from others.
+
 * Pipeline Steps
 
 ** apply-jump