#+title: Physics System
#+author: Downstroke Contributors

* 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.

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.

The =tilemap= argument is required by collision functions, since collision data lives in the tilemap metadata (which tiles are solid, which are not).

** Key Physics Functions

- =apply-jump= — trigger jump acceleration if on ground
- =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-ground= — probe 1px below feet to set #:on-ground?
- =resolve-entity-collisions= — all-pairs AABB push-apart for solid entities
- =aabb-overlap?= — pure boolean collision test (for queries, not resolution)

* Physics Pipeline

The canonical **per-entity** physics pipeline (what you typically call from =update:=) is:

#+begin_src
apply-jump                  (set #:ay if jump pressed and on-ground)
  ↓
apply-acceleration          (consume #:ay into #:vy)
  ↓
apply-gravity               (add gravity constant to #:vy)
  ↓
apply-velocity-x          (add #:vx to #:x)
  ↓
resolve-tile-collisions-x   (snap off horizontal tiles, zero #:vx)
  ↓
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; 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

#+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)
#+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=.

** apply-gravity

#+begin_src scheme
(apply-gravity entity)
#+end_src

**Reads**: =#:gravity?= (boolean), =#:vy= (default 0)

**Writes**: =#:vy= (adds 1 pixel/frame²)

**Description**: Applies a constant gravitational acceleration. The gravity constant is =*gravity* = 1= pixel per frame per frame. Only applies if =#:gravity?= is true. Safe to call every frame.

** apply-velocity-x

#+begin_src scheme
(apply-velocity-x entity)
#+end_src

**Reads**: =#:vx= (default 0), =#:x= (default 0)

**Writes**: =#:x= (adds #:vx to it)

**Description**: Moves the entity horizontally by its velocity. Call once per frame, before =resolve-tile-collisions-x=.

** apply-velocity-y

#+begin_src scheme
(apply-velocity-y entity)
#+end_src

**Reads**: =#:vy= (default 0), =#:y= (default 0)

**Writes**: =#:y= (adds #:vy to it)

**Description**: Moves the entity vertically by its velocity. Call once per frame, before =resolve-tile-collisions-y=.

** resolve-tile-collisions-x

#+begin_src scheme
(resolve-tile-collisions-x entity tilemap)
#+end_src

**Reads**: =#:x=, =#:y=, =#:width=, =#:height=, =#:vx=

**Writes**: =#:x= (snapped to tile edge), =#:vx= (zeroed if collision occurs)

**Description**: Detects all solid tiles overlapping the entity's AABB and snaps the entity to the nearest tile edge on the X-axis. If a collision is found:

- **Moving right** (vx > 0): entity's right edge is snapped to the left edge of the tile (position = tile-x - width)
- **Moving left** (vx < 0): entity's left edge is snapped to the right edge of the tile (position = tile-x + tile-width)

Velocity is zeroed to stop the entity from sliding. Call this immediately after =apply-velocity-x=.

** resolve-tile-collisions-y

#+begin_src scheme
(resolve-tile-collisions-y entity tilemap)
#+end_src

**Reads**: =#:x=, =#:y=, =#:width=, =#:height=, =#:vy=

**Writes**: =#:y= (snapped to tile edge), =#:vy= (zeroed if collision occurs)

**Description**: Detects all solid tiles overlapping the entity's AABB and snaps the entity to the nearest tile edge on the Y-axis. If a collision is found:

- **Moving down** (vy > 0): entity's bottom edge is snapped to the top edge of the tile (position = tile-y - height)
- **Moving up** (vy < 0): entity's top edge is snapped to the bottom edge of the tile (position = tile-y + tile-height)

Velocity is zeroed. Call this immediately after =apply-velocity-y=.

** detect-ground

#+begin_src scheme
(detect-ground entity tilemap)
#+end_src

**Reads**: =#:gravity?=, =#:x=, =#:y=, =#:width=, =#:height=

**Writes**: =#:on-ground?= (set to #t if tile found 1px below feet, 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.

Used by =apply-jump= to decide whether jump is allowed. Call this at the end of each physics frame, after all collision resolution.

** resolve-entity-collisions

#+begin_src scheme
(resolve-entity-collisions entities)
#+end_src

**Input**: A list of entity plists

**Reads**: For each entity: =#:solid?=, =#:x=, =#:y=, =#:width=, =#:height=, =#:vx=, =#:vy=

**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

Entities without =#:solid?= or with =#:solid? #f= are skipped. Returns a new entity list with collisions resolved.

This is relatively expensive: O(n²) for n entities. Use only when entity count is low (< 100) or for game objects where push-apart is desired.

** scene-resolve-collisions

#+begin_src scheme
(scene-resolve-collisions scene)
#+end_src

**Description**: Convenience wrapper. Extracts all entities from the scene, passes them to =resolve-entity-collisions=, and updates the scene in place. Modifies the scene.

** aabb-overlap?

#+begin_src scheme
(aabb-overlap? x1 y1 w1 h1 x2 y2 w2 h2)
#+end_src

**Returns**: Boolean (#t if overlapping, #f if separated or touching)

**Description**: Pure collision test for two axis-aligned bounding boxes. Does not modify any state. Useful for manual collision queries (e.g., "did bullet hit enemy?") where you want to decide the response manually rather than using push-apart.

#+begin_src scheme
;; Example: check if player overlaps enemy
(if (aabb-overlap? (entity-ref player #:x 0) (entity-ref player #:y 0)
                   (entity-ref player #:width 0) (entity-ref player #:height 0)
                   (entity-ref enemy #:x 0) (entity-ref enemy #:y 0)
                   (entity-ref enemy #:width 0) (entity-ref enemy #:height 0))
    (do-damage!))
#+end_src

* Tile Collision Model

Tiles come from **TMX maps** loaded by the tilemap module. The tilemap parses the XML and builds a 2D tile grid. Each cell references a tile ID from the tileset.

**Solid tiles** are identified by **tile metadata** in the TSX tileset (defined in Tiled editor). The physics module checks each tile to see if it has collision metadata. Tiles with no metadata are treated as non-solid background tiles.

** How Collision Works

1. Entity's AABB (x, y, width, height) is used to compute all overlapping tile cells
2. For each cell, the physics module queries the tilemap: "does this cell have a solid tile?"
3. If yes, the entity is snapped to the edge of that tile in the axis being resolved
4. Velocity is zeroed in that axis to prevent sliding

** Why X and Y are Separate

Tile collisions are resolved in two passes:

#+begin_src
apply-velocity-x → resolve-tile-collisions-x → apply-velocity-y → resolve-tile-collisions-y
#+end_src

This prevents a common platformer bug: if you moved and collided on both axes at once, you could get "corner clipped" (stuck in a diagonal corner). By separating X and Y, you guarantee the entity snaps cleanly.

* Entity-Entity Collision

Entity-entity collisions are for when two **game objects** overlap: a player and an enemy, two boxes stacked, etc.

=resolve-entity-collisions= does all-pairs AABB checks. Any entity with =#:solid? #t= that overlaps another solid entity is pushed apart.

The push-apart is along the **minimum penetration axis** (X or Y, whichever overlap is smaller). Entities are pushed in opposite directions by half the overlap distance, and their velocities are set to ±1 to prevent stacking.

** When to Use

- **Physics sandbox**: multiple boxes/balls that should bounce apart
- **Solid obstacles**: pushable crates that block the player
- **Knockback**: enemies that push back when hit

** When NOT to Use

- **Trigger zones**: enemies that should detect the player without colliding — use =aabb-overlap?= manually
- **Bullets**: should pass through enemies — don't mark bullet as solid, use =aabb-overlap?= to check hits
- **High entity count**: 100+ entities = O(n²) is too slow

* Platformer Example

A minimal platformer with a player, gravity, jumping, and tile collisions:

#+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)))
         ;; Set horizontal velocity based on input
         (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-ground      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))
    ;; Store updated player back in scene
    (scene-entities-set! scene (list player))))
#+end_src

** 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-ground**: probe 1px below feet, set #:on-ground? for next frame's jump check

* Top-Down Example

A top-down game with no gravity, no jumping, and free 4-way movement:

#+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
    (camera-x-set! (scene-camera scene) (max 0 (- (entity-ref player #:x 0) 300)))
    (camera-y-set! (scene-camera scene) (max 0 (- (entity-ref player #:y 0) 200)))
    ;; Store updated player back in scene
    (scene-entities-set! scene (list player))))
#+end_src

** 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

The pipeline is much simpler because there's no vertical acceleration to manage.

* Physics Sandbox Example

Multiple entities falling and colliding with each other:

#+begin_src scheme
update: (lambda (game dt)
  (let* ((scene (game-scene game))
         (tm    (scene-tilemap scene)))
    ;; Apply physics to all entities in one pass
    (scene-update-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-ground e tm)))
    ;; Then resolve entity-entity collisions
    (scene-resolve-collisions scene)))
#+end_src

** step-by-step

1. **scene-update-entities**: applies each step to all entities in order
   - =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)

2. **scene-resolve-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.

** Lambdas with Tilemap

Notice that =resolve-tile-collisions-x= needs the tilemap argument, so it's wrapped in a lambda:

#+begin_src scheme
(lambda (e) (resolve-tile-collisions-x e tm))
#+end_src

Same for other functions that take tilemap. The =scene-update-entities= macro applies each function to all entities, so you wrap single-argument functions in a lambda to capture the tilemap.

* 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
#+end_src

You only need =apply-jump=, =apply-acceleration=, and =apply-gravity=. =detect-ground= 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.

** Knockback

Set #:vx or #:vy directly to push an entity:

#+begin_src scheme
(entity-set enemy #:vx -5)  ;; Push left
#+end_src

Gravity will resume on the next frame if =#:gravity?= is #t.

** Trigger Zones

For areas that don't collide but detect presence (spawn zones, damage zones):

#+begin_src scheme
;; In update:
(if (aabb-overlap? (entity-ref trigger #:x 0) (entity-ref trigger #:y 0)
                   (entity-ref trigger #:width 0) (entity-ref trigger #:height 0)
                   (entity-ref player #:x 0) (entity-ref player #:y 0)
                   (entity-ref player #:width 0) (entity-ref player #:height 0))
    (on-trigger-enter! player))
#+end_src

Don't mark the trigger as solid; just use =aabb-overlap?= to query.

** Slopes and Ramps

The current tile collision system is AABB-based and does not support slopes. All tiles are axis-aligned rectangles. To simulate slopes, you can:

1. Use small tiles to approximate a slope (many tiny tiles at angles)
2. Post-process the player's position after collision (rotate velocity vector)
3. Use a custom collision function instead of =resolve-tile-collisions-y=

This is beyond the scope of the basic physics system.

* Performance Notes

- **Tile collision**: O(overlapping tiles) per entity. Usually 1–4 tiles per frame.
- **Entity collision**: O(n²) where n = entity count. Avoid for > 100 solid entities.
- **Ground detection**: O(2) tile lookups per entity (corners below feet).

For large games, consider spatial partitioning (grid, quadtree) to cull entity pairs. The basic physics system is designed for small to medium games (< 100 entities).

* Troubleshooting

** Entity Sinks Into Floor

- Make sure =#:height= is set correctly (not 0 or too large)
- Verify tileset metadata marks floor tiles as solid in Tiled editor
- Check that =resolve-tile-collisions-y= is called after =apply-velocity-y=

** Double-Jump / Can't Jump

- Ensure =detect-ground= is called after all collision resolution
- Verify =#:on-ground?= is checked in =apply-jump= (not hardcoded)
- Make sure you're checking =input-pressed?= (not =input-held?=) for jump

** Entity Slides Through Walls

- Check that #:width and #:height are set correctly
- Verify tileset marks wall tiles as solid
- Ensure =resolve-tile-collisions-x= is called after =apply-velocity-x=

** Entities Get Stuck Overlapping

- Use =scene-resolve-collisions= after all physics steps
- Verify both entities have =#:solid? #t=
- Reduce =*gravity*= or max velocity if entities are moving too fast (can cause multi-frame overlap)

** Performance Drops

- Profile entity count (should be < 100 for full physics pipeline)
- Disable =resolve-entity-collisions= if not needed
- Use =aabb-overlap?= for queries instead of marking many entities solid