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