From 84840ede6646ed793b61cdd889d3f57ab05e9311 Mon Sep 17 00:00:00 2001 From: Gene Pasquet Date: Wed, 8 Apr 2026 01:32:55 +0100 Subject: Refactor to be functional --- docs/api.org | 39 ++++++++++++++++++++++----------------- 1 file changed, 22 insertions(+), 17 deletions(-) (limited to 'docs/api.org') 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 -- cgit v1.2.3