Add mod gameplay APIs and zombie shooter example

docs/lua-modding.md

@@ -124,7 +124,8 @@ All vectors are 1-based Lua arrays `{x,y,z}` in engine world coordinates, metres
 | `sdk.input.action(id:integer)` | number from published native gameplay action 64–81; errors outside range |
 | `sdk.ui.text(key:string,text:string)` | nil; create/update owned plain screen text, max 1024 bytes; stable top-left rows sorted by owner/key, 19px font, 28px row spacing |
 | `sdk.scene.cube(key:string,position:Vec3,size:Vec3,color:Vec3)` | nil; create/update owned visual cuboid; no collision, grind attachment or rigid body |
-| `sdk.scene.remove(key:string)` | nil; remove owned cube/text; absent key is a no-op; cannot address another mod's objects |
+| `sdk.scene.held_cube(key:string,bone:string,offset:Vec3,size:Vec3,color:Vec3)` | nil; create/update an owned visual cuboid parented to an exact displayed skeleton bone; local-only, non-colliding and removed with its owner |
+| `sdk.scene.remove(key:string)` | nil; remove owned world cube, held cube or text; absent key is a no-op; cannot address another mod's objects |
 | `sdk.time.elapsed` | active Update seconds since state creation, advanced after `on_update` |
 | `sdk.time.after(key:string,seconds:number,callback:function)` | nil; replace keyed one-shot timer; delay 0–86400 finite seconds, key 1–64 bytes, at most 64 timers |
 | `sdk.time.cancel(key:string)` | nil; remove timer; absent key is a no-op |
@@ -133,7 +134,7 @@ All vectors are 1-based Lua arrays `{x,y,z}` in engine world coordinates, metres
 
 Timers run after `on_update`, within its same instruction budget and transaction. Due timer keys sort lexicographically. A timer is removed before invocation. Newly scheduled timers normally wait for the next Update (replacing an already due, not-yet-delivered key can affect that key's pending delivery). Pausing stops the timer clock. Errors disable the owner. `sdk.time.elapsed` and snapshot fields should be treated as read-only by authors.
 
-Cube positions and teleport positions must be finite, each component within ±100000. Size components must be finite in `(0,100]`. RGB components must be finite in `[0,1]`, interpreted as sRGB. Heading must be finite. Text and cubes share an owner-local key namespace: switching type replaces the old object. At most 64 visual objects per mod; update existing keys to avoid churn. At most 128 commands per Lua invocation. Invalid arguments raise Lua errors; exceeding limits stops the mod. Commands return nil on successful **queuing**, not proof of engine completion. Host rejection appears in the mod's error panel and log. Teleports reject map loading, replay and busy actor-reset conditions. This is a free-position command, not a terrain-safe spawn finder: authors must select valid destinations. It does not set velocities directly or bypass the native deferred reset/camera-cut sequence.
+Cube positions and teleport positions must be finite, each component within ±100000. World-cube size components must be finite in `(0,100]`. Held-cube offsets are limited to ±10 metres, held-cube sizes to `(0,10]`, and the bone must be an exact installed name reported by `sdk.animation.info()`. A held cube remains hidden until that bone has a displayed binding, then follows its final animated transform. RGB components must be finite in `[0,1]`, interpreted as sRGB. Heading must be finite. Text and cubes share an owner-local key namespace: switching type replaces the old object. At most 64 visual objects per mod; update existing keys to avoid churn. At most 128 commands per Lua invocation. Invalid arguments raise Lua errors; exceeding limits stops the mod. Commands return nil on successful **queuing**, not proof of engine completion. Host rejection appears in the mod's error panel and log. Teleports reject map loading, replay and busy actor-reset conditions. This is a free-position command, not a terrain-safe spawn finder: authors must select valid destinations. It does not set velocities directly or bypass the native deferred reset/camera-cut sequence.
 
 ### Snapshot and event payloads
 

docs/multiplayer-mods.md

@@ -11,6 +11,7 @@ available. `Build.ps1` builds and stages both executables without launching them
 | SDK feature | Multiplayer behavior |
 | --- | --- |
 | `scene.cube` / `scene.remove` | Owner-scoped shared visual objects; updates, removal and late joins supported. Cubes remain non-colliding. |
+| `scene.held_cube` | Local visual attachment to the owning player's displayed skeleton. It is not replicated by SDK 1. |
 | `vehicle.spawn/remove/reset/tune/control` | Matching package supplies the model and definition. Owner sends chassis pose, velocities, wheel state, controls, tuning and occupancy. Other peers render and collide with replicas. |
 | Vehicle entry/exit/steering | The final displayed native skeleton, including stance blending and arm steering, is replicated. Seated riders follow the same car render sample. |
 | Vehicle engine audio | Each occupied car has a smoothed engine voice; other players' cars attenuate with distance. |