From afc30a12e25215ff5e9226c3b4f8fd127d9a4d68 Mon Sep 17 00:00:00 2001 From: Gene Pasquet Date: Wed, 8 Apr 2026 07:08:54 +0100 Subject: Move the engine-update to the scene --- docs/physics.org | 250 ++++++++++++++++++++++++------------------------------- 1 file changed, 108 insertions(+), 142 deletions(-) (limited to 'docs/physics.org') diff --git a/docs/physics.org b/docs/physics.org index e5b3749..81c57b8 100644 --- a/docs/physics.org +++ b/docs/physics.org @@ -3,54 +3,72 @@ * Overview -The downstroke physics system is **explicit**: YOU call each physics step in your =update:= hook. This design gives you full control over the game's behavior—skip gravity for top-down games, skip tile collision for shmups, or skip entity collision for single-player platformers. +With the default =engine-update:= hook (=default-engine-update= from =downstroke-engine=), the physics pipeline runs **automatically** every frame *before* your =update:= hook. Input is processed first, then =engine-update= integrates motion and collisions, then =update:= runs so your game logic sees resolved positions and =#:on-ground?=. -All physics functions are **functional and immutable**: they take an entity (plist) and return a NEW plist with updated values. No side effects. This makes it easy to reason about physics state and compose multiple steps together. +Set =engine-update: #f= on =make-game= to disable the built-in pass, or pass a custom =(lambda (game dt) ...)= to drive your own order — useful for shmups, menus, or experiments. -The =tilemap= argument is required by collision functions, since collision data lives in the tilemap metadata (which tiles are solid, which are not). +All physics functions are **functional and immutable**: per-entity steps take an entity (plist) plus the current scene and frame =dt=, and return a NEW plist. Bulk steps take the entity list only. No in-place mutation of entities. + +Tile collision reads solid flags from the tilemap embedded in the scene (=scene-tilemap=). ** Key Physics Functions -- =apply-jump= — trigger jump acceleration if on ground +- =step-tweens= — advance =#:tween= (see =docs/tweens.org=) - =apply-acceleration= — consume one-shot #:ay into velocity - =apply-gravity= — add gravity to falling entities - =apply-velocity-x=, =apply-velocity-y= — move entity by velocity - =resolve-tile-collisions-x=, =resolve-tile-collisions-y= — snap entity off tiles on collision -- =detect-on-solid= — set =#:on-ground?= from tiles below feet and/or solid entities underfoot -- =resolve-entity-collisions= — all-pairs AABB push-apart for solid entities +- =detect-on-solid= — set =#:on-ground?= from tiles below feet and/or solid entities in the scene list +- =resolve-entity-collisions= — all-pairs AABB push-apart for solid entities (=entities= only) +- =sync-groups= — group follow origins (=entities= only) - =aabb-overlap?= — pure boolean collision test (for queries, not resolution) +Jumping is **game logic**: set =#:ay= in =update:= (e.g. =(- *jump-force*)=) when the player jumps; there is no =apply-jump=. + * Physics Pipeline -The canonical **per-entity** physics pipeline (what you typically call from =update:=) is: +The canonical order inside =default-engine-update= (and the recommended order when composing steps yourself) is: #+begin_src -apply-jump (set #:ay if jump pressed and on-ground) +Frame loop (see =docs/api.org= =game-run!=): + input + ↓ + engine-update (=default-engine-update= by default) + ↓ + update (your game logic: set #:vx, #:vy, #:ay, …) + ↓ + camera follow → render + +Inside =default-engine-update= (per entity, then bulk): +step-tweens (advance #:tween) ↓ apply-acceleration (consume #:ay into #: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) ↓ -apply-velocity-y (add #:vy to #:y) +apply-velocity-y (add #:vy to #:y) + ↓ +resolve-tile-collisions-y (snap off vertical tiles, zero #:vy) ↓ -resolve-tile-collisions-y (snap off vertical tiles, zero #:vy) +detect-on-solid (tiles and/or scene entities underfoot → #:on-ground?) ↓ -detect-on-solid (tiles and/or other solids underfoot, set #:on-ground?) +resolve-entity-collisions (whole entity list) ↓ -resolve-entity-collisions (push apart overlapping solid entities; whole list) +sync-groups (whole entity list) #+end_src -Input and rendering live **outside** this list — you read input first, then run the steps you need, then render. +Per-entity steps use signature =(entity scene dt)=. Bulk steps =(resolve-entity-collisions entities)= and =(sync-groups entities)= apply to the full list; use =scene-transform-entities=. -**Not all steps are needed for all game types.** See the examples section for three different patterns: +**Not all steps apply to every entity** (=#:skip-pipelines=, guards like =#:gravity?=, missing tilemap). See the examples section for patterns: -- **Platformer**: uses all 9 steps -- **Top-down**: skips gravity, acceleration, jump, ground detection -- **Physics Sandbox**: uses all steps, applies them to multiple entities +- **Platformer**: default =engine-update=; =update:= sets =#:vx= and =#:ay= for jumps +- **Top-down**: same auto pipeline; entities without =#:gravity?= skip gravity/acceleration/ground +- **Physics Sandbox**: default or custom =scene-map-entities= with the same step order +- **Custom / shmup**: =engine-update: #f= and move entities in =update:= * Skipping steps (~#:skip-pipelines~) @@ -58,7 +76,6 @@ An entity may include ~#:skip-pipelines=, a list of **symbols** naming steps to | Symbol | Skipped call | |--------+----------------| -| ~jump~ | ~apply-jump~ | | ~acceleration~ | ~apply-acceleration~ | | ~gravity~ | ~apply-gravity~ | | ~velocity-x~ | ~apply-velocity-x~ | @@ -67,6 +84,7 @@ An entity may include ~#:skip-pipelines=, a list of **symbols** naming steps to | ~tile-collisions-y~ | ~resolve-tile-collisions-y~ | | ~on-solid~ | ~detect-on-solid~ | | ~entity-collisions~ | participation in ~resolve-entity-collisions~ / ~resolve-pair~ | +| ~tweens~ | ~step-tweens~ (see ~downstroke-tween~) | **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. @@ -76,57 +94,33 @@ Helper: ~(entity-skips-pipeline? entity step-symbol)~ (from ~downstroke-entity~) ** ~define-pipeline~ (~downstroke-entity~) -Physics steps are defined with ~(define-pipeline (procedure-name skip-symbol) (formals ...) body ...)~ from the entity module, optionally with ~guard: expr~ before ~body ...~: when the guard is false, the entity is returned unchanged before the body runs. The first formal must be the entity. The procedure name and skip symbol are separate (e.g. ~detect-on-solid~ vs ~on-solid~). ~apply-velocity~ is still written by hand because it consults ~velocity-x~ and ~velocity-y~ independently. +Physics steps are defined with ~(define-pipeline (procedure-name skip-symbol) (entity scene dt) body ...)~ from the entity module, optionally with ~guard: expr~ before ~body ...~: when the guard is false, the entity is returned unchanged before the body runs. The first formal must be the entity; ~scene~ and ~dt~ are standard for pipeline uniformity. The procedure name and skip symbol are separate (e.g. ~detect-on-solid~ vs ~on-solid~). ~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. +- **Tweens / knockback:** skip ~acceleration~, ~gravity~, ~velocity-x~, ~velocity-y~ (and often ~tweens~ is *not* skipped so ~step-tweens~ still runs) while a tween drives ~#:x~ / ~#:y~, but keep tile resolution so the body does not rest inside walls. +- **Top-down:** entities without ~#:gravity?~ skip gravity, acceleration, and ground detection automatically; you usually do not need ~#:skip-pipelines= unless some entities differ from others. * Pipeline Steps -** apply-jump - -#+begin_src scheme -(apply-jump entity jump-pressed?) -#+end_src - -**Signature**: Takes an entity plist and a boolean (jump button state). - -**Reads**: =#:on-ground?= (must be #t), =#:jump-force= (default: 15 pixels/frame²) - -**Writes**: =#:ay= (acceleration-y), set to =(- jump-force)= if jump pressed and on ground, else #:ay is left untouched - -**Description**: Sets up a one-shot vertical acceleration if the jump button was just pressed AND the entity is standing on ground. The acceleration is consumed on the next frame by =apply-acceleration=. Do not call this repeatedly in a loop; call it once per frame. - -#+begin_src scheme -;; Example: -(define entity (list #:type 'player #:on-ground? #t #:jump-force 15)) -(define jumped (apply-jump entity #t)) -;; jumped has #:ay -15 - -(define jumped2 (apply-jump entity #f)) -;; jumped2 is unchanged (not on ground) -#+end_src - ** apply-acceleration #+begin_src scheme -(apply-acceleration entity) +(apply-acceleration entity scene dt) #+end_src **Reads**: =#:ay= (default 0), =#:vy= (default 0), =#:gravity?= to decide whether to consume **Writes**: =#:vy= (adds #:ay to it), =#:ay= (reset to 0) -**Description**: Consumes the one-shot acceleration into velocity. Used for jumps and other instant bursts. Only works if =#:gravity?= is true (gravity-enabled entities). Call once per frame, after =apply-jump=. +**Description**: Consumes the one-shot acceleration into velocity. Used for jumps (set =#:ay= in =update:=) and other instant bursts. Only works if =#:gravity?= is true (gravity-enabled entities). =scene= and =dt= are unused but required for the pipeline signature. ** apply-gravity #+begin_src scheme -(apply-gravity entity) +(apply-gravity entity scene dt) #+end_src **Reads**: =#:gravity?= (boolean), =#:vy= (default 0) @@ -138,7 +132,7 @@ Use cases: ** apply-velocity-x #+begin_src scheme -(apply-velocity-x entity) +(apply-velocity-x entity scene dt) #+end_src **Reads**: =#:vx= (default 0), =#:x= (default 0) @@ -150,7 +144,7 @@ Use cases: ** apply-velocity-y #+begin_src scheme -(apply-velocity-y entity) +(apply-velocity-y entity scene dt) #+end_src **Reads**: =#:vy= (default 0), =#:y= (default 0) @@ -162,7 +156,7 @@ Use cases: ** resolve-tile-collisions-x #+begin_src scheme -(resolve-tile-collisions-x entity tilemap) +(resolve-tile-collisions-x entity scene dt) #+end_src **Reads**: =#:x=, =#:y=, =#:width=, =#:height=, =#:vx= @@ -179,7 +173,7 @@ Velocity is zeroed to stop the entity from sliding. Call this immediately after ** resolve-tile-collisions-y #+begin_src scheme -(resolve-tile-collisions-y entity tilemap) +(resolve-tile-collisions-y entity scene dt) #+end_src **Reads**: =#:x=, =#:y=, =#:width=, =#:height=, =#:vy= @@ -196,16 +190,16 @@ Velocity is zeroed. Call this immediately after =apply-velocity-y=. ** detect-on-solid #+begin_src scheme -(detect-on-solid entity tilemap #!optional other-entities) +(detect-on-solid entity scene dt) #+end_src -**Reads**: =#:gravity?=, =#:x=, =#:y=, =#:width=, =#:height=, =#:vy=; when =other-entities= is passed, each other entity's =#:solid?=, position, and size +**Reads**: =#:gravity?=, =#:x=, =#:y=, =#:width=, =#:height=, =#:vy=; other entities from =(scene-entities scene)= for solid support **Writes**: =#:on-ground?= (set to =#t= if supported by a solid tile probe and/or by another solid's top surface, else =#f=) -**Description**: Despite the =?=-suffix, this returns an **updated entity** (it sets =#:on-ground?=), not a boolean. Ground is **either** (1) a solid tile one pixel below the feet (probe at both lower corners of the AABB, same as before), **or** (2) when =other-entities= is a non-=#f= list, resting on another solid entity's **top** (horizontal overlap, feet within a few pixels of that entity's top, and vertical speed small enough that we treat the body as supported—so moving platforms and crates count). Omit =other-entities= (or pass =#f=) to keep tile-only behavior. Only runs when =#:gravity?= is true. If =tilemap= is =#f=, the tile probe is skipped and only entity support applies when a list is provided. +**Description**: Despite the =?=-suffix, this returns an **updated entity** (it sets =#:on-ground?=), not a boolean. Ground is **either** (1) a solid tile one pixel below the feet (probe at both lower corners of the AABB), **or** (2) resting on another solid entity's **top** from the scene list (horizontal overlap, feet within a few pixels of that entity's top, and vertical speed small enough that we treat the body as supported—so moving platforms and crates count). If =scene-tilemap= is =#f=, the tile probe is skipped; entity–entity support still applies when other solids exist in the list. Only runs when =#:gravity?= is true. -Used by =apply-jump= (via =#:on-ground?= on the **next** frame). Call **after** tile collision and **after** =resolve-entity-collisions= when using entity support, so positions and velocities are settled. +Use =#:on-ground?= in =update:= to gate jump input; in =default-engine-update= this step runs **after** tile collision and **before** =resolve-entity-collisions= (see engine order). If you need ground detection to account for entity push-apart first, use a custom =engine-update= and call =detect-on-solid= after =resolve-entity-collisions=. ** resolve-entity-collisions @@ -299,83 +293,52 @@ The push-apart is along the **minimum penetration axis** (X or Y, whichever over * Platformer Example -A minimal platformer with a player, gravity, jumping, and tile collisions: +A minimal platformer with a player, gravity, jumping, and tile collisions. Physics runs in =default-engine-update=; =update:= is input → intent only: #+begin_src scheme +;; Omit engine-update: or use default — physics runs automatically before this hook. update: (lambda (game dt) (let* ((input (game-input game)) (scene (game-scene game)) - (tm (scene-tilemap scene)) (player (car (scene-entities scene))) - ;; Set horizontal velocity based on input + (jump? (and (input-pressed? input 'a) + (entity-ref player #:on-ground? #f))) (player (entity-set player #:vx (cond ((input-held? input 'left) -3) ((input-held? input 'right) 3) - (else 0)))) - ;; Play sound if jump pressed - (_ (when (and (input-pressed? input 'a) - (entity-ref player #:on-ground? #f)) - (play-sound 'jump))) - ;; Apply jump acceleration if button pressed - (player (apply-jump player (input-pressed? input 'a))) - ;; Consume #:ay into #:vy - (player (apply-acceleration player)) - ;; Apply gravity constant - (player (apply-gravity player)) - ;; Move horizontally - (player (apply-velocity-x player)) - ;; Resolve tile collisions on x-axis - (player (resolve-tile-collisions-x player tm)) - ;; Move vertically - (player (apply-velocity-y player)) - ;; Resolve tile collisions on y-axis - (player (resolve-tile-collisions-y player tm)) - ;; Check if standing on ground - (player (detect-on-solid player tm))) - (game-scene-set! game - (update-scene scene entities: (list player))))) + (else 0))))) + (when jump? (play-sound 'jump)) + (let ((player (if jump? + (entity-set player #:ay (- *jump-force*)) + player))) + (game-scene-set! game + (update-scene scene entities: (list player)))))) #+end_src +Import =*jump-force*= from =downstroke-physics= (or use a literal such as =-15= for =#:ay=). + ** Step-by-Step 1. **Set #:vx** from input (left = -3, right = +3, idle = 0) -2. **Check jump**: if A button pressed and on-ground, sound plays -3. **apply-jump**: if A pressed and on-ground, set #:ay to -15 (jump force) -4. **apply-acceleration**: consume #:ay into #:vy (so #:ay becomes 0) -5. **apply-gravity**: add 1 to #:vy each frame (falling acceleration) -6. **apply-velocity-x**: add #:vx to #:x (move left/right) -7. **resolve-tile-collisions-x**: if hit a tile, snap #:x and zero #:vx -8. **apply-velocity-y**: add #:vy to #:y (move up/down) -9. **resolve-tile-collisions-y**: if hit a tile, snap #:y and zero #:vy -10. **detect-on-solid**: set #:on-ground? from tiles and/or other solids (optional entity list), for next frame's jump check +2. **Jump**: if A pressed and =#:on-ground?= (already updated for this frame — your =update:= runs after =engine-update=), play sound and set =#:ay= to =(- *jump-force*)= +3. **Next frame’s =engine-update=** runs =apply-acceleration= through =sync-groups= as documented above * Top-Down Example -A top-down game with no gravity, no jumping, and free 4-way movement: +A top-down game with no gravity and free 4-way movement. Give the player =#:gravity? #f= so acceleration, gravity, and ground detection no-op inside =default-engine-update=: #+begin_src scheme update: (lambda (game dt) (let* ((input (game-input game)) (scene (game-scene game)) - (tm (scene-tilemap scene)) (player (car (scene-entities scene))) - ;; Combine directional input (dx (+ (if (input-held? input 'left) -3 0) (if (input-held? input 'right) 3 0))) (dy (+ (if (input-held? input 'up) -3 0) (if (input-held? input 'down) 3 0))) - ;; Set both velocities - (player (entity-set (entity-set player #:vx dx) #:vy dy)) - ;; Move horizontally - (player (apply-velocity-x player)) - ;; Resolve tile collisions on x-axis - (player (resolve-tile-collisions-x player tm)) - ;; Move vertically - (player (apply-velocity-y player)) - ;; Resolve tile collisions on y-axis - (player (resolve-tile-collisions-y player tm))) - ;; Update camera to follow player + (player (entity-set (entity-set player #:vx dx) #:vy dy))) + ;; Camera follow still runs after update: in game-run! (camera-x-set! (scene-camera scene) (max 0 (- (entity-ref player #:x 0) 300))) (game-scene-set! game (update-scene scene entities: (list player))))) @@ -384,72 +347,75 @@ update: (lambda (game dt) ** Step-by-Step 1. **Read input**: combine left/right into dx, up/down into dy -2. **Set velocity**: both #:vx and #:vy based on input -3. **apply-velocity-x** and **resolve-tile-collisions-x**: move and collide horizontally -4. **apply-velocity-y** and **resolve-tile-collisions-y**: move and collide vertically -5. **No gravity, no jumping, no ground detection**: top-down games don't need these +2. **Set velocity**: both #:vx and #:vy based on input; the next =engine-update= applies velocity and tile collision +3. **No gravity**: =#:gravity? #f= skips =apply-acceleration=, =apply-gravity=, =detect-on-solid= -The pipeline is much simpler because there's no vertical acceleration to manage. +The built-in pipeline still runs; most steps no-op or pass through for non-gravity entities. * Physics Sandbox Example -Multiple entities falling and colliding with each other: +The real =demo/sandbox.scm= relies on =default-engine-update= for boxes, rafts, and tile collision; =update:= only runs per-entity AI (e.g. bots) via =scene-map-entities=. + +If you **replace** =engine-update= with your own procedure, a full multi-entity pass looks like this (same step order as =default-engine-update=, minus tweens/sync if you omit them): #+begin_src scheme -update: (lambda (game dt) - (let* ((scene (game-scene game)) - (tm (scene-tilemap scene))) - ;; Apply physics to all entities in one pass, then resolve entity-entity collisions - (scene-transform-entities - (scene-map-entities scene - apply-gravity - apply-velocity-x - (lambda (e) (resolve-tile-collisions-x e tm)) - apply-velocity-y - (lambda (e) (resolve-tile-collisions-y e tm)) - (lambda (e) (detect-on-solid e tm))) - resolve-entity-collisions))) +(define (my-engine-update game dt) + (let ((scene (game-scene game))) + (when scene + (game-scene-set! game + (scene-transform-entities + (scene-map-entities scene + (lambda (e) (apply-gravity e scene dt)) + (lambda (e) (apply-velocity-x e scene dt)) + (lambda (e) (resolve-tile-collisions-x e scene dt)) + (lambda (e) (apply-velocity-y e scene dt)) + (lambda (e) (resolve-tile-collisions-y e scene dt)) + (lambda (e) (detect-on-solid e scene dt))) + resolve-entity-collisions))))) #+end_src +Prefer reusing =default-engine-update= unless you need a different order (e.g. =detect-on-solid= after entity collisions). A complete custom hook should also run =step-tweens= first and =sync-groups= last, matching =engine.scm=. + ** step-by-step -1. **scene-map-entities**: applies each step to all entities in order +1. **scene-map-entities**: applies each step to all entities in order (snippet above starts at gravity for brevity) - =apply-gravity= (all entities fall) - =apply-velocity-x=, =resolve-tile-collisions-x= (move and collide on x-axis) - =apply-velocity-y=, =resolve-tile-collisions-y= (move and collide on y-axis) - - =detect-on-solid= (set #:on-ground? for next frame) + - =detect-on-solid= (set #:on-ground?) 2. **scene-transform-entities** with **resolve-entity-collisions**: after all entities are moved and collided with tiles, resolve entity-entity overlaps (boxes pushing apart) -This pattern is efficient for sandbox simulations: apply the same pipeline to all entities, then resolve inter-entity collisions once. +This pattern matches how multiple movers interact in the sandbox demo, except the demo uses the built-in =default-engine-update= instead of a hand-rolled hook. -** Lambdas with Tilemap +** Capturing =scene= and =dt= -Notice that =resolve-tile-collisions-x= needs the tilemap argument, so it's wrapped in a lambda: +=scene-map-entities= passes only each entity into the step. Per-entity physics steps take =(entity scene dt)=, so wrap them: #+begin_src scheme -(lambda (e) (resolve-tile-collisions-x e tm)) +(lambda (e) (resolve-tile-collisions-x e scene dt)) #+end_src -Same for other functions that take tilemap. The =scene-map-entities= macro applies each function to all entities, so you wrap single-argument functions in a lambda to capture the tilemap. +Use the same =dt= (milliseconds) that =game-run!= passes to your hooks. * Common Patterns ** Jumping #+begin_src scheme -;; In update: -(player (apply-jump player (input-pressed? input 'jump))) -(player (apply-acceleration player)) -(player (apply-gravity player)) -;; ... rest of pipeline +;; In update: (after physics, #:on-ground? is current) +(let ((jump? (and (input-pressed? input 'a) + (entity-ref player #:on-ground? #f)))) + (if jump? + (entity-set player #:ay (- *jump-force*)) + player)) #+end_src -You only need =apply-jump=, =apply-acceleration=, and =apply-gravity=. =detect-on-solid= is needed to prevent double-jumping. +=*jump-force*= (default 15) is exported from =downstroke-physics=. =apply-acceleration= and gravity run inside =default-engine-update= on the following frame. ** No Gravity -For top-down or shmup games, skip =apply-jump=, =apply-acceleration=, =apply-gravity=, and =detect-on-solid=. Just do velocity + tile collision. +For top-down games, use =#:gravity? #f= on movers so acceleration, gravity, and ground detection no-op. For shmups or fully custom motion, use =engine-update: #f= and move entities in =update:=. ** Knockback @@ -504,9 +470,9 @@ For large games, consider spatial partitioning (grid, quadtree) to cull entity p ** Double-Jump / Can't Jump -- Ensure =detect-on-solid= is called after tile collision and, when using the optional entity list, after =resolve-entity-collisions= -- Verify =#:on-ground?= is checked in =apply-jump= (not hardcoded) -- Make sure you're checking =input-pressed?= (not =input-held?=) for jump +- Ensure =#:on-ground?= is set: with =default-engine-update=, =detect-on-solid= runs each frame; for standing on other solids, note it runs *before* =resolve-entity-collisions= in the default order (see *detect-on-solid* above) +- Gate jump in =update:= with =#:on-ground?= and =input-pressed?= (not =input-held?=) +- Set =#:ay= only on the jump frame; =apply-acceleration= clears =#:ay= when it runs ** Entity Slides Through Walls -- cgit v1.2.3