spoint 0.1.49 → 0.1.51

package/SKILL.md

@@ -1,1406 +1,379 @@
 ---
 name: spoint
-description: Work with spoint - a multiplayer physics game server SDK. Scaffolds apps locally, runs engine from npm package.
+description: Build multiplayer physics games with the Spawnpoint engine. Use when asked to: create a game, add physics objects, spawn entities, build an arena, handle player interaction, add weapons/respawn/scoring, create moving platforms, manage world config, load 3D models, add HUD/UI, work with the EventBus, or develop any app inside an apps/ directory.
 ---
 
 # Spawnpoint App Development Reference
 
-Complete reference for building apps in a spawnpoint project. Engine source code is not required. Everything needed to build any app is documented here.
+Setup:
+```bash
+bunx spoint scaffold   # first time — copies default apps/ into cwd
+bunx spoint            # start server (localhost:3001)
+bunx spoint-create-app my-app
+bunx spoint-create-app --template physics my-crate
+```
+
+Project structure: `apps/world/index.js` (world config) + `apps/<name>/index.js` (apps). Engine is from npm — never in user project.
 
 ---
 
 ## Quick Start — Minimal Working Arena
 
-This is the fastest path to a playable scene. Copy this pattern exactly.
-
-### Step 1: World config (`apps/world/index.js`)
-
+### `apps/world/index.js`
 ```js
 export default {
-  port: 3001,
-  tickRate: 128,
-  gravity: [0, -9.81, 0],
+  port: 3001, tickRate: 128, gravity: [0, -9.81, 0],
   movement: { maxSpeed: 4.0, groundAccel: 10.0, airAccel: 1.0, friction: 6.0, stopSpeed: 2.0, jumpImpulse: 4.0 },
   player: { health: 100, capsuleRadius: 0.4, capsuleHalfHeight: 0.9, modelScale: 1.323, feetOffset: 0.212 },
   scene: { skyColor: 0x87ceeb, fogColor: 0x87ceeb, fogNear: 80, fogFar: 200, sunIntensity: 1.5, sunPosition: [20, 40, 20] },
-  entities: [
-    { id: 'arena', position: [0, 0, 0], app: 'arena' }
-  ],
+  entities: [{ id: 'arena', position: [0,0,0], app: 'arena' }],
   spawnPoint: [0, 2, 0]
 }
 ```
 
-### Step 2: Arena app (`apps/arena/index.js`)
-
-This creates a ground plane and 4 walls using box primitives (visual + physics), no GLB required:
-
+### `apps/arena/index.js`
 ```js
-const HALF = 12, WALL_H = 3, WALL_T = 0.5
+const HALF = 12, WH = 3, WT = 0.5
 const WALLS = [
-  { id: 'wall-n', x: 0,      y: WALL_H/2, z: -HALF,  hx: HALF,      hy: WALL_H/2, hz: WALL_T/2 },
-  { id: 'wall-s', x: 0,      y: WALL_H/2, z:  HALF,  hx: HALF,      hy: WALL_H/2, hz: WALL_T/2 },
-  { id: 'wall-e', x:  HALF,  y: WALL_H/2, z: 0,      hx: WALL_T/2, hy: WALL_H/2, hz: HALF },
-  { id: 'wall-w', x: -HALF,  y: WALL_H/2, z: 0,      hx: WALL_T/2, hy: WALL_H/2, hz: HALF },
+  { id:'wn', x:0,     y:WH/2, z:-HALF, hx:HALF,  hy:WH/2, hz:WT/2 },
+  { id:'ws', x:0,     y:WH/2, z: HALF, hx:HALF,  hy:WH/2, hz:WT/2 },
+  { id:'we', x: HALF, y:WH/2, z:0,     hx:WT/2,  hy:WH/2, hz:HALF },
+  { id:'ww', x:-HALF, y:WH/2, z:0,     hx:WT/2,  hy:WH/2, hz:HALF },
 ]
-
 export default {
   server: {
     setup(ctx) {
       ctx.state.ids = ctx.state.ids || []
       if (ctx.state.ids.length > 0) return  // hot-reload guard
-
-      // Ground — this entity IS the ground
-      ctx.entity.custom = { mesh: 'box', color: 0x5a7a4a, roughness: 1, sx: HALF*2, sy: 0.5, sz: HALF*2 }
+      ctx.entity.custom = { mesh:'box', color:0x5a7a4a, sx:HALF*2, sy:0.5, sz:HALF*2 }
       ctx.physics.setStatic(true)
       ctx.physics.addBoxCollider([HALF, 0.25, HALF])
-
-      // Walls — spawn children each with box-static app
       for (const w of WALLS) {
-        const e = ctx.world.spawn(w.id, {
-          position: [w.x, w.y, w.z],
-          app: 'box-static',
-          config: { hx: w.hx, hy: w.hy, hz: w.hz, color: 0x7a6a5a }
-        })
+        const e = ctx.world.spawn(w.id, { position:[w.x,w.y,w.z], app:'box-static', config:{ hx:w.hx, hy:w.hy, hz:w.hz, color:0x7a6a5a } })
         if (e) ctx.state.ids.push(w.id)
       }
     },
-    teardown(ctx) {
-      for (const id of ctx.state.ids || []) ctx.world.destroy(id)
-      ctx.state.ids = []
-    }
+    teardown(ctx) { for (const id of ctx.state.ids||[]) ctx.world.destroy(id); ctx.state.ids = [] }
   },
-  client: {
-    render(ctx) {
-      return { position: ctx.entity.position, rotation: ctx.entity.rotation, custom: ctx.entity.custom }
-    }
-  }
+  client: { render(ctx) { return { position:ctx.entity.position, rotation:ctx.entity.rotation, custom:ctx.entity.custom } } }
 }
 ```
 
-### Step 3: box-static reusable app (`apps/box-static/index.js`)
-
-Reusable app for any static box primitive with physics. Config drives size and color:
-
+### `apps/box-static/index.js` — reusable static box primitive
 ```js
 export default {
   server: {
     setup(ctx) {
       const c = ctx.config
-      ctx.entity.custom = {
-        mesh: 'box',
-        color: c.color ?? 0x888888,
-        roughness: c.roughness ?? 0.9,
-        sx: (c.hx ?? 1) * 2, sy: (c.hy ?? 1) * 2, sz: (c.hz ?? 1) * 2
-      }
+      ctx.entity.custom = { mesh:'box', color:c.color??0x888888, sx:(c.hx??1)*2, sy:(c.hy??1)*2, sz:(c.hz??1)*2 }
       ctx.physics.setStatic(true)
-      ctx.physics.addBoxCollider([c.hx ?? 1, c.hy ?? 1, c.hz ?? 1])
+      ctx.physics.addBoxCollider([c.hx??1, c.hy??1, c.hz??1])
     }
   },
-  client: {
-    render(ctx) {
-      return { position: ctx.entity.position, rotation: ctx.entity.rotation, custom: ctx.entity.custom }
-    }
-  }
+  client: { render(ctx) { return { position:ctx.entity.position, rotation:ctx.entity.rotation, custom:ctx.entity.custom } } }
 }
 ```
 
 ---
 
-## Asset Loading — How It Works
-
-### Loading Sequence Gate
-
-The loading screen stays up until ALL of these pass simultaneously:
-1. WebSocket connected
-2. Player VRM model downloaded
-3. Environment model loaded (first entity with a `model` field, OR any entity without a model that creates a mesh)
-4. First snapshot received from server
-5. All entities from the **world config `entities` array** that have a `model` field are loaded
-
-**Critical:** Entities declared in `world.entities` that have a `model` are tracked by the client loading gate. Entities spawned later by `ctx.world.spawn()` at runtime are NOT part of the loading gate — they appear after the game starts.
-
-If you want a model to be part of the loading sequence, declare it in `world.entities`:
-
-```js
-// world/index.js
-entities: [
-  { id: 'environment', model: './apps/tps-game/schwust.glb', app: 'environment' },
-  //                   ^^ This model blocks the loading screen until loaded
-]
-```
-
-### Local Models
-
-Place GLB files inside your app folder. Reference with `./apps/<app-name>/file.glb`:
-
-```
-apps/my-arena/
-  index.js
-  floor.glb       <-- served automatically by StaticHandler
-  wall.glb
-```
-
-```js
-// In world/index.js:
-{ id: 'env', model: './apps/my-arena/floor.glb', app: 'environment' }
-
-// Or spawned at runtime:
-ctx.world.spawn('floor', { model: './apps/my-arena/floor.glb', ... })
-```
-
-The StaticHandler serves everything under `apps/` at the same path. No CDN, no hosting needed.
-
-### Remote Models (Verified Asset Library)
-
-The `https://github.com/anEntrypoint/assets` repository contains ~170 free GLB models.
-
-**URL pattern:** `https://raw.githubusercontent.com/anEntrypoint/assets/main/FILENAME.glb`
-
-**Verified filenames** (use these exactly — wrong filenames silently 404):
-
-```
-Vehicles & Junk:
-  broken_car_b6d2e66d_v1.glb          broken_car_b6d2e66d_v2.glb
-  crashed_car_f2b577ae_v1.glb         crashed_car_f2b577ae_v2.glb
-  crashed_pickup_truck_ae555020_v1.glb
-  crashed_rusty_minivan_f872ff37_v1.glb
-  Bus_junk_1.glb
-
-Containers & Industrial:
-  blue_shipping_container_60b5ea93_v1.glb
-  blue_shipping_container_63cc3905_v1.glb
-  dumpster_b076662a_v1.glb            dumpster_b076662a_v2.glb
-  garbage_can_6b3d052b_v1.glb         garbage_can_6b3d052b_v2.glb
-  crushed_oil_barrel_e450f43f_v1.glb  crushed_oil_barrel_e450f43f_v2.glb
-  fire_hydrant_ba0175c1_v1.glb        fire_hydrant_ba0175c1_v2.glb
-  fire_extinguisher_wall_mounted_bc0dddd4_v1.glb
-
-Office & Furniture:
-  break_room_chair_14a39c7b_v1.glb    break_room_chair_14a39c7b_v2.glb
-  break_room_couch_444abf63_v1.glb    break_room_table_09b9fd0d_v1.glb
-  filing_cabinet_0194476c_v1.glb      filing_cabinet_0194476c_v2.glb
-  fancy_reception_desk_58fde71d_v1.glb
-  cash_register_0c0dcad2_v1.glb
-  espresso_machine_e722ed8c_v1.glb
-  Couch.glb  Couch_2.glb  3chairs.glb
-
-Natural & Rocks:
-  large_rock_051293c4_v1.glb          large_rock_051293c4_v2.glb
-
-Misc:
-  Tin_Man_1.glb  Tin_Man_2.glb  Plants_3.glb  Urinals.glb  V_Machine_2.glb
-```
-
-**Remote models are NOT part of the loading gate.** They appear after game starts. Use them for decorative props, not required environment geometry.
-
-**NEVER guess asset filenames.** Only use names from the verified list above. Wrong URLs silently 404 — no model appears, no error thrown.
-
-### prop-static reusable app
+## World Config Schema
 
-For remote GLB props that need convex hull physics:
+All fields optional. `apps/world/index.js` exports a plain object.
 
 ```js
-// apps/prop-static/index.js
 export default {
-  server: {
-    setup(ctx) {
-      ctx.physics.setStatic(true)
-      if (ctx.entity.model) ctx.physics.addConvexFromModel(0)
-    }
+  port: 3001, tickRate: 128, gravity: [0,-9.81,0],
+  movement: {
+    maxSpeed: 4.0,         // code default is 8.0 — always override explicitly
+    groundAccel: 10.0, airAccel: 1.0, friction: 6.0, stopSpeed: 2.0,
+    jumpImpulse: 4.0,      // velocity SET (not added) on jump
+    crouchSpeedMul: 0.4, sprintSpeed: null  // null = maxSpeed * 1.75
   },
-  client: {
-    render(ctx) {
-      return { position: ctx.entity.position, rotation: ctx.entity.rotation, model: ctx.entity.model }
-    }
-  }
+  player: {
+    health: 100, capsuleRadius: 0.4, capsuleHalfHeight: 0.9, crouchHalfHeight: 0.45,
+    mass: 120, modelScale: 1.323,
+    feetOffset: 0.212      // feetOffset * modelScale = negative Y on model
+  },
+  scene: {
+    skyColor: 0x87ceeb, fogColor: 0x87ceeb, fogNear: 80, fogFar: 200,
+    ambientColor: 0xfff4d6, ambientIntensity: 0.3,
+    sunColor: 0xffffff, sunIntensity: 1.5, sunPosition: [21,50,20],
+    fillColor: 0x4488ff, fillIntensity: 0.4, fillPosition: [-20,30,-10],
+    shadowMapSize: 1024, shadowBias: 0.0038, shadowNormalBias: 0.6, shadowRadius: 12, shadowBlurSamples: 8
+  },
+  camera: {
+    fov: 70, shoulderOffset: 0.35, headHeight: 0.4,
+    zoomStages: [0,1.5,3,5,8], defaultZoomIndex: 2,
+    followSpeed: 12.0, snapSpeed: 30.0, mouseSensitivity: 0.002, pitchRange: [-1.4,1.4]
+  },
+  animation: { mixerTimeScale: 1.3, walkTimeScale: 2.0, sprintTimeScale: 0.56, fadeTime: 0.15 },
+  entities: [{ id:'env', model:'./apps/my-app/env.glb', position:[0,0,0], app:'environment', config:{} }],
+  playerModel: './apps/tps-game/Cleetus.vrm',
+  spawnPoint: [0,2,0]
 }
 ```
 
-Spawn remote props:
-
-```js
-const BASE = 'https://raw.githubusercontent.com/anEntrypoint/assets/main'
-ctx.world.spawn('dumpster-1', {
-  model: `${BASE}/dumpster_b076662a_v1.glb`,
-  position: [5, 0, -3],
-  rotation: [0, Math.sin(0.5), 0, Math.cos(0.5)],
-  app: 'prop-static'
-})
-```
-
 ---
 
-## Setup
-
-When no `apps/` directory exists in the working directory, scaffold it:
+## Asset Loading Gate
 
-```bash
-bunx spoint scaffold
-bunx spoint
-```
+Loading screen holds until ALL pass simultaneously:
+1. WebSocket connected
+2. Player VRM downloaded
+3. Any entity with `model` field (or entity creating a mesh) loaded
+4. First snapshot received
+5. All `world.entities` entries with `model` field loaded
 
-This copies the default apps (world config, tps-game, environment, etc.) into `./apps/` and starts the server. The engine (src/, client/) always comes from the npm package - never from the user's local folder.
+Entities spawned via `ctx.world.spawn()` at runtime are NOT in the gate. Declare in `world.entities` to block loading screen on a model.
 
-```bash
-bunx spoint          # start server
-```
-
-Open http://localhost:3001 in browser. Apps hot-reload on file save.
+---
 
-```bash
-bunx spoint-create-app my-app
-bunx spoint-create-app --template physics my-physics-object
-bunx spoint-create-app --template interactive my-button
-bunx spoint-create-app --template spawner my-spawner
-```
+## Remote Models — Verified Filenames
 
----
+URL: `https://raw.githubusercontent.com/anEntrypoint/assets/main/FILENAME.glb`
 
-## Project Structure
+**Never guess filenames** — wrong URLs silently 404, no error.
 
 ```
-your-project/
-  apps/
-    world/index.js          # World config (port, tickRate, gravity, entities, scene, camera)
-    my-app/index.js         # Your app (or apps/my-app.js)
+broken_car_b6d2e66d_v1.glb  broken_car_b6d2e66d_v2.glb  crashed_car_f2b577ae_v1.glb
+crashed_pickup_truck_ae555020_v1.glb  crashed_rusty_minivan_f872ff37_v1.glb  Bus_junk_1.glb
+blue_shipping_container_60b5ea93_v1.glb  blue_shipping_container_63cc3905_v1.glb
+dumpster_b076662a_v1.glb  dumpster_b076662a_v2.glb  garbage_can_6b3d052b_v1.glb
+crushed_oil_barrel_e450f43f_v1.glb  fire_hydrant_ba0175c1_v1.glb
+fire_extinguisher_wall_mounted_bc0dddd4_v1.glb
+break_room_chair_14a39c7b_v1.glb  break_room_couch_444abf63_v1.glb
+break_room_table_09b9fd0d_v1.glb  filing_cabinet_0194476c_v1.glb
+fancy_reception_desk_58fde71d_v1.glb  cash_register_0c0dcad2_v1.glb
+espresso_machine_e722ed8c_v1.glb  Couch.glb  Couch_2.glb  3chairs.glb
+large_rock_051293c4_v1.glb  Tin_Man_1.glb  Tin_Man_2.glb  Plants_3.glb  Urinals.glb  V_Machine_2.glb
 ```
 
-Start: `node server.js` or `bunx spoint`. Port from world config (default 8080, world default 3001).
-
----
-
-## App Anatomy
-
-An app is an ES module with a default export containing a `server` object and optionally a `client` object.
-
+Remote models are NOT in the loading gate. Use `prop-static` app for physics:
 ```js
+// apps/prop-static/index.js
 export default {
-  server: {
-    setup(ctx) {},           // Called once when entity is attached
-    update(ctx, dt) {},      // Called every tick, dt in seconds
-    teardown(ctx) {},        // Called on entity destroy or before hot reload
-    onMessage(ctx, msg) {},  // Called for player messages (including player_join, player_leave)
-    onEvent(ctx, payload) {}, // Called via ctx.bus or fireEvent
-    onCollision(ctx, other) {}, // other = { id, position, velocity }
-    onInteract(ctx, player) {},  // Called by fireInteract
-    onHandover(ctx, sourceEntityId, stateData) {} // Called via bus.handover
-  },
-
-  client: {
-    setup(engine) {},          // Called once when app loads on client
-    teardown(engine) {},       // Called before hot reload or disconnect
-    onFrame(dt, engine) {},    // Called every animation frame
-    onInput(input, engine) {}, // Called when input state is available
-    onEvent(payload, engine) {}, // Called when server sends message to this client
-    onMouseDown(e, engine) {},
-    onMouseUp(e, engine) {},
-    render(ctx) {}             // Returns entity render state + optional UI
-  }
-}
-```
-
----
-
-## World Config Schema
-
-`apps/world/index.js` exports a plain object. All fields optional.
-
-```js
-export default {
-  port: 3001,
-  tickRate: 128,
-  gravity: [0, -9.81, 0],
-
-  movement: {
-    maxSpeed: 4.0,           // Max horizontal speed (m/s). DEFAULT code value is 8.0 but world overrides it
-    groundAccel: 10.0,       // Ground acceleration
-    airAccel: 1.0,           // Air acceleration (no friction in air)
-    friction: 6.0,           // Ground friction coefficient
-    stopSpeed: 2.0,          // Speed threshold for minimum friction control
-    jumpImpulse: 4.0,        // Upward velocity set on jump
-    collisionRestitution: 0.2,
-    collisionDamping: 0.25,
-    crouchSpeedMul: 0.4,     // Speed multiplier when crouching
-    sprintSpeed: null        // null = maxSpeed * 1.75
-  },
-
-  player: {
-    health: 100,
-    capsuleRadius: 0.4,
-    capsuleHalfHeight: 0.9,
-    crouchHalfHeight: 0.45,
-    mass: 120,
-    modelScale: 1.323,
-    feetOffset: 0.212        // Ratio: feetOffset * modelScale = negative Y offset on model
-  },
-
-  scene: {
-    skyColor: 0x87ceeb,
-    fogColor: 0x87ceeb,
-    fogNear: 80,
-    fogFar: 200,
-    ambientColor: 0xfff4d6,
-    ambientIntensity: 0.3,
-    sunColor: 0xffffff,
-    sunIntensity: 1.5,
-    sunPosition: [21, 50, 20],
-    fillColor: 0x4488ff,
-    fillIntensity: 0.4,
-    fillPosition: [-20, 30, -10],
-    shadowMapSize: 1024,
-    shadowBias: 0.0038,
-    shadowNormalBias: 0.6,
-    shadowRadius: 12,
-    shadowBlurSamples: 8
-  },
-
-  camera: {
-    fov: 70,
-    shoulderOffset: 0.35,
-    headHeight: 0.4,
-    zoomStages: [0, 1.5, 3, 5, 8],
-    defaultZoomIndex: 2,
-    followSpeed: 12.0,
-    snapSpeed: 30.0,
-    mouseSensitivity: 0.002,
-    pitchRange: [-1.4, 1.4]
-  },
-
-  animation: {
-    mixerTimeScale: 1.3,
-    walkTimeScale: 2.0,
-    sprintTimeScale: 0.56,
-    fadeTime: 0.15
-  },
-
-  entities: [
-    {
-      id: 'environment',
-      model: './apps/tps-game/schwust.glb',
-      position: [0, 0, 0],
-      app: 'environment',       // App name matching apps/ folder or file
-      config: { myKey: 'val' }  // Accessible as ctx.config.myKey in the app
-    }
-  ],
-
-  playerModel: './apps/tps-game/Cleetus.vrm',
-  spawnPoint: [-35, 3, -65]
+  server: { setup(ctx) { ctx.physics.setStatic(true); if (ctx.entity.model) ctx.physics.addConvexFromModel(0) } },
+  client: { render(ctx) { return { position:ctx.entity.position, rotation:ctx.entity.rotation, model:ctx.entity.model } } }
 }
+// Spawn:
+const BASE = 'https://raw.githubusercontent.com/anEntrypoint/assets/main'
+ctx.world.spawn('dumpster-1', { model:`${BASE}/dumpster_b076662a_v1.glb`, position:[5,0,-3], app:'prop-static' })
 ```
 
 ---
 
-## Server-Side Context API (ctx)
-
-The `ctx` object is passed to every server lifecycle method.
+## Server ctx API
 
 ### ctx.entity
-
 ```js
-ctx.entity.id           // string - unique ID (read-only)
-ctx.entity.model        // string|null - GLB/VRM asset path
-ctx.entity.position     // [x, y, z] array - read/write
-ctx.entity.rotation     // [x, y, z, w] quaternion - read/write
-ctx.entity.scale        // [x, y, z] array - read/write
-ctx.entity.velocity     // [x, y, z] array - read/write
-ctx.entity.custom       // any - arbitrary data sent to clients in snapshots (keep small)
-ctx.entity.parent       // string|null - parent entity ID (read-only)
-ctx.entity.children     // string[] - copy of child entity IDs (read-only)
-ctx.entity.worldTransform  // { position, rotation, scale } - computed world space transform
-ctx.entity.destroy()    // Destroy this entity and all children
+ctx.entity.id / model / position / rotation / scale / velocity / custom / parent / children / worldTransform
+ctx.entity.destroy()
+// position: [x,y,z]  rotation: [x,y,z,w] quaternion  custom: any (sent in every snapshot — keep small)
 ```
 
 ### ctx.state
 
-Persistent state object. Survives hot reload. Assign properties directly or merge.
-
-```js
-ctx.state.score = 0
-ctx.state.players = new Map()
-ctx.state = { key: 'value' }  // Object.assign merge (does NOT replace the object)
-```
-
-Initialize with `||` to preserve values across hot reload:
-
+Persists across hot reloads. Re-register timers and bus subscriptions in every setup:
 ```js
 setup(ctx) {
-  ctx.state.score = ctx.state.score || 0
-  ctx.state.data = ctx.state.data || new Map()
+  ctx.state.score = ctx.state.score || 0      // || preserves value on reload
+  ctx.state.data  = ctx.state.data  || new Map()
+  ctx.bus.on('event', handler)                // always re-register
+  ctx.time.every(1, ticker)                   // always re-register
 }
 ```
 
 ### ctx.config
 
-Read-only. Set in the world entities array under `config: {}`.
-
-```js
-// world/index.js:
-{ id: 'my-entity', app: 'my-app', config: { radius: 5 } }
-// In app:
-ctx.config.radius  // 5
-```
+Read-only. Set in world: `{ id:'x', app:'y', config:{ radius:5 } }` → `ctx.config.radius`
 
 ### ctx.interactable
 
-Declares this entity as interactable. The engine handles proximity detection, the E-key prompt UI, and cooldown automatically. The app only needs to implement `onInteract`.
-
+Engine handles proximity, E-key prompt, and cooldown. App only needs `onInteract`:
 ```js
-setup(ctx) {
-  ctx.interactable({ prompt: 'Press E to open', radius: 2, cooldown: 1000 })
-},
-
-onInteract(ctx, player) {
-  ctx.players.send(player.id, { type: 'opened', message: 'Opened!' })
-}
+setup(ctx) { ctx.interactable({ prompt:'Press E', radius:2, cooldown:1000 }) },
+onInteract(ctx, player) { ctx.players.send(player.id, { type:'opened' }) }
 ```
 
-Options:
-- `prompt` — text shown in the HUD when player is within range (default: `'Press E'`)
-- `radius` — interaction distance in world units (default: `3`)
-- `cooldown` — milliseconds between allowed interactions per player (default: `500`)
-
-The engine client automatically shows and hides the prompt when the local player enters or leaves the radius. No client-side code is needed for basic interactables.
-
 ### ctx.physics
-
 ```js
-ctx.physics.setStatic(true)    // Immovable
-ctx.physics.setDynamic(true)   // Affected by physics
-ctx.physics.setKinematic(true) // Moved by code, pushes dynamic bodies
+ctx.physics.setStatic(true) / setDynamic(true) / setKinematic(true)
 ctx.physics.setMass(kg)
-
-ctx.physics.addBoxCollider(size)
-// size: number (uniform) or [hx, hy, hz] half-extents
-// Example: ctx.physics.addBoxCollider([0.75, 0.25, 0.75])
-
+ctx.physics.addBoxCollider(size)              // number or [hx,hy,hz] half-extents
 ctx.physics.addSphereCollider(radius)
-
-ctx.physics.addCapsuleCollider(radius, fullHeight)
-// fullHeight is the FULL height. Internally divided by 2 for Jolt.
-
-ctx.physics.addTrimeshCollider()
-// Builds static mesh from entity.model path. Static only.
-
-ctx.physics.addConvexCollider(points)
-// points: flat Float32Array or Array of [x,y,z,x,y,z,...] vertex positions
-// Builds a ConvexHullShape from the provided point cloud. Supports all motion types.
-
-ctx.physics.addConvexFromModel(meshIndex = 0)
-// Extracts vertex positions from entity.model GLB and builds ConvexHullShape.
-// Simpler and faster than trimesh for dynamic objects like vehicles/crates.
-
-ctx.physics.addForce([fx, fy, fz])    // Impulse: velocity += force / mass
-ctx.physics.setVelocity([vx, vy, vz]) // Set velocity directly
+ctx.physics.addCapsuleCollider(radius, fullHeight)  // fullHeight=total height, halved internally
+ctx.physics.addTrimeshCollider()              // static-only, uses entity.model
+ctx.physics.addConvexCollider(points)         // flat [x,y,z,...], all motion types
+ctx.physics.addConvexFromModel(meshIndex=0)   // extracts verts from entity.model GLB
+ctx.physics.addForce([fx,fy,fz])              // velocity += force/mass
+ctx.physics.setVelocity([vx,vy,vz])
 ```
 
 ### ctx.world
-
 ```js
-ctx.world.spawn(id, config)
-// id: string|null (null = auto-generate as 'entity_N')
-// Returns: entity object or null
-
+ctx.world.spawn(id, config)   // id: string|null (null=auto-generate). Returns entity|null.
 ctx.world.destroy(id)
-ctx.world.getEntity(id)           // Returns entity object or null
-ctx.world.query(filterFn)         // Returns entity[] matching filter
-ctx.world.nearby(pos, radius)     // Returns entity IDs within radius
-ctx.world.reparent(eid, parentId) // Change parent (null = detach from parent)
-ctx.world.attach(entityId, appName)
-ctx.world.detach(entityId)
-ctx.world.gravity                 // [x, y, z] read-only
-```
-
-Entity config for spawn:
+ctx.world.getEntity(id)       // entity|null
+ctx.world.query(filterFn)     // entity[]
+ctx.world.nearby(pos, radius) // entity IDs within radius
+ctx.world.reparent(eid, parentId)  // parentId null = detach
+ctx.world.attach(entityId, appName) / detach(entityId)
+ctx.world.gravity             // [x,y,z] read-only
 
-```js
-ctx.world.spawn('my-id', {
-  model: './path/to/model.glb',
-  position: [x, y, z],            // default [0,0,0]
-  rotation: [x, y, z, w],         // default [0,0,0,1]
-  scale: [x, y, z],               // default [1,1,1]
-  parent: 'parent-entity-id',
-  app: 'app-name',                 // Auto-attach app
-  config: { ... },                 // ctx.config in attached app
-  autoTrimesh: true                // Auto-add trimesh collider from model
-})
+// spawn config keys: model, position, rotation, scale, parent, app, config, autoTrimesh
 ```
 
 ### ctx.players
-
 ```js
 ctx.players.getAll()
-// Returns Player[] where each player has:
-// { id: string, state: { position, velocity, health, onGround, crouch, lookPitch, lookYaw, interact } }
-
-ctx.players.getNearest([x, y, z], radius)
-// Returns nearest player within radius, or null
-
-ctx.players.send(playerId, { type: 'my_type', ...data })
-// Client receives in onEvent(payload, engine)
-
-ctx.players.broadcast({ type: 'my_type', ...data })
-
-ctx.players.setPosition(playerId, [x, y, z])
-// Teleports player - no collision check during teleport
-```
-
-Player state fields:
-
-```js
-player.state.position   // [x, y, z]
-player.state.velocity   // [x, y, z]
-player.state.health     // number
-player.state.onGround   // boolean
-player.state.crouch     // 0 or 1
-player.state.lookPitch  // radians
-player.state.lookYaw    // radians
-player.state.interact   // boolean - true if player pressed interact this tick
-```
-
-You can directly mutate `player.state.health`, `player.state.velocity`, etc. and the change propagates in the next snapshot.
-
-### ctx.network
-
-```js
-ctx.network.broadcast(msg)        // Same as ctx.players.broadcast
-ctx.network.sendTo(playerId, msg) // Same as ctx.players.send
+// Player: { id, state: { position, velocity, health, onGround, crouch, lookPitch, lookYaw, interact } }
+ctx.players.getNearest([x,y,z], radius)  // Player|null
+ctx.players.send(playerId, msg)           // client receives in onEvent(payload, engine)
+ctx.players.broadcast(msg)
+ctx.players.setPosition(playerId, [x,y,z])  // teleport — no collision check
 ```
+Mutate `player.state.health` / `player.state.velocity` directly — propagates in next snapshot.
 
 ### ctx.bus
-
-Scoped EventBus. Auto-cleaned on teardown.
-
 ```js
-ctx.bus.on('channel.name', (event) => {
-  event.channel  // string
-  event.data     // your payload
-  event.meta     // { timestamp, sourceEntity }
-})
-
-ctx.bus.once('channel.name', handler)
-ctx.bus.emit('channel.name', data)
-ctx.bus.handover(targetEntityId, stateData)
-// Fires onHandover(ctx, sourceEntityId, stateData) on the target entity's app
+ctx.bus.on('channel', (e) => { e.data; e.channel; e.meta })
+ctx.bus.once('channel', handler)
+ctx.bus.emit('channel', data)            // meta.sourceEntity set automatically
+ctx.bus.on('combat.*', handler)          // wildcard prefix
+ctx.bus.handover(targetEntityId, data)   // fires onHandover on target
 ```
+`system.*` prefix is reserved — do not emit on it.
 
 ### ctx.time
-
 ```js
-ctx.time.tick       // Current tick number
-ctx.time.deltaTime  // Same as dt in update()
-ctx.time.elapsed    // Total seconds since runtime start
+ctx.time.tick / deltaTime / elapsed
+ctx.time.after(seconds, fn)  // one-shot, cleared on teardown
+ctx.time.every(seconds, fn)  // repeating, cleared on teardown
+```
 
-ctx.time.after(seconds, fn)   // One-shot timer
-ctx.time.every(seconds, fn)   // Repeating timer
-// All timers are cleared on teardown automatically
+### ctx.raycast
+```js
+const hit = ctx.raycast([x,y,z], [dx,dy,dz], maxDist)
+// { hit:bool, distance:number, body:bodyId|null, position:[x,y,z]|null }
 ```
 
 ### ctx.storage
-
-Async key-value storage, namespaced to app name. Null if no adapter configured.
-
 ```js
 if (ctx.storage) {
   await ctx.storage.set('key', value)
   const val = await ctx.storage.get('key')
   await ctx.storage.delete('key')
-  const exists = await ctx.storage.has('key')
-  const keys = await ctx.storage.list('')  // all keys in namespace
-}
-```
-
-### ctx.debug
-
-```js
-ctx.debug.log('message', optionalData)
-```
-
-### ctx.raycast
-
-```js
-const hit = ctx.raycast(origin, direction, maxDistance)
-// origin: [x, y, z]
-// direction: [x, y, z] normalized unit vector
-// maxDistance: number (default 1000)
-// Returns: { hit: boolean, distance: number, body: bodyId|null, position: [x,y,z]|null }
-
-const result = ctx.raycast([x, 20, z], [0, -1, 0], 30)
-if (result.hit) {
-  const groundY = result.position[1]
+  const keys = await ctx.storage.list('')
 }
 ```
 
 ---
 
-## Client-Side Context API
-
-### render(ctx)
+## Client API
 
+### render(ctx) — return value
 ```js
-client: {
-  render(ctx) {
-    // ctx.entity   - entity data from latest snapshot
-    // ctx.players  - array of all player states from snapshot
-    // ctx.engine   - reference to engineCtx
-    // ctx.h        - hyperscript function for UI
-    // ctx.playerId - local player's ID
-
-    return {
-      position: ctx.entity.position,  // Required
-      rotation: ctx.entity.rotation,  // Optional
-      model: ctx.entity.model,        // Optional - override model
-      custom: ctx.entity.custom,      // Optional - drives procedural mesh
-      ui: ctx.h ? ctx.h('div', ...) : null  // Optional - HTML overlay
-    }
-  }
-}
+{ position:[x,y,z], rotation:[x,y,z,w], model:'path.glb', custom:{...}, ui:ctx.h('div',...) }
 ```
 
-### engine Object (client callbacks)
-
-Available in `setup(engine)`, `onFrame(dt, engine)`, `onInput(input, engine)`, `onEvent(payload, engine)`, `teardown(engine)`.
-
+### engine object
 ```js
-engine.THREE          // THREE.js library
-engine.scene          // THREE.Scene
-engine.camera         // THREE.Camera
-engine.renderer       // THREE.WebGLRenderer
-engine.playerId       // Local player's string ID
-engine.client.state   // { players: [...], entities: [...] } - latest snapshot
-
-engine.cam.getAimDirection(position)  // Returns normalized [dx, dy, dz]
-engine.cam.punch(intensity)           // Aim punch (visual recoil)
-
+engine.THREE / scene / camera / renderer
+engine.playerId                              // local player ID
+engine.client.state                          // { players:[...], entities:[...] }
+engine.cam.getAimDirection(position)         // normalized [dx,dy,dz]
+engine.cam.punch(intensity)                  // visual recoil
 engine.players.getAnimator(playerId)
-engine.players.setExpression(playerId, expressionName, weight)
+engine.players.setExpression(playerId, name, weight)
 engine.players.setAiming(playerId, isAiming)
-
-engine.mobileControls?.registerInteractable(id, label)
-engine.mobileControls?.unregisterInteractable(id)
-```
-
-### ctx.h (hyperscript for UI)
-
-```js
-ctx.h(tagName, props, ...children)
-// tagName: 'div', 'span', 'button', etc.
-// props: object with HTML attributes and inline styles, or null
-// children: strings, numbers, h() calls, null (null ignored)
-
-ctx.h('div', { style: 'color:red;font-size:24px' }, 'Hello World')
-ctx.h('div', { class: 'hud' },
-  ctx.h('span', null, `HP: ${hp}`),
-  hp < 30 ? ctx.h('span', { style: 'color:red' }, 'LOW HP') : null
-)
-```
-
-Client apps cannot use `import`. All dependencies come via `engine`.
-
-### onInput(input, engine)
-
-```js
-input.forward   // boolean
-input.backward  // boolean
-input.left      // boolean
-input.right     // boolean
-input.jump      // boolean
-input.crouch    // boolean
-input.sprint    // boolean
-input.shoot     // boolean
-input.reload    // boolean
-input.interact  // boolean
-input.yaw       // number - camera yaw in radians
-input.pitch     // number - camera pitch in radians
-```
-
----
-
-## App Lifecycle
-
-```
-Server start:
-  AppLoader.loadAll() -> registers all apps in apps/
-  For each entity in world.entities:
-    spawnEntity() -> _attachApp() -> server.setup(ctx)
-
-Each tick (128/sec):
-  for each entity with app: server.update(ctx, dt)
-  tick timers
-  tick sphere collisions -> server.onCollision()
-
-On file save (hot reload):
-  AppLoader detects change, queues reload
-  End of current tick: drain queue
-    server.teardown(ctx)        [bus scope destroyed, timers cleared]
-    new AppContext               [ctx.state reference PRESERVED on entity]
-    server.setup(ctx)           [fresh context, same state data]
-
-On entity destroy:
-  Cascade to all children
-  server.teardown(ctx)
-  entity removed from Map
-
-Client:
-  Receives APP_MODULE message with app source
-  client.setup(engine) called once
-  Each frame: client.onFrame(dt, engine), client.render(ctx)
-  On server message: client.onEvent(payload, engine)
-  On hot reload: client.teardown(engine) -> location.reload()
-```
-
----
-
-## Entity System
-
-Entities are plain objects in a Map. Not class instances.
-
-```js
-{
-  id: string,
-  model: string|null,
-  position: [x, y, z],
-  rotation: [x, y, z, w],     // quaternion
-  scale: [x, y, z],
-  velocity: [x, y, z],
-  mass: 1,
-  bodyType: 'static'|'dynamic'|'kinematic',
-  collider: null | { type, ...params },
-  parent: string|null,
-  children: Set<string>,
-  custom: any,                  // sent to clients in every snapshot - keep small
-  _appState: object,            // ctx.state - persists across hot reloads
-  _appName: string|null,
-  _config: object|null
-}
 ```
 
-Destroying a parent destroys all children. World transform is computed recursively up the parent chain.
-
----
-
-## Physics API
-
-### Shape Types and Methods
-
+### ctx.h — hyperscript
 ```js
-ctx.physics.addBoxCollider(size)
-// size: number (uniform half-extent) or [hx, hy, hz]
-
-ctx.physics.addSphereCollider(radius)
-
-ctx.physics.addCapsuleCollider(radius, fullHeight)
-// fullHeight = total height. Halved internally before passing to Jolt.
-
-ctx.physics.addTrimeshCollider()
-// Static trimesh from entity.model. Only for static bodies.
-
-ctx.physics.addConvexCollider(points)
-// points: flat array [x,y,z,x,y,z,...]. Supports all motion types (dynamic/kinematic/static).
-
-ctx.physics.addConvexFromModel(meshIndex = 0)
-// Extracts vertices from entity.model GLB and builds ConvexHullShape. Good for dynamic vehicles/crates.
-
-ctx.physics.addForce([fx, fy, fz])     // velocity += force / mass
-ctx.physics.setVelocity([vx, vy, vz])
+ctx.h(tag, props, ...children)  // props = attrs/inline styles or null; null children ignored
+ctx.h('div', { style:'color:red' }, 'Hello')
 ```
+Client apps cannot use `import` — all import statements stripped before evaluation. Use `engine.*` for deps.
 
-### Body Types
-
-- `static`: immovable, other bodies collide with it
-- `dynamic`: affected by gravity and forces
-- `kinematic`: moved by code, pushes dynamic bodies
-
-### Jolt WASM Memory Rules
-
-Do NOT call Jolt methods directly from app code. Use `ctx.physics` only. The engine destroys all WASM heap objects internally. Every Jolt getter call and raycast creates temporary heap objects that must be destroyed - the engine handles this automatically via the ctx API.
+### onInput fields
+`forward backward left right jump crouch sprint shoot reload interact yaw pitch`
 
 ---
 
-## EventBus
+## Procedural Mesh (custom field)
 
-Shared pub/sub system. Scoped per entity - all subscriptions auto-cleaned on teardown.
+When no GLB set, `custom` drives geometry — primary way to create primitives without any GLB file.
 
 ```js
-// Subscribe
-const unsub = ctx.bus.on('channel.name', (event) => {
-  event.data     // your payload
-  event.channel  // 'channel.name'
-  event.meta     // { timestamp, sourceEntity }
-})
-unsub()  // manual unsubscribe if needed
-
-// One-time
-ctx.bus.once('channel.name', handler)
-
-// Emit (meta.sourceEntity = this entity's ID automatically)
-ctx.bus.emit('channel.name', { key: 'value' })
-
-// Wildcard - subscribe to prefix
-ctx.bus.on('combat.*', (event) => {
-  // Receives: combat.fire, combat.hit, combat.death, etc.
-})
-
-// Handover - transfer state to another entity's app
-ctx.bus.handover(targetEntityId, stateData)
-// Fires: server.onHandover(ctx, sourceEntityId, stateData) on target
+{ mesh:'box',      color:0xff8800, roughness:0.8, sx:2, sy:1, sz:2 }   // sx/sy/sz = FULL dimensions
+{ mesh:'sphere',   color:0x00ff00, r:1, seg:16 }
+{ mesh:'cylinder', r:0.4, h:0.1, seg:16, color:0xffd700, metalness:0.8,
+                   emissive:0xffa000, emissiveIntensity:0.3,
+                   light:0xffd700, lightIntensity:1, lightRange:4 }
+{ ..., hover:0.15, spin:1 }                  // Y oscillation amplitude (units), rotation (rad/sec)
+{ ..., glow:true, glowColor:0x00ff88, glowIntensity:0.5 }
+{ mesh:'box', label:'PRESS E' }
 ```
 
-### Reserved Channels
-
-`system.*` prefix is reserved. Events on `system.*` do NOT trigger the `*` catch-all logger. Do not emit on `system.*` from app code.
-
-### Cross-App Pattern
-
-```js
-// App A (power-crate) emits:
-ctx.bus.emit('powerup.collected', { playerId, duration: 45, speedMultiplier: 1.2 })
-
-// App B (tps-game) subscribes:
-ctx.bus.on('powerup.collected', (event) => {
-  const { playerId, duration } = event.data
-  ctx.state.buffs.set(playerId, { expiresAt: Date.now() + duration * 1000 })
-})
-```
-
----
-
-## Message Types (Hex Reference)
-
-Apps do not use these directly. Listed for debugging and understanding the transport layer.
-
-| Name | Hex | Direction | Notes |
-|------|-----|-----------|-------|
-| HANDSHAKE | 0x01 | C→S | Initial connection |
-| HANDSHAKE_ACK | 0x02 | S→C | Connection accepted |
-| HEARTBEAT | 0x03 | C→S | Every 1000ms, 3s timeout |
-| HEARTBEAT_ACK | 0x04 | S→C | |
-| SNAPSHOT | 0x10 | S→C | Full world state |
-| INPUT | 0x11 | C→S | Player input |
-| STATE_CORRECTION | 0x12 | S→C | Physics correction |
-| DELTA_UPDATE | 0x13 | S→C | Delta snapshot |
-| PLAYER_JOIN | 0x20 | S→C | Player connected |
-| PLAYER_LEAVE | 0x21 | S→C | Player disconnected |
-| ENTITY_SPAWN | 0x30 | S→C | New entity |
-| ENTITY_DESTROY | 0x31 | S→C | Entity removed |
-| ENTITY_UPDATE | 0x32 | S→C | Entity state change |
-| APP_EVENT | 0x33 | S→C | ctx.players.send/broadcast payload |
-| HOT_RELOAD | 0x70 | S→C | Triggers location.reload() on client |
-| WORLD_DEF | 0x71 | S→C | World configuration |
-| APP_MODULE | 0x72 | S→C | Client app source code |
-| BUS_EVENT | 0x74 | S→C | Bus event forwarded to client |
-
-Heartbeat: any message from client resets the 3-second timeout. Client sends explicit heartbeat every 1000ms. 3s silence = disconnected.
+**sx/sy/sz are FULL size. addBoxCollider takes HALF-extents.** `sx:4,sy:2` → `addBoxCollider([2,1,...])`
 
 ---
 
-## Snapshot Format
+## AppLoader — Blocked Strings
 
-Snapshots sent at tickRate (128/sec) only when players are connected.
+Any of these anywhere in source (including comments) silently prevents load, no throw:
 
-### Player Array (positional - do not reorder)
-
-```
-[0]id  [1]px [2]py [3]pz  [4]rx [5]ry [6]rz [7]rw  [8]vx [9]vy [10]vz  [11]onGround  [12]health  [13]inputSeq  [14]crouch  [15]lookPitch  [16]lookYaw
-```
-
-- Position precision: 2 decimal places (×100 quantization)
-- Rotation precision: 4 decimal places (×10000 quantization)
-- health: rounded integer
-- onGround: 1 or 0
-- lookPitch/lookYaw: 0-255 (8-bit encoded, full range)
-
-### Entity Array (positional - do not reorder)
-
-```
-[0]id  [1]model  [2]px [3]py [4]pz  [5]rx [6]ry [7]rz [8]rw  [9]bodyType  [10]custom
-```
-
-- Same position/rotation quantization as players
-- custom: any JSON-serializable value (null if not set)
-
-Changing field order or count breaks all clients silently (wrong positions, no error).
-
-### Delta Snapshots
-
-Unchanged entities are omitted. Removed entities appear in a `removed` string array. Players are always fully encoded (no delta). When StageLoader is active, each player gets a different snapshot with only nearby entities (within relevanceRadius, default 200 units).
+`process.exit`  `child_process`  `require(`  `__proto__`  `Object.prototype`  `globalThis`  `eval(`  `import(`
 
 ---
 
-## Collision Detection
-
-Two separate systems run simultaneously.
-
-### Jolt Physics (player-world, rigid bodies)
-
-Automatic. Players collide with static trimesh geometry. Dynamic bodies collide with everything. No app API needed.
-
-### App Sphere Collisions (entity-entity)
-
-Runs every tick. For entities that have both a collider AND an attached app, sphere-overlap tests fire `onCollision`:
-
-```js
-server: {
-  setup(ctx) {
-    ctx.physics.addSphereCollider(1.5)  // Must set collider to receive events
-  },
-  onCollision(ctx, other) {
-    // other: { id, position, velocity }
-  }
-}
-```
-
-Collision radius per shape type:
-- sphere: radius value
-- capsule: max(radius, height/2)
-- box: max of all half-extents
-
-This is sphere-vs-sphere approximation. Use for pickups, triggers, proximity - not precise physics.
-
-### Player-Player Collision
-
-Custom capsule separation runs after the physics step. Engine-managed. No app API.
-
----
-
-## Movement Config
-
-Quake-style movement. Defined in `world.movement`.
-
-```js
-movement: {
-  maxSpeed: 4.0,      // IMPORTANT: code default is 8.0, world config overrides. Always set explicitly.
-  groundAccel: 10.0,  // Ground acceleration (applied with friction simultaneously)
-  airAccel: 1.0,      // Air acceleration (no friction in air = air strafing)
-  friction: 6.0,      // Ground friction
-  stopSpeed: 2.0,     // Min speed for friction calculation (prevents infinite decel)
-  jumpImpulse: 4.0,   // Upward velocity SET (not added) on jump
-  crouchSpeedMul: 0.4,
-  sprintSpeed: null   // null = maxSpeed * 1.75
-}
-```
-
-Key behavior: horizontal velocity (XZ) is wish-based. After physics step, the wish velocity overwrites the XZ physics result. Only Y velocity comes from physics (gravity/jumping). This is why `player.state.velocity[0]` and `[2]` reflect wish velocity, not physics result.
-
----
-
-## Hot Reload
-
-### What Survives
-
-`ctx.state` (stored on `entity._appState`) survives. The reference is kept on the entity across hot reloads.
-
-### What Does NOT Survive
-
-- `ctx.time` timers (must re-register in setup)
-- `ctx.bus` subscriptions (must re-subscribe in setup)
-- Any closures
-- Client `this` properties (reset on location.reload)
-
-### Hot Reload Safety Pattern
-
-```js
-setup(ctx) {
-  // Preserve existing values:
-  ctx.state.score = ctx.state.score || 0
-  ctx.state.data = ctx.state.data || new Map()
-
-  // Always re-register (cleared on teardown):
-  ctx.bus.on('some.event', handler)
-  ctx.time.every(1, ticker)
-}
-```
-
-### Timing
-
-App reloads never happen mid-tick. Queue drains at end of each tick. After each reload, client heartbeat timers are reset for all connections to prevent disconnect during slow reloads. After 3 consecutive failures, AppLoader stops auto-reloading that module until server restart (exponential backoff: 100ms, 200ms, 400ms max).
-
----
-
-## Client Rendering
-
-### GLB Shader Stall Prevention
-
-The engine handles GPU shader warmup in two phases — no action is needed from app code:
-
-1. **Initial load**: After the loading screen gates pass (assets, environment, first snapshot, first-snapshot entities all loaded), the loading screen hides and `warmupShaders()` runs asynchronously. It calls `renderer.compileAsync(scene, camera)`, disables frustum culling, renders twice to upload GPU data, then restores culling. This covers all entities present at startup.
-
-2. **Post-load dynamic entities**: For GLBs added after the loading screen is hidden, `loadEntityModel` calls `renderer.compileAsync(scene, camera)` immediately after adding the mesh to the scene.
-
-VRM players use a separate one-time warmup (`_vrmWarmupDone`) that fires `renderer.compileAsync(scene, camera)` after the first player model loads.
-
-### render(ctx) Return Value
-
-```js
-return {
-  position: [x, y, z],      // Required
-  rotation: [x, y, z, w],   // Optional
-  model: 'path.glb',         // Optional - override model
-  custom: { ... },           // Optional - drives procedural mesh rendering
-  ui: h('div', ...)          // Optional - HTML overlay
-}
-```
-
-### Entity custom Field - Procedural Mesh Conventions
+## Critical Caveats
 
-When no GLB model is set, `custom` drives procedural geometry. This is the primary way to create walls, floors, and visible primitives without any GLB file.
+**Physics only activates inside app setup().** `entity.bodyType = 'static'` does nothing without an app calling `ctx.physics.*`.
 
 ```js
-// Box — sx/sy/sz are FULL dimensions (width/height/depth in world units)
-custom: { mesh: 'box', color: 0xff8800, roughness: 0.8, sx: 2, sy: 1, sz: 2 }
-
-// Sphere — r is radius
-custom: { mesh: 'sphere', color: 0x00ff00, r: 1, seg: 16 }
-
-// Cylinder — r is radius, h is full height, seg is polygon count
-custom: {
-  mesh: 'cylinder',
-  r: 0.4, h: 0.1, seg: 16,
-  color: 0xffd700,
-  roughness: 0.3, metalness: 0.8,
-  emissive: 0xffa000, emissiveIntensity: 0.3,
-  rotZ: Math.PI / 2,
-  light: 0xffd700, lightIntensity: 1, lightRange: 4
-}
-
-// Animation
-custom: { ..., hover: 0.15, spin: 1 }
-// hover: Y oscillation amplitude (units)
-// spin: rotation speed (radians/sec)
+// WRONG — entity renders but players fall through:
+const e = ctx.world.spawn('floor', {...}); e.bodyType = 'static'  // ignored
 
-// Glow (interaction feedback)
-custom: { ..., glow: true, glowColor: 0x00ff88, glowIntensity: 0.5 }
-
-// Label
-custom: { mesh: 'box', label: 'PRESS E' }
+// CORRECT:
+ctx.world.spawn('floor', { app:'box-static', config:{ hx:5, hy:0.25, hz:5 } })
 ```
 
-**Note on sx/sy/sz vs collider half-extents:** The `custom.sx/sy/sz` fields are the FULL visual size. The `addBoxCollider([hx, hy, hz])` takes HALF-extents. Always halve the visual size when computing the collider: `sx: 4, sy: 2, sz: 4` → `addBoxCollider([2, 1, 2])`.
-
-**Primitives with physics require an app.** Setting `entity.custom` only affects rendering. Physics colliders only activate when `ctx.physics.addBoxCollider()` etc. is called inside an app's `setup()`. Use the `box-static` app pattern (see Quick Start above) for primitive walls/floors.
+**maxSpeed default mismatch.** Code default is 8.0. Always set `movement.maxSpeed` explicitly.
 
----
+**Horizontal velocity is wish-based.** After physics step, wish velocity overwrites XZ physics result. `player.state.velocity[0/2]` = wish velocity. Only `velocity[1]` (Y) comes from physics.
 
-## AppLoader Security Restrictions
+**Capsule parameter order.** `addCapsuleCollider(radius, fullHeight)` — full height, halved internally. Reversed from Jolt's direct API which takes (halfHeight, radius).
 
-The following strings in app source (including in comments or string literals) cause silent load failure:
+**Trimesh is static-only.** Use `addConvexCollider` or `addConvexFromModel` for dynamic/kinematic.
 
-- `process.exit`
-- `child_process`
-- `require(`
-- `__proto__`
-- `Object.prototype`
-- `globalThis`
-- `eval(`
-- `import(`
+**`setTimeout` not cleared on hot reload.** `ctx.time.*` IS cleared. Manage raw timers manually in teardown.
 
-If blocked, AppLoader logs a console error and the app does not register. Entities using it spawn without a server app.
+**Destroying parent destroys all children.** Reparent first to preserve: `ctx.world.reparent(childId, null)`
 
-Static ES module `import` at the top of the file is fine - AppLoader uses dynamic import internally to load the file. Do NOT use dynamic `import(` inside app code.
+**setPosition teleports through walls** — physics pushes out next tick.
 
----
+**App sphere collision is O(n²).** Keep interactive entity count under ~50.
 
-## Common Patterns
+**Snapshots only sent when players > 0.** Entity state still updates, nothing broadcast.
 
-### Spawn entities on setup, destroy on teardown
-
-```js
-server: {
-  setup(ctx) {
-    ctx.state.spawned = ctx.state.spawned || []
-    if (ctx.state.spawned.length === 0) {
-      for (let i = 0; i < 5; i++) {
-        const id = `item_${Date.now()}_${i}`
-        const e = ctx.world.spawn(id, { position: [i * 3, 1, 0] })
-        if (e) {
-          e.custom = { mesh: 'sphere', color: 0xffff00, radius: 0.5 }
-          ctx.state.spawned.push(id)
-        }
-      }
-    }
-  },
-  teardown(ctx) {
-    for (const id of ctx.state.spawned || []) ctx.world.destroy(id)
-    ctx.state.spawned = []
-  }
-}
-```
-
-### Raycast to find ground spawn points
-
-```js
-function findSpawnPoints(ctx) {
-  const points = []
-  for (let x = -50; x <= 50; x += 10) {
-    for (let z = -50; z <= 50; z += 10) {
-      const hit = ctx.raycast([x, 30, z], [0, -1, 0], 40)
-      if (hit.hit && hit.position[1] > -5) {
-        points.push([x, hit.position[1] + 2, z])
-      }
-    }
-  }
-  if (points.length < 4) points.push([0, 5, 0], [10, 5, 10])
-  return points
-}
-```
-
-### Player join/leave handling
+**TickSystem max 4 steps per loop.** >4 ticks behind (~31ms at 128TPS) = silent drop.
 
+**Player join/leave arrive via onMessage:**
 ```js
 onMessage(ctx, msg) {
   if (!msg) return
   const pid = msg.playerId || msg.senderId
-  if (msg.type === 'player_join') {
-    ctx.state.scores = ctx.state.scores || new Map()
-    ctx.state.scores.set(pid, 0)
-  }
-  if (msg.type === 'player_leave') {
-    ctx.state.scores?.delete(pid)
-  }
-}
-```
-
-### Interact detection with cooldown
-
-Use `ctx.interactable()` — the engine handles proximity, prompt UI, and cooldown automatically.
-
-```js
-setup(ctx) {
-  ctx.interactable({ prompt: 'Press E', radius: 4, cooldown: 500 })
-},
-
-onInteract(ctx, player) {
-  ctx.players.send(player.id, { type: 'interact_response', message: 'Hello!' })
-  ctx.network.broadcast({ type: 'interact_effect', position: ctx.entity.position })
-}
-```
-
-### Area damage hazard
-
-```js
-update(ctx, dt) {
-  ctx.state.damageTimer = (ctx.state.damageTimer || 0) - dt
-  if (ctx.state.damageTimer > 0) return
-  ctx.state.damageTimer = 0.5
-  const radius = ctx.config.radius || 3
-  for (const player of ctx.players.getAll()) {
-    if (!player.state) continue
-    const pp = player.state.position
-    const dist = Math.hypot(
-      pp[0] - ctx.entity.position[0],
-      pp[1] - ctx.entity.position[1],
-      pp[2] - ctx.entity.position[2]
-    )
-    if (dist < radius) {
-      player.state.health = Math.max(0, (player.state.health || 100) - 10)
-      ctx.players.send(player.id, { type: 'hazard_damage', damage: 10 })
-    }
-  }
-}
-```
-
-### Moving platform
-
-```js
-update(ctx, dt) {
-  const s = ctx.state
-  if (!s.waypoints || s.waypoints.length < 2) return
-  s.waitTimer = (s.waitTimer || 0) - dt
-  if (s.waitTimer > 0) return
-  const wp = s.waypoints[s.wpIndex || 0]
-  const next = s.waypoints[((s.wpIndex || 0) + 1) % s.waypoints.length]
-  const dx = next[0] - ctx.entity.position[0]
-  const dy = next[1] - ctx.entity.position[1]
-  const dz = next[2] - ctx.entity.position[2]
-  const dist = Math.sqrt(dx*dx + dy*dy + dz*dz)
-  if (dist < 0.1) {
-    s.wpIndex = ((s.wpIndex || 0) + 1) % s.waypoints.length
-    s.waitTimer = s.waitTime || 1
-    return
-  }
-  const step = Math.min((s.speed || 5) * dt, dist)
-  ctx.entity.position[0] += (dx/dist) * step
-  ctx.entity.position[1] += (dy/dist) * step
-  ctx.entity.position[2] += (dz/dist) * step
-}
-```
-
-### Client UI with custom HUD
-
-For interaction prompts, use `ctx.interactable()` on the server — the engine renders the prompt automatically. For custom HUD elements (health bars, messages), use `render()`:
-
-```js
-client: {
-  onEvent(payload) {
-    if (payload.type === 'interact_response') { this._msg = payload.message; this._expire = Date.now() + 3000 }
-  },
-
-  render(ctx) {
-    const h = ctx.h
-    if (!h) return { position: ctx.entity.position }
-    return {
-      position: ctx.entity.position,
-      custom: ctx.entity.custom,
-      ui: this._msg && Date.now() < this._expire
-        ? h('div', { style: 'position:fixed;top:30%;left:50%;transform:translate(-50%,-50%);padding:16px 32px;background:rgba(0,0,0,0.8);border-radius:12px;color:#0f0;font-weight:bold' }, this._msg)
-        : null
-    }
-  }
-}
-```
-
-### Client health HUD
-
-```js
-client: {
-  render(ctx) {
-    const h = ctx.h
-    if (!h) return { position: ctx.entity.position }
-    const local = ctx.players?.find(p => p.id === ctx.engine?.playerId)
-    const hp = local?.health ?? 100
-    return {
-      position: ctx.entity.position,
-      ui: h('div', { style: 'position:fixed;bottom:20px;left:50%;transform:translateX(-50%);width:200px;height:20px;background:#333;border-radius:4px;overflow:hidden' },
-        h('div', { style: `width:${hp}%;height:100%;background:${hp > 60 ? '#0f0' : hp > 30 ? '#ff0' : '#f00'};transition:width 0.2s` }),
-        h('span', { style: 'position:absolute;width:100%;text-align:center;color:#fff;font-size:12px;line-height:20px' }, String(hp))
-      )
-    }
-  }
-}
-```
-
-### Cross-app EventBus communication
-
-```js
-// Emitter app setup:
-ctx.bus.emit('combat.fire', { shooterId, origin, direction })
-
-// Listener app setup:
-ctx.bus.on('combat.fire', (event) => {
-  const { shooterId, origin, direction } = event.data
-  // handle shot...
-})
-ctx.bus.on('combat.*', (event) => {
-  // catches combat.fire, combat.hit, combat.kill, etc.
-})
-```
-
----
-
-## Critical Caveats
-
-### Spawned entities need their own app to have physics
-
-Calling `ctx.world.spawn()` creates an entity but does NOT create a physics body. Physics is only created when `ctx.physics.addBoxCollider()` (or any other physics call) runs inside that entity's app `setup()`.
-
-To create a wall/floor with physics via `ctx.world.spawn()`, give it an app:
-
-```js
-// WRONG — entity appears visually but has no physics, players fall through
-const e = ctx.world.spawn('floor', { position: [0, 0, 0] })
-e.custom = { mesh: 'box', sx: 10, sy: 0.5, sz: 10 }
-e.bodyType = 'static'          // does nothing without an app physics call
-e.collider = { ... }           // does nothing without an app physics call
-
-// CORRECT — use box-static app which calls ctx.physics.addBoxCollider in setup
-ctx.world.spawn('floor', {
-  position: [0, 0, 0],
-  app: 'box-static',
-  config: { hx: 5, hy: 0.25, hz: 5, color: 0x448844 }
-})
-```
-
-Alternatively, the entity's own app can create child entities with their own apps, or the entity itself can call `ctx.physics.*` for its own body (the entity the app is attached to).
-
-### ctx.state survives hot reload; timers and bus subscriptions do not
-
-Re-register all timers and bus subscriptions in `setup`. Use `||` to preserve state:
-
-```js
-setup(ctx) {
-  ctx.state.counter = ctx.state.counter || 0  // preserved
-  ctx.bus.on('event', handler)   // re-registered fresh
-  ctx.time.every(1, ticker)      // re-registered fresh
+  if (msg.type === 'player_join') { /* ... */ }
+  if (msg.type === 'player_leave') { /* ... */ }
 }
 ```
 
-### Snapshot field order is fixed and positional
-
-Player arrays and entity arrays use positional indexing. Changing the order or count of fields breaks all clients silently (wrong positions, no error thrown).
-
-### maxSpeed default mismatch
-
-`DEFAULT_MOVEMENT.maxSpeed` in the movement code is 8.0. World config overrides this. The example world config uses 4.0. Always set `movement.maxSpeed` explicitly in world config.
-
-### Horizontal velocity is wish-based, not physics-based
-
-After the physics step, wish velocity overwrites XZ physics result. `player.state.velocity[0]` and `[2]` are the wish velocity. Only `velocity[1]` (Y) comes from physics. This means horizontal movement ignores physics forces.
-
-### CharacterVirtual gravity must be applied manually
-
-The engine manually applies `gravity[1] * dt` to Y velocity. This is already handled. If you override `player.state.velocity[1]`, gravity still accumulates on top next tick.
-
-### Capsule parameter order
-
-`addCapsuleCollider(radius, fullHeight)` - full height, not half height. The API divides by 2 internally. This differs from Jolt's direct API which takes (halfHeight, radius).
-
-### Trimesh colliders are static only
-
-`addTrimeshCollider()` creates a static mesh. No dynamic or kinematic trimesh support.
-
-### Convex hull for dynamic objects
-
-Use `addConvexCollider(points)` or `addConvexFromModel()` for dynamic/kinematic bodies that need shape-accurate physics (vehicles, crates). Convex hulls support all motion types unlike trimesh. `addConvexFromModel()` reads vertices from the entity's GLB at setup time - call it after setting `entity.model`.
-
-### Animation library uses two-phase cache
-
-`preloadAnimationLibrary()` kicks off the `/anim-lib.glb` fetch and caches the promise (`_gltfPromise`). `loadAnimationLibrary(vrmVersion, vrmHumanoid)` awaits that fetch and caches the normalized clip result (`_normalizedCache`). The engine calls `preloadAnimationLibrary()` early during asset init so the GLB is already fetching while the VRM downloads. Subsequent calls to `loadAnimationLibrary()` return the normalized cache immediately. Both functions are idempotent and safe to call concurrently.
-
-### Tick drops under load
-
-TickSystem processes max 4 ticks per loop. If the server falls more than 4 ticks behind (31ms at 128 TPS), those ticks are dropped silently.
-
-### Snapshots not sent with zero players
-
-`if (players.length > 0)` guards snapshot creation. Entity state still updates when no players are connected but nothing is broadcast.
-
-### Collision detection is O(n²)
-
-`_tickCollisions` runs sphere-vs-sphere for all entities with both a collider and an app. Keep interactive entity count under ~50 for this to be cheap.
-
-### AppLoader blocks entire file on pattern match
-
-If any blocked string (including in comments) appears anywhere in the source, the app silently fails to load. No throw, only console error.
-
-### Client apps cannot use import statements
-
-All `import` statements in client app source are stripped by regex before evaluation. Use `engine.THREE`, `engine.scene`, etc. for all dependencies.
-
-### GLB/VRM assets are cached in IndexedDB
-
-On repeat page loads, `fetchCached()` in `client/ModelCache.js` validates cached GLB/VRM ArrayBuffers against the server ETag via a HEAD request. If the ETag matches, the cached bytes are returned without a network fetch. Cache misses or stale entries trigger a full fetch and re-store. Cache failures (quota, unavailable) fall back to normal fetch transparently. This is fully automatic — no app code needed.
-
-### Loading screen hides before shader warmup completes
-
-After the four gate conditions pass, the loading screen hides immediately. `warmupShaders()` then runs asynchronously in the background. The very first rendered frame after the loading screen hides may have a brief GPU stall if shader compilation is not yet complete. This is a deliberate tradeoff to avoid the loading screen adding warmup time on top of actual asset loading.
-
-### setTimeout not cleared on hot reload
-
-`ctx.time.after/every` timers are cleared on teardown. `setTimeout` and `setInterval` are NOT. Use `ctx.time` for game logic. Use `setTimeout` only for external timing (e.g., reload cooldown) and manage cleanup in teardown manually.
-
-### Entity children destroyed with parent
-
-`destroyEntity` recursively destroys all children. Reparent first if you need to preserve a child: `ctx.world.reparent(childId, null)`.
-
-### setPosition teleports through walls
-
-`ctx.players.setPosition` directly sets physics body position with no collision check. The physics solver pushes out on the next tick, which may look jarring.
-
 ---
 
 ## Debug Globals
 
 ```
-Server: globalThis.__DEBUG__.server   (Node REPL)
-Client: window.debug                  (browser console)
-  window.debug.scene, camera, renderer, client, players, input
+Server (Node REPL): globalThis.__DEBUG__.server
+Client (browser):   window.debug  →  scene, camera, renderer, client, players, input
 ```