diff options
Diffstat (limited to 'docs/api.org')
| -rw-r--r-- | docs/api.org | 42 |
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~ |