Rework animations and entities - somewhat

1 files changed, 51 insertions, 32 deletions

diff --git a/docs/entities.org b/docs/entities.org
index 06b1831..4e451d3 100644
--- a/docs/entities.org
+++ b/docs/entities.org
@@ -24,7 +24,14 @@ The optional key ~#:skip-pipelines~ holds a list of **symbols** naming frame pip
 
 * Creating Entities
 
-There is no ~make-entity~ constructor. Create an entity as a plain list:
+There is a basic ~make-entity~ constructor, which carries positional data (x y w h); its type is ='none=:
+
+#+begin_src scheme
+  (define my-entity (make-entity 200 150 16 16))
+#+end_src
+
+
+However creating an entity is as simple as a plain list:
 
 #+begin_src scheme
 (define my-entity
@@ -77,6 +84,19 @@ Returns a **new** plist with the key/value pair set (or replaced). The original
 (entity-ref updated-player #:vx)  ; → 5
 #+end_src
 
+** ~entity-set-many entity pairs~
+
+Sets multiple attributes of an entity at once.
+
+#+begin_src scheme
+  (define updated-player (entity-set-many player '((#:vx 5) (#:vy 10))))
+  ;; original player is still unchanged:
+  (entity-ref player #:vx)          ; → 0
+  (entity-ref player #:vy)          ; → 0
+  (entity-ref updated-player #:vx)  ; → 5
+  (entity-ref updated-player #:vy)  ; → 10
+#+end_src
+
 ** ~entity-update entity key proc [default]~
 
 Returns a new entity with ~key~ set to ~(proc (entity-ref entity key default))~. Useful for incrementing or transforming a value:
@@ -87,14 +107,13 @@ Returns a new entity with ~key~ set to ~(proc (entity-ref entity key default))~.
 
 ** Chaining Updates: The let* Pattern
 
-Since each update returns a new entity, chain updates with ~let*~:
+Since each update returns a new entity, chain updates with ~chain~ (srfi-197):
 
 #+begin_src scheme
-(let* ((player (entity-set player #:vx 3))
-       (player (apply-velocity-x player scene dt))
-       (player (resolve-tile-collisions-x player scene dt)))
-  ;; now use the updated player
-  player)
+  (chain player
+         (entity-set _ #:vx 3)
+         (apply-velocity-x _ scene dt)
+         (resolve-tile-collisions-x _ scene dt))
 #+end_src
 
 With the default =engine-update=, you normally set =#:vx= / =#:ay= in =update:= and do not chain physics steps yourself. This =let*= shape is for custom =engine-update= hooks or tests; per-entity steps take =(entity scene dt)=.
@@ -103,31 +122,31 @@ With the default =engine-update=, you normally set =#:vx= / =#:ay= in =update:=
 
 The engine recognizes these standard keys. Use them to integrate with the physics pipeline, rendering, and animation systems. Custom keys are always allowed.
 
-| Key | Type | Description |
-|---|---|---|
-| ~#:type~ | symbol | Entity type, e.g., ~'player~, ~'enemy~, ~'coin~. No built-in enforcement; use for ~entity-type~ checks and scene queries. |
-| ~#:x~, ~#:y~ | number | World position in pixels (top-left corner of bounding box). Updated by ~apply-velocity-x~, ~apply-velocity-y~, and collision resolvers. |
-| ~#:width~, ~#:height~ | number | Bounding box size in pixels. Used for AABB tile collision checks and entity-entity collision. Required for physics. |
-| ~#:vx~, ~#:vy~ | number | Velocity in pixels per frame. ~#:vx~ is updated by ~apply-velocity-x~; ~#:vy~ is updated by ~apply-velocity-y~. Both consumed by collision resolvers. |
-| ~#:ay~ | number | Y acceleration (e.g., from jumping or knockback). Consumed by ~apply-acceleration~, which adds it to ~#:vy~. Optional; default is 0. |
-| ~#:gravity?~ | boolean | Whether gravity applies to this entity. Set to ~#t~ for platformers (gravity pulls down), ~#f~ for top-down or flying entities. Used by ~apply-gravity~. |
-| ~#:on-ground?~ | boolean | Whether the entity is supported from below (set by ~detect-on-solid~ in the default pipeline): solid tile under the feet and/or standing on another solid entity from ~(scene-entities scene)~. Use this in ~update:~ to gate jump input (~#:ay~). |
-| ~#:solid?~ | boolean | Whether this entity participates in entity-entity collision. If ~#t~, ~resolve-entity-collisions~ will check it against other solid entities. |
-| ~#:immovable?~ | boolean | If ~#t~ with ~#:solid? #t~, entity–entity resolution only moves the *other* entity (static platforms). Two overlapping immovable solids are not separated. |
-| ~#:skip-pipelines~ | list of symbols | Optional. Each symbol names a pipeline step to skip (e.g. ~gravity~, ~velocity-x~, ~tweens~). See ~docs/physics.org~ and ~docs/tweens.org~. |
-| ~#:tween~ | tween struct or ~#f~ | Optional. When present, ~step-tweens~ auto-advances the tween each frame. Removed automatically when the tween finishes. See ~docs/tweens.org~. |
-| ~#:tile-id~ | integer | Sprite index in the tileset (1-indexed). Used by ~render-scene!~ when the scene has a tileset texture and tile metadata (from the tilemap or ~scene-tileset~). Updated automatically by animation (~animate-entity~). |
-| ~#:color~ | list | Optional ~(r g b)~ or ~(r g b a)~ (0–255 each). When ~#:tile-id~ is not drawn as a sprite (missing ~#:tile-id~, or no tileset texture), ~render-scene!~ fills the entity rect with this color. |
-| ~#:facing~ | number | Horizontal flip direction: ~1~ = right (default), ~-1~ = left. Used by renderer to flip sprite horizontally. Update when changing direction. |
-| ~#:tags~ | list of symbols | List of tag symbols, e.g., ~'(player solid)~. Used by ~scene-find-tagged~ and ~scene-find-all-tagged~ for fast lookups. |
-| ~#:animations~ | alist | Animation definitions (see Animation section). Keys are animation names (symbols); values are animation specs. |
-| ~#:anim-name~ | symbol | Currently active animation name, e.g., ~'walk~, ~'jump~. Set with ~set-animation~; reset by ~animate-entity~. |
-| ~#:anim-frame~ | integer | Current frame index within the animation (0-indexed). Updated automatically by ~animate-entity~. |
-| ~#:anim-tick~ | integer | Tick counter for frame timing (0 to ~#:duration - 1~). Incremented by ~animate-entity~; resets when frame advances. |
-| ~#:group-id~ | symbol | Shared id for one rigid assembly (from ~instantiate-group-prefab~). All parts and the origin share the same symbol. |
-| ~#:group-origin?~ | boolean | When ~#t~, this entity is the assembly’s pose origin; world ~#:x~ / ~#:y~ drive the group. Members should not set this. |
-| ~#:group-local-x~, ~#:group-local-y~ | number | Offset from the origin’s top-left corner; members’ world position is origin + local (updated by ~sync-groups~ on the entity list, e.g. ~(scene-transform-entities scene sync-groups)~). |
-| ~#:skip-render~ | boolean | When ~#t~, ~render-scene!~ skips drawing this entity (used for invisible origins). |
+| Key                                  | Type                 | Description                                                                                                                                                                                                                                        |
+|--------------------------------------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| ~#:type~                             | symbol               | Entity type, e.g., ~'player~, ~'enemy~, ~'coin~. No built-in enforcement; use for ~entity-type~ checks and scene queries.                                                                                                                          |
+| ~#:x~, ~#:y~                         | number               | World position in pixels (top-left corner of bounding box). Updated by ~apply-velocity-x~, ~apply-velocity-y~, and collision resolvers.                                                                                                            |
+| ~#:width~, ~#:height~                | number               | Bounding box size in pixels. Used for AABB tile collision checks and entity-entity collision. Required for physics.                                                                                                                                |
+| ~#:vx~, ~#:vy~                       | number               | Velocity in pixels per frame. ~#:vx~ is updated by ~apply-velocity-x~; ~#:vy~ is updated by ~apply-velocity-y~. Both consumed by collision resolvers.                                                                                              |
+| ~#:ay~                               | number               | Y acceleration (e.g., from jumping or knockback). Consumed by ~apply-acceleration~, which adds it to ~#:vy~. Optional; default is 0.                                                                                                               |
+| ~#:gravity?~                         | boolean              | Whether gravity applies to this entity. Set to ~#t~ for platformers (gravity pulls down), ~#f~ for top-down or flying entities. Used by ~apply-gravity~.                                                                                           |
+| ~#:on-ground?~                       | boolean              | Whether the entity is supported from below (set by ~detect-on-solid~ in the default pipeline): solid tile under the feet and/or standing on another solid entity from ~(scene-entities scene)~. Use this in ~update:~ to gate jump input (~#:ay~). |
+| ~#:solid?~                           | boolean              | Whether this entity participates in entity-entity collision. If ~#t~, ~resolve-entity-collisions~ will check it against other solid entities.                                                                                                      |
+| ~#:immovable?~                       | boolean              | If ~#t~ with ~#:solid? #t~, entity–entity resolution only moves the *other* entity (static platforms). Two overlapping immovable solids are not separated.                                                                                         |
+| ~#:skip-pipelines~                   | list of symbols      | Optional. Each symbol names a pipeline step to skip (e.g. ~gravity~, ~velocity-x~, ~tweens~). See ~docs/physics.org~ and ~docs/tweens.org~.                                                                                                        |
+| ~#:tween~                            | tween struct or ~#f~ | Optional. When present, ~step-tweens~ auto-advances the tween each frame. Removed automatically when the tween finishes. See ~docs/tweens.org~.                                                                                                    |
+| ~#:tile-id~                          | integer              | Sprite index in the tileset (1-indexed). Used by ~render-scene!~ when the scene has a tileset texture and tile metadata (from the tilemap or ~scene-tileset~). Updated automatically by animation (~animate-entity~).                              |
+| ~#:color~                            | list                 | Optional ~(r g b)~ or ~(r g b a)~ (0–255 each). When ~#:tile-id~ is not drawn as a sprite (missing ~#:tile-id~, or no tileset texture), ~render-scene!~ fills the entity rect with this color.                                                     |
+| ~#:facing~                           | number               | Horizontal flip direction: ~1~ = right (default), ~-1~ = left. Used by renderer to flip sprite horizontally. Update when changing direction.                                                                                                       |
+| ~#:tags~                             | list of symbols      | List of tag symbols, e.g., ~'(player solid)~. Used by ~scene-find-tagged~ and ~scene-find-all-tagged~ for fast lookups.                                                                                                                            |
+| ~#:animations~                       | alist                | Animation definitions (see Animation section). Keys are animation names (symbols); values are animation specs.                                                                                                                                     |
+| ~#:anim-name~                        | symbol               | Currently active animation name, e.g., ~'walk~, ~'jump~. Set with ~set-animation~; reset by ~animate-entity~.                                                                                                                                      |
+| ~#:anim-frame~                       | integer              | Current frame index within the animation (0-indexed). Updated automatically by ~animate-entity~.                                                                                                                                                   |
+| ~#:anim-tick~                        | integer              | Tick counter for frame timing (0 to ~#:duration - 1~). Incremented by ~animate-entity~; resets when frame advances.                                                                                                                                |
+| ~#:group-id~                         | symbol               | Shared id for one rigid assembly (from ~instantiate-group-prefab~). All parts and the origin share the same symbol.                                                                                                                                |
+| ~#:group-origin?~                    | boolean              | When ~#t~, this entity is the assembly’s pose origin; world ~#:x~ / ~#:y~ drive the group. Members should not set this.                                                                                                                            |
+| ~#:group-local-x~, ~#:group-local-y~ | number               | Offset from the origin’s top-left corner; members’ world position is origin + local (updated by ~sync-groups~ on the entity list, e.g. ~(scene-transform-entities scene sync-groups)~).                                                            |
+| ~#:skip-render~                      | boolean              | When ~#t~, ~render-scene!~ skips drawing this entity (used for invisible origins).                                                                                                                                                                 |
 
 * Entity groups (prefab assemblies)