Physics

• Reads: #:tween
• Writes: #:tween (advanced, or removed when finished), plus any entity keys the tween is targeting (typically #:x, #:y, a color component, etc. — see docs/tweens.org)
• Guard: does nothing if #:tween is #f
• Defined in tween.scm.

• Reads: #:ay (default 0), #:vy (default 0)
• Writes: #:vy (set to (+ vy ay)), #:ay (reset to 0)
• Guard: (entity-ref entity #:gravity? #f) — only runs on entities with #:gravity? #t
• One-shot: #:ay is consumed every frame. This is the jump mechanism — set #:ay to (- *jump-force*) on the frame you want to jump and this step folds it into #:vy exactly once.

• Reads: #:gravity?, #:vy (default 0)
• Writes: #:vy (set to (+ vy *gravity*))
• Guard: only runs when #:gravity? #t
• *gravity* is exported from (downstroke physics); its value is 1 pixel/frame². Gravity accumulates until resolve-tile-collisions-y zeroes #:vy on contact with the floor.

• Reads: #:x (default 0), #:vx (default 0)
• Writes: #:x (set to (+ x vx))
• No guard. Every entity moves by #:vx, regardless of #:gravity?. Top-down games therefore "just work" — set #:vx and #:vy from input, the pipeline moves the entity and resolves tile collisions, and the absence of #:gravity? makes gravity/acceleration/ground detection no-op.

• Reads: scene's tilemap via scene-tilemap, then #:x, #:y, #:width, #:height, #:vx
• Writes: #:x (snapped), #:vx (set to 0 if a collision occurred)
• Guard: only runs when (scene-tilemap scene) is truthy. If the scene has no tilemap this step is a no-op.
• Behavior: computes every tile cell overlapping the entity's AABB (entity-tile-cells), walks them, and if any cell's tile id is non-zero it snaps the entity to that tile's edge on the X axis. Moving right (#:vx > 0) snaps the right edge to the near side of the first solid tile found (shallowest penetration). Moving left (#:vx < 0) snaps the left edge to the far side of the last solid tile found. In both cases #:vx is zeroed.

• Reads: #:y (default 0), #:vy (default 0)
• Writes: #:y (set to (+ y vy))
• No guard. Same as apply-velocity-x on the Y axis.

• Reads: scene's tilemap, then #:x, #:y, #:width, #:height, #:vy
• Writes: #:y (snapped), #:vy (zeroed on collision)
• Guard: only runs when (scene-tilemap scene) is truthy.
• Behavior: same as the X-axis version, but on Y. Moving down (#:vy > 0) snaps the feet to a floor tile's top; moving up (#:vy < 0) snaps the head to a ceiling tile's bottom. X and Y are resolved in separate passes (move X → resolve X → move Y → resolve Y) to avoid corner-clipping.

• Reads: #:gravity?, #:x, #:y, #:width, #:height, #:vy; and (scene-entities scene) for entity-supported ground
• Writes: #:on-ground? (#t or #f)
• Guard: only runs on gravity entities. The ? in the name is slightly misleading: the step returns an updated entity (with #:on-ground? set), not a boolean.
• Two sources of "ground":
  1. Tile ground. Probes one pixel below the feet ((+ y h 1)) at both lower corners; if either column's tile id at that row is non-zero, the entity is grounded. If scene-tilemap is #f this probe is skipped.
  2. Entity ground. Another entity in the scene with #:solid? #t counts as ground if it horizontally overlaps the mover, its top is within *entity-ground-contact-tolerance* (5 pixels) of the mover's bottom, and the mover's |#:vy| is at most *entity-ground-vy-max* (12) — so a body falling too fast is not treated as supported mid-frame.

This is a bulk step: it takes the entity list and returns a new entity list.

• Reads: for each entity, #:solid?, #:immovable?, #:x, #:y, #:width, #:height
• Writes: for overlapping pairs, #:x, #:y, and whichever axis velocity (#:vx or #:vy) the separation was applied on
• Behavior: all-pairs AABB overlap check (O(n²)). For each pair where both entities have #:solid? #t:
  • both #:immovable? #t → pair skipped
  • one #:immovable? #t → the movable one is pushed out along the shallow penetration axis, its velocity on that axis is zeroed. If the mover's center is still above the immovable's center (a landing contact), separation is forced vertical so the mover doesn't get shoved sideways off the edge of a platform.
  • neither immovable → both are pushed apart by half the overlap along the smaller-penetration axis, and their velocities on that axis are set to ±1 (to prevent sticking / drift back into each other).
  • If either entity lists entity-collisions in #:skip-pipelines, the pair is skipped entirely.

• Bulk step. Takes the entity list and returns a new entity list.
• For each entity with #:group-origin? #t and a #:group-id, marks it as the origin of its group (first-wins).
• For each entity with a #:group-id that is not the origin, snaps its #:x / #:y to (+ origin-x #:group-local-x) / (+ origin-y #:group-local-y).
• Intended use: multi-part entities (a platform made of several tiles, a boss with attached hitboxes) that should move as one body. Move the origin only; sync-groups rigidly follows the members.

• Reads: #:animations, #:anim-name, #:anim-frame, #:anim-tick (the tick budget each step is animation-frame-duration on the current animation + frame index — see docs/animation.org).
• Writes: #:anim-tick, #:anim-frame, #:tile-id, #:anim-duration (#:anim-duration mirrors the resolved budget for the current frame).
• Guard: only runs when #:animations is present.
• Advances the per-entity animation state machine and updates #:tile-id so the renderer draws the correct sprite. Fully documented in docs/animation.org.

Some pipeline steps only run when a specific entity key is set. These are guards declared with the guard: clause of define-pipeline:

A top-down entity with #:gravity? absent (or #f) therefore automatically skips acceleration, gravity, and ground detection — the rest of the pipeline (velocity, tile collisions, entity collisions, animation) still runs.

Entity–entity collisions have their own opt-in gate instead of a guard: only entities with #:solid? #t participate in resolve-entity-collisions. Non-solid entities are ignored by the pair walk.

Every per-entity step is also gated by entity-skips-pipeline? (from (downstroke entity)). If the entity's #:skip-pipelines list contains the step's symbol, the step returns the entity unchanged. The symbols match the second name in each define-pipeline form:

For resolve-entity-collisions, if either entity in a pair lists entity-collisions, the whole pair is skipped. This is the clean way to mark "ghosts" or script-driven actors that should not be pushed apart from others.

Example: an entity driven by a tween that shouldn't be integrated by velocity or affected by gravity, but should still resolve against walls and run animation:

(list #:type 'moving-platform
      #:x 100 #:y 300 #:width 48 #:height 16
      #:vx 0 #:vy 0
      #:tween ...
      #:skip-pipelines '(acceleration gravity velocity-x velocity-y))

The pipeline will advance #:tween (which can overwrite #:x / #:y directly), skip the four listed integrators, still resolve tile collisions, and still detect ground under it.

All per-entity pipeline steps are declared with define-pipeline from (downstroke entity) (see docs/entities.org). The shape is:

(define-pipeline (procedure-name skip-symbol) (scene entity dt)
  guard: (some-expression-over entity)
  (body ...))

The macro expands to a procedure (procedure-name scene entity dt) that returns entity unchanged if either the guard is #f or the entity's #:skip-pipelines list contains skip-symbol. Otherwise it runs body. The guard: clause is optional; when absent, only #:skip-pipelines is consulted.

Tiles come from a (downstroke tilemap) parsed from a TMX file (Tiled editor). The tilemap stores a grid of tile ids across one or more layers; tilemap-tile-at returns 0 for an empty cell and a positive id for a filled cell. Only empty vs non-empty is checked — there is no per-tile "solid" flag in the core engine; any non-zero tile counts as solid for collision purposes.

For each axis:

1. Compute the set of tile cells the entity's AABB overlaps (entity-tile-cells), in tile coordinates. The AABB is computed from #:x, #:y, #:width, #:height; the lower edges use (- (+ coord size) 1) so an entity exactly flush with a tile edge is not considered overlapping that tile.

2. For each overlapping cell, if its tile id is non-zero, snap the entity to the tile edge on that axis. The snap function (tile-push-pos) is:

   ;; Moving forward (v>0):   snap leading edge to tile's near edge.
   ;; Moving backward (v<0):  snap trailing edge to tile's far edge.
   (if (> v 0)
       (- (* coord tile-size) entity-size)
       (* (+ coord 1) tile-size))
   

3. Zero the axis velocity so the entity doesn't slide through.

X and Y are resolved in separate passes (see the pipeline order above). Resolving them together tends to produce corner-clip bugs where a player moving diagonally gets stuck at the corner of a floor and a wall; the two-pass approach avoids this entirely.

resolve-entity-collisions walks all unique pairs (i, j) with i < j of the entity list and calls resolve-pair. For each pair:

• Both must have #:solid? #t and neither may list entity-collisions in #:skip-pipelines.
• AABB overlap test (aabb-overlap?): strictly overlapping; edge-touching does not count.
• On overlap, push-apart picks the minimum-penetration axis (X vs Y, whichever overlap is smaller) and pushes each entity half the overlap away from the other, setting velocity on that axis to ±1.
• If exactly one entity has #:immovable? #t (static geometry like a platform), only the other entity moves, by the full overlap, and its velocity on the separation axis is zeroed.
• Landing-on-top preference: when a movable body is falling onto a static one and the movable's center is still above the static's center, separation is forced vertical regardless of which axis has the smaller overlap. This is what makes moving platforms usable — a narrow horizontal overlap at the edge of a platform doesn't shove the player off sideways.

#:on-ground? is the single key you'll read most often. It is a result of the pipeline (written by detect-on-solid), not an input. It is re-computed every frame after both tile-collision passes but before entity collisions. If your game needs ground detection to reflect entity push-apart (rare — it matters for very thin platforms), install a custom engine-update that calls detect-on-solid after resolve-entity-collisions.

If you want to detect overlap without resolving it (bullets hitting enemies, damage zones, pickups), call aabb-overlap? directly:

(aabb-overlap? x1 y1 w1 h1 x2 y2 w2 h2)  ;; → #t or #f

This is pure — it does not touch either entity. The shmup demo (demo/shmup.scm) uses exactly this pattern to find bullet/enemy overlaps and remove them from the scene.