spoint 0.1.47 → 0.1.49

package/SKILL.md

@@ -9,6 +9,227 @@ Complete reference for building apps in a spawnpoint project. Engine source code
 
 ---
 
+## 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`)
+
+```js
+export default {
+  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' }
+  ],
+  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:
+
+```js
+const HALF = 12, WALL_H = 3, WALL_T = 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 },
+]
+
+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.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 }
+        })
+        if (e) ctx.state.ids.push(w.id)
+      }
+    },
+    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 }
+    }
+  }
+}
+```
+
+### 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:
+
+```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.physics.setStatic(true)
+      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 }
+    }
+  }
+}
+```
+
+---
+
+## 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
+
+For remote GLB props that need convex hull physics:
+
+```js
+// apps/prop-static/index.js
+export default {
+  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 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:
@@ -799,7 +1020,13 @@ App reloads never happen mid-tick. Queue drains at end of each tick. After each
 
 ### GLB Shader Stall Prevention
 
-The engine automatically calls `renderer.compileAsync(object, camera)` immediately after adding any GLB or procedural mesh to the scene. This prevents first-draw GPU stall for dynamically loaded entities (environment models, physics crates, power crates, smart objects, drag-and-drop models). No action is needed from app code — warmup is handled in `loadEntityModel` and `loadQueuedModels`. VRM players use a separate one-time warmup path.
+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
 
@@ -815,16 +1042,16 @@ return {
 
 ### Entity custom Field - Procedural Mesh Conventions
 
-When no GLB model is set, `custom` drives procedural geometry:
+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.
 
 ```js
-// Box
-custom: { mesh: 'box', color: 0xff8800, sx: 1, sy: 1, sz: 1 }
+// 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
-custom: { mesh: 'sphere', color: 0x00ff00, radius: 1 }
+// Sphere — r is radius
+custom: { mesh: 'sphere', color: 0x00ff00, r: 1, seg: 16 }
 
-// Cylinder
+// Cylinder — r is radius, h is full height, seg is polygon count
 custom: {
   mesh: 'cylinder',
   r: 0.4, h: 0.1, seg: 16,
@@ -847,6 +1074,10 @@ custom: { ..., glow: true, glowColor: 0x00ff88, glowIntensity: 0.5 }
 custom: { mesh: 'box', label: 'PRESS E' }
 ```
 
+**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.
+
 ---
 
 ## AppLoader Security Restrictions
@@ -1057,6 +1288,29 @@ ctx.bus.on('combat.*', (event) => {
 
 ## 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:
@@ -1097,9 +1351,9 @@ The engine manually applies `gravity[1] * dt` to Y velocity. This is already han
 
 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 is cached globally
+### Animation library uses two-phase cache
 
-`loadAnimationLibrary()` loads `/anim-lib.glb` only once and caches the result. All subsequent calls return the cached result immediately. The library is also pre-fetched in parallel with the VRM download during initialization.
+`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
 
@@ -1121,6 +1375,14 @@ If any blocked string (including in comments) appears anywhere in the source, th
 
 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.

package/apps/arena/index.js

@@ -0,0 +1,83 @@
+const ASSET_BASE = 'https://raw.githubusercontent.com/anEntrypoint/assets/main'
+
+const JUNK_MODELS = [
+  `${ASSET_BASE}/dumpster_b076662a_v1.glb`,
+  `${ASSET_BASE}/garbage_can_6b3d052b_v1.glb`,
+  `${ASSET_BASE}/fire_hydrant_ba0175c1_v1.glb`,
+  `${ASSET_BASE}/crushed_oil_barrel_e450f43f_v1.glb`,
+]
+
+const HALF = 12
+const WALL_H = 3
+const WALL_T = 0.5
+
+const WALLS = [
+  { id: 'arena-wall-n', x: 0,     y: WALL_H / 2, z: -HALF,  hx: HALF,        hy: WALL_H / 2, hz: WALL_T / 2 },
+  { id: 'arena-wall-s', x: 0,     y: WALL_H / 2, z:  HALF,  hx: HALF,        hy: WALL_H / 2, hz: WALL_T / 2 },
+  { id: 'arena-wall-e', x:  HALF, y: WALL_H / 2, z: 0,      hx: WALL_T / 2, hy: WALL_H / 2, hz: HALF },
+  { id: 'arena-wall-w', x: -HALF, y: WALL_H / 2, z: 0,      hx: WALL_T / 2, hy: WALL_H / 2, hz: HALF },
+]
+
+const PROPS = [
+  { model: 0, x: -6, z: -6, rot: 0.5 },
+  { model: 0, x:  7, z:  5, rot: 2.1 },
+  { model: 1, x: -8, z:  3, rot: 1.0 },
+  { model: 1, x:  5, z: -7, rot: 3.2 },
+  { model: 1, x:  3, z:  8, rot: 0.3 },
+  { model: 2, x: -4, z: -9, rot: 1.5 },
+  { model: 2, x:  9, z: -3, rot: 4.0 },
+  { model: 3, x: -7, z:  7, rot: 0.8 },
+  { model: 3, x:  6, z:  2, rot: 2.7 },
+  { model: 3, x: -3, z: -5, rot: 1.2 },
+]
+
+export default {
+  server: {
+    setup(ctx) {
+      ctx.state.ids = ctx.state.ids || []
+      if (ctx.state.ids.length > 0) return
+
+      // Ground (this entity itself)
+      ctx.entity.custom = { mesh: 'box', color: 0x5a7a4a, roughness: 1, sx: HALF * 2, sy: 0.5, sz: HALF * 2 }
+      ctx.physics.setStatic(true)
+      ctx.physics.addBoxCollider([HALF, 0.25, HALF])
+
+      // Walls - each gets box-static app which adds its own collider
+      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, roughness: 0.9 }
+        })
+        if (e) ctx.state.ids.push(w.id)
+      }
+
+      // Props from remote asset repo (static, convex hull from model)
+      for (let i = 0; i < PROPS.length; i++) {
+        const p = PROPS[i]
+        const id = `arena-prop-${i}`
+        const a = p.rot / 2
+        const e = ctx.world.spawn(id, {
+          model: JUNK_MODELS[p.model],
+          position: [p.x, 0, p.z],
+          rotation: [0, Math.sin(a), 0, Math.cos(a)],
+          app: 'prop-static'
+        })
+        if (e) ctx.state.ids.push(id)
+      }
+
+      ctx.debug.log(`[arena] setup: ground + ${WALLS.length} walls + ${PROPS.length} props`)
+    },
+
+    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 }
+    }
+  }
+}

package/apps/box-static/index.js

@@ -0,0 +1,24 @@
+export default {
+  server: {
+    setup(ctx) {
+      const c = ctx.config
+      if (c.color !== undefined) {
+        ctx.entity.custom = {
+          mesh: 'box',
+          color: c.color,
+          roughness: c.roughness ?? 0.9,
+          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])
+    }
+  },
+  client: {
+    render(ctx) {
+      return { position: ctx.entity.position, rotation: ctx.entity.rotation, custom: ctx.entity.custom }
+    }
+  }
+}

package/apps/prop-static/index.js

@@ -0,0 +1,15 @@
+export default {
+  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 }
+    }
+  }
+}

package/apps/world/index.js

@@ -62,6 +62,8 @@ export default {
     { id: 'game', position: [0, 0, 0], app: 'tps-game' },
     { id: 'power-crates', position: [0, 0, 0], app: 'power-crate' },
     { id: 'interact-box', position: [-100, 3, -100], app: 'interactable' }
+    // To use the primitive arena instead of schwust.glb, replace above with:
+    // { id: 'arena', position: [0, 0, 0], app: 'arena' }
   ],
   playerModel: './apps/tps-game/cleetus.vrm',
   spawnPoint: [-35, 3, -65]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spoint",
-  "version": "0.1.47",
+  "version": "0.1.49",
   "description": "Physics and netcode SDK for multiplayer game servers",
   "type": "module",
   "main": "src/index.js",