1 files changed, 22 insertions, 17 deletions
diff --git a/docs/api.org b/docs/api.org
index d4dc074..15c6e54 100644
--- a/docs/api.org
+++ b/docs/api.org
@@ -208,7 +208,7 @@ Creates a scene record representing the current level state.
 | ~tileset~ | tileset/false | #f | Tileset metadata (from ~load-tileset~) when there is no tilemap; required with ~tileset-texture~ to draw ~#:tile-id~ sprites without a TMX map |
 | ~camera~ | camera/false | #f | Viewport position |
 | ~tileset-texture~ | SDL2 texture/false | #f | Rendered tileset image |
-| ~camera-target~ | symbol/false | #f | Tag symbol of the entity to follow (see ~scene-camera-target-set!~) |
+| ~camera-target~ | symbol/false | #f | Tag symbol of the entity to follow (set via ~update-scene~) |
 | ~background~ | list/false | #f | Framebuffer clear color: ~(r g b)~ or ~(r g b a)~ (0–255). ~#f~ means opaque black. Set each frame in ~game-run!~ before ~SDL_RenderClear~. |
 
 ** ~make-camera~
@@ -239,13 +239,13 @@ Accessors for camera position.
 
 Mutate camera position (in-place).
 
-** ~camera-follow!~
+** ~camera-follow~
 
 #+begin_src scheme
-(camera-follow! camera entity viewport-w viewport-h)
+(camera-follow camera entity viewport-w viewport-h)
 #+end_src
 
-Centers the camera on an entity, clamping to stay within world bounds (never negative). ~viewport-w~ and ~viewport-h~ are the game window dimensions.
+Returns a new camera centered on an entity, clamping to stay within world bounds (never negative). ~viewport-w~ and ~viewport-h~ are the game window dimensions. The original camera is not modified.
 
 ** ~scene-add-entity~
 
@@ -253,7 +253,7 @@ Centers the camera on an entity, clamping to stay within world bounds (never neg
 (scene-add-entity scene entity)
 #+end_src
 
-Appends an entity to the scene's entity list. Returns the modified scene.
+Appends an entity to the scene's entity list. Returns a new scene; the original is not modified.
 
 ** ~scene-update-entities~
 
@@ -261,7 +261,7 @@ Appends an entity to the scene's entity list. Returns the modified scene.
 (scene-update-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. The scene's entity list is updated once with the final result. Returns the modified scene.
+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.
 
 Example:
 
@@ -276,13 +276,13 @@ Example:
 ; Each entity is passed through increment-x, then through apply-gravity
 #+end_src
 
-** ~scene-sync-groups!~
+** ~scene-sync-groups~
 
 #+begin_src scheme
-(scene-sync-groups! scene)
+(scene-sync-groups scene)
 #+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 the scene.
+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.
 
 ** ~scene-filter-entities~
 
@@ -290,7 +290,7 @@ For every entity with ~#:group-id~ that is not an origin (~#:group-origin?~ is f
 (scene-filter-entities scene predicate)
 #+end_src
 
-Removes all entities that do not satisfy the predicate. Returns the modified scene.
+Keeps only entities that satisfy the predicate. Returns a new scene; the original is not modified.
 
 Example:
 
@@ -318,11 +318,16 @@ Returns a list of all entities whose ~#:tags~ list contains the given tag. Retur
 
 ** Accessor functions (auto-generated by defstruct)
 
-- ~scene-entities~, ~scene-entities-set!~
-- ~scene-tilemap~, ~scene-tilemap-set!~
-- ~scene-camera~, ~scene-camera-set!~
-- ~scene-tileset-texture~, ~scene-tileset-texture-set!~
-- ~scene-camera-target~, ~scene-camera-target-set!~
+Read accessors:
+- ~scene-entities~, ~scene-tilemap~, ~scene-camera~, ~scene-tileset-texture~, ~scene-camera-target~, ~scene-background~
+
+Functional updater (returns a new scene with the specified fields changed):
+
+#+begin_src scheme
+(update-scene scene entities: new-entities camera-target: 'player)
+#+end_src
+
+Mutating setters (~scene-entities-set!~, etc.) are also generated but should be avoided in favour of ~update-scene~ and the pure pipeline functions above. Use ~game-scene-set!~ at the boundary to store the final scene back on the game struct.
 
 ** ~tilemap-tile-at~
 
@@ -1328,7 +1333,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 call ~scene-sync-groups~ so member ~#:x~ / ~#:y~ match ~origin + #:group-local-x/y~.
 
 ** ~tilemap-objects->entities~
 
@@ -1343,5 +1348,5 @@ Example:
 #+begin_src scheme
 (let* ((registry (load-prefabs "assets/prefabs.scm" '() '()))
        (entities (tilemap-objects->entities tilemap registry)))
-  (scene-entities-set! scene entities))
+  (update-scene scene entities: entities))
 #+end_src