Support entity groups

1 files changed, 17 insertions, 1 deletions

diff --git a/docs/api.org b/docs/api.org
index 1f15945..45593e4 100644
--- a/docs/api.org
+++ b/docs/api.org
@@ -237,6 +237,14 @@ Example:
 ; Each entity is passed through increment-x, then through apply-gravity
 #+end_src
 
+** ~scene-sync-groups!~
+
+#+begin_src scheme
+(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.
+
 ** ~scene-filter-entities~
 
 #+begin_src scheme
@@ -1233,7 +1241,7 @@ Creates an SDL2 texture from the tileset image embedded in a tilemap struct. Use
 (load-prefabs filename engine-mixin-table user-hooks)
 #+end_src
 
-Loads a prefab definition file and returns a ~prefab-registry~ struct. The file must contain a Scheme expression with ~mixins~ and ~prefabs~ sections (see ~docs/entities.org~).
+Loads a prefab definition file and returns a ~prefab-registry~ struct. The file must contain a Scheme expression with ~mixins~ and ~prefabs~ sections; an optional ~group-prefabs~ section defines multi-entity assemblies (see ~docs/entities.org~).
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
@@ -1263,6 +1271,14 @@ Reloads the prefab file that the registry was originally loaded from. Returns a
 
 Looks up a prefab by type symbol in the registry and returns a fresh entity plist at the given position and size. Returns ~#f~ if the type is not registered. If the resulting entity has an ~#:on-instantiate~ hook, it is called with the entity before returning.
 
+** ~instantiate-group-prefab~
+
+#+begin_src scheme
+(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~.
+
 ** ~tilemap-objects->entities~
 
 #+begin_src scheme