Refactor update pipelines

1 files changed, 29 insertions, 13 deletions

diff --git a/docs/api.org b/docs/api.org
index 15c6e54..e60ef7d 100644
--- a/docs/api.org
+++ b/docs/api.org
@@ -255,10 +255,10 @@ Returns a new camera centered on an entity, clamping to stay within world bounds
 
 Appends an entity to the scene's entity list. Returns a new scene; the original is not modified.
 
-** ~scene-update-entities~
+** ~scene-map-entities~
 
 #+begin_src scheme
-(scene-update-entities scene proc1 proc2 ...)
+(scene-map-entities scene proc1 proc2 ...)
 #+end_src
 
 Applies each procedure in sequence to all entities in the scene. Each procedure takes a single entity and returns a modified entity. Returns a new scene with the updated entity list; the original is not modified.
@@ -272,17 +272,31 @@ Example:
 (define (apply-gravity entity)
   (entity-set entity #:vy (+ 1 (entity-ref entity #:vy 0))))
 
-(scene-update-entities scene increment-x apply-gravity)
+(scene-map-entities scene increment-x apply-gravity)
 ; Each entity is passed through increment-x, then through apply-gravity
 #+end_src
 
-** ~scene-sync-groups~
+** ~scene-transform-entities~
 
 #+begin_src scheme
-(scene-sync-groups scene)
+(scene-transform-entities scene proc)
 #+end_src
 
-For every entity with ~#:group-id~ that is not an origin (~#:group-origin?~ is false), sets ~#:x~ and ~#:y~ to the corresponding origin’s position plus that entity’s ~#:group-local-x~ and ~#:group-local-y~. Origins are read from ~scene-entities~, so after a tween or other motion that returns a *new* origin plist, replace that origin in the scene’s list (match on ~#:group-id~ / ~#:group-origin?~) before calling ~scene-sync-groups~. Call after updating origin positions and before per-entity physics so platforms and collisions see a consistent pose. Returns a new scene; the original is not modified.
+Applies ~proc~ to the scene’s full entity list. ~proc~ must have signature ~(entities → entities)~: it receives the current list and returns a new list. Returns a new scene with that entity list; the original is not modified. Use this to run whole-list steps such as ~sync-groups~ or ~resolve-entity-collisions~ after ~scene-map-entities~ (or in any order your game needs).
+
+** ~sync-groups~
+
+#+begin_src scheme
+(sync-groups entities)
+#+end_src
+
+For every entity with ~#:group-id~ that is not an origin (~#:group-origin?~ is false), sets ~#:x~ and ~#:y~ to the corresponding origin’s position plus that entity’s ~#:group-local-x~ and ~#:group-local-y~. Origins are read from the **entity list** argument (typically ~(scene-entities scene)~ when you compose with ~scene-transform-entities~), so after a tween or other motion that returns a *new* origin plist, replace that origin in the list (match on ~#:group-id~ / ~#:group-origin?~) before calling ~sync-groups~. Call after updating origin positions and before per-entity physics so platforms and collisions see a consistent pose. Returns a new entity list.
+
+Typical usage:
+
+#+begin_src scheme
+(scene-transform-entities scene sync-groups)
+#+end_src
 
 ** ~scene-filter-entities~
 
@@ -411,10 +425,14 @@ Returns true if ~step-symbol~ appears in the entity’s ~#:skip-pipelines~ list
 ** ~define-pipeline~
 
 #+begin_src scheme
-(define-pipeline (procedure-name skip-symbol) (entity-formal extra-formal ...) body ...)
+(define-pipeline (procedure-name skip-symbol) (entity-formal extra-formal ...)
+  guard: guard-expr
+  body ...)
 #+end_src
 
-Syntax for authors of per-entity pipeline steps: expands to a ~define~ that returns the **first** formal (the entity) unchanged when ~skip-symbol~ is listed in ~#:skip-pipelines~; otherwise runs ~body ...~ inside ~(let () ...)~. Used throughout ~downstroke-physics~; other modules can use it for consistent skip behavior. The procedure name and skip symbol differ when needed (e.g. ~detect-on-solid~ vs ~on-solid~).
+The ~guard:~ clause is optional. When present, ~guard-expr~ is evaluated first; if it is false, the entity is returned unchanged and ~body ...~ does not run. When absent, the body applies to all entities (subject only to the skip-symbol check below).
+
+Syntax for authors of per-entity pipeline steps: expands to a ~define~ that returns the **first** formal (the entity) unchanged when ~skip-symbol~ is listed in ~#:skip-pipelines~; otherwise, if a guard is present and fails, returns the entity unchanged; otherwise runs ~body ...~ inside ~(let () ...)~. Used throughout ~downstroke-physics~; other modules can use it for consistent skip behavior. The procedure name and skip symbol differ when needed (e.g. ~detect-on-solid~ vs ~on-solid~).
 
 ** Shared Entity Keys
 
@@ -547,14 +565,12 @@ If the jump button is pressed and the entity is on ground, sets ~#:ay~ to ~(- #:
 
 Detects and resolves AABB collisions between all pairs of entities with ~#:solid?~ true. Pushes overlapping entities apart along the axis of minimum penetration and sets their velocities in the push direction. Returns a new entity list.
 
-** ~scene-resolve-collisions~
+There is no scene-level wrapper; apply ~resolve-entity-collisions~ to the entity list via ~scene-transform-entities~:
 
 #+begin_src scheme
-(scene-resolve-collisions scene)
+(scene-transform-entities scene resolve-entity-collisions)
 #+end_src
 
-Applies ~resolve-entity-collisions~ to the scene's entity list. Returns the modified scene.
-
 ** Physics Constants
 
 - ~*gravity*~ = 1 (pixels per frame per frame)
@@ -1333,7 +1349,7 @@ Looks up a prefab by type symbol in the registry and returns a fresh entity plis
 (instantiate-group-prefab registry type origin-x origin-y)
 #+end_src
 
-Looks up a *group prefab* by type symbol and returns a list ~(origin member ...)~: one origin entity plus one entity per part. Optional group-level flags ~#:pose-only-origin?~ and ~#:static-parts?~ select origin/part profiles (see ~docs/entities.org~); defaults are ~#f~ (physics-driving origin, non-static parts). Each instance receives a fresh gensym ~#:group-id~ shared by the origin and all members. Returns ~#f~ if the type is not in ~group-prefabs~. After moving origins (tween and/or physics), ensure updated origins are stored in the scene’s entity list, then call ~scene-sync-groups~ so member ~#:x~ / ~#:y~ match ~origin + #:group-local-x/y~.
+Looks up a *group prefab* by type symbol and returns a list ~(origin member ...)~: one origin entity plus one entity per part. Optional group-level flags ~#:pose-only-origin?~ and ~#:static-parts?~ select origin/part profiles (see ~docs/entities.org~); defaults are ~#f~ (physics-driving origin, non-static parts). Each instance receives a fresh gensym ~#:group-id~ shared by the origin and all members. Returns ~#f~ if the type is not in ~group-prefabs~. After moving origins (tween and/or physics), ensure updated origins are stored in the scene’s entity list, then ~(scene-transform-entities scene sync-groups)~ so member ~#:x~ / ~#:y~ match ~origin + #:group-local-x/y~.
 
 ** ~tilemap-objects->entities~