Work on demos

1 files changed, 18 insertions, 22 deletions

diff --git a/docs/physics.org b/docs/physics.org
index 2a82210..0eb9265 100644
--- a/docs/physics.org
+++ b/docs/physics.org
@@ -16,7 +16,7 @@ The =tilemap= argument is required by collision functions, since collision data
 - =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-ground= — probe 1px below feet to set #:on-ground?
+- =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
 - =aabb-overlap?= — pure boolean collision test (for queries, not resolution)
 
@@ -39,7 +39,7 @@ 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?)
+detect-on-solid          (tiles and/or other solids underfoot, set #:on-ground?)
   ↓
 resolve-entity-collisions (push apart overlapping solid entities; whole list)
 #+end_src
@@ -65,7 +65,7 @@ An entity may include ~#:skip-pipelines=, a list of **symbols** naming steps to
 | ~velocity-y~ | ~apply-velocity-y~ |
 | ~tile-collisions-x~ | ~resolve-tile-collisions-x~ |
 | ~tile-collisions-y~ | ~resolve-tile-collisions-y~ |
-| ~ground-detection~ | ~detect-ground~ |
+| ~on-solid~ | ~detect-on-solid~ |
 | ~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.
@@ -76,7 +76,7 @@ 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. 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.
+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 (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.
 
@@ -193,19 +193,19 @@ Velocity is zeroed to stop the entity from sliding. Call this immediately after
 
 Velocity is zeroed. Call this immediately after =apply-velocity-y=.
 
-** detect-ground
+** detect-on-solid
 
 #+begin_src scheme
-(detect-ground entity tilemap)
+(detect-on-solid entity tilemap #!optional other-entities)
 #+end_src
 
-**Reads**: =#:gravity?=, =#:x=, =#:y=, =#:width=, =#:height=
+**Reads**: =#:gravity?=, =#:x=, =#:y=, =#:width=, =#:height=, =#:vy=; when =other-entities= is passed, each other entity's =#:solid?=, position, and size
 
-**Writes**: =#:on-ground?= (set to #t if tile found 1px below feet, else #f)
+**Writes**: =#:on-ground?= (set to =#t= if supported by a solid tile probe and/or by another solid's top surface, else =#f=)
 
-**Description**: Probes 1 pixel directly below the entity's feet (bottom edge) to see if it's standing on a tile. The probe checks both corners of the entity's width to handle partial overlaps. Only works if =#:gravity?= is true.
+**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.
 
-Used by =apply-jump= to decide whether jump is allowed. Call this at the end of each physics frame, after all collision resolution.
+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.
 
 ** resolve-entity-collisions
 
@@ -219,11 +219,7 @@ Used by =apply-jump= to decide whether jump is allowed. Call this at the end of
 
 **Writes**: For colliding pairs: =#:x=, =#:y=, =#:vx=, =#:vy= (pushed apart, velocities set to ±1)
 
-**Description**: Performs all-pairs AABB overlap detection. For each pair of entities where BOTH have =#:solid? #t=, if they overlap:
-
-1. Calculate overlap on both X and Y axes
-2. Push apart along the axis with smaller overlap (to avoid getting stuck in corners)
-3. Set each entity's velocity along that axis to push them in opposite directions
+**Description**: Performs all-pairs AABB overlap detection. For each pair of entities where BOTH have =#:solid? #t=, if they overlap: if one has =#:immovable? #t=, only the other entity is displaced along the shallow overlap axis (and its velocity on that axis is zeroed); if both are immovable, the pair is skipped. Otherwise the two bodies are pushed apart along the smaller overlap axis and their velocities on that axis are set to ±1.
 
 Entities without =#:solid?= or with =#:solid? #f= are skipped. Returns a new entity list with collisions resolved.
 
@@ -334,7 +330,7 @@ update: (lambda (game dt)
          ;; Resolve tile collisions on y-axis
          (player (resolve-tile-collisions-y player tm))
          ;; Check if standing on ground
-         (player (detect-ground      player tm)))
+         (player (detect-on-solid      player tm)))
     ;; Update camera to follow player
     (let ((cam-x (max 0 (- (entity-ref player #:x 0) 300))))
       (camera-x-set! (scene-camera scene) cam-x))
@@ -353,7 +349,7 @@ update: (lambda (game dt)
 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-ground**: probe 1px below feet, set #:on-ground? for next frame's jump check
+10. **detect-on-solid**: set #:on-ground? from tiles and/or other solids (optional entity list), for next frame's jump check
 
 * Top-Down Example
 
@@ -412,7 +408,7 @@ update: (lambda (game dt)
       (lambda (e) (resolve-tile-collisions-x e tm))
       apply-velocity-y
       (lambda (e) (resolve-tile-collisions-y e tm))
-      (lambda (e) (detect-ground e tm)))
+      (lambda (e) (detect-on-solid e tm)))
     ;; Then resolve entity-entity collisions
     (scene-resolve-collisions scene)))
 #+end_src
@@ -423,7 +419,7 @@ update: (lambda (game dt)
    - =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-ground= (set #:on-ground? for next frame)
+   - =detect-on-solid= (set #:on-ground? for next frame)
 
 2. **scene-resolve-collisions**: after all entities are moved and collided with tiles, resolve entity-entity overlaps (boxes pushing apart)
 
@@ -451,11 +447,11 @@ Same for other functions that take tilemap. The =scene-update-entities= macro ap
 ;; ... rest of pipeline
 #+end_src
 
-You only need =apply-jump=, =apply-acceleration=, and =apply-gravity=. =detect-ground= is needed to prevent double-jumping.
+You only need =apply-jump=, =apply-acceleration=, and =apply-gravity=. =detect-on-solid= is needed to prevent double-jumping.
 
 ** No Gravity
 
-For top-down or shmup games, skip =apply-jump=, =apply-acceleration=, =apply-gravity=, and =detect-ground=. Just do velocity + tile collision.
+For top-down or shmup games, skip =apply-jump=, =apply-acceleration=, =apply-gravity=, and =detect-on-solid=. Just do velocity + tile collision.
 
 ** Knockback
 
@@ -510,7 +506,7 @@ For large games, consider spatial partitioning (grid, quadtree) to cull entity p
 
 ** Double-Jump / Can't Jump
 
-- Ensure =detect-ground= is called after all collision resolution
+- 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