spoint 0.1.46 → 0.1.48

package/SKILL.md

@@ -219,6 +219,27 @@ Read-only. Set in the world entities array under `config: {}`.
 ctx.config.radius  // 5
 ```
 
+### 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`.
+
+```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!' })
+}
+```
+
+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
@@ -778,7 +799,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
 
@@ -909,21 +936,16 @@ onMessage(ctx, msg) {
 
 ### Interact detection with cooldown
 
+Use `ctx.interactable()` — the engine handles proximity, prompt UI, and cooldown automatically.
+
 ```js
 setup(ctx) {
-  ctx.state.cooldowns = new Map()
-  ctx.time.every(0.1, () => {
-    const player = ctx.players.getNearest(ctx.entity.position, 4)
-    if (!player?.state?.interact) return
-    const now = Date.now()
-    if (now - (ctx.state.cooldowns.get(player.id) || 0) < 500) return
-    ctx.state.cooldowns.set(player.id, now)
-    ctx.players.send(player.id, { type: 'interact_response', message: 'Hello!' })
-    ctx.network.broadcast({ type: 'interact_effect', position: ctx.entity.position })
-  })
+  ctx.interactable({ prompt: 'Press E', radius: 4, cooldown: 500 })
 },
-teardown(ctx) {
-  ctx.state.cooldowns?.clear()
+
+onInteract(ctx, player) {
+  ctx.players.send(player.id, { type: 'interact_response', message: 'Hello!' })
+  ctx.network.broadcast({ type: 'interact_effect', position: ctx.entity.position })
 }
 ```
 
@@ -977,19 +999,14 @@ update(ctx, dt) {
 }
 ```
 
-### Client UI with proximity check
+### 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: {
-  onFrame(dt, engine) {
-    const ent = engine.client?.state?.entities?.find(e => e.app === 'my-app')
-    const local = engine.client?.state?.players?.find(p => p.id === engine.playerId)
-    if (!ent?.position || !local?.position) { this._canInteract = false; return }
-    const dist = Math.hypot(
-      ent.position[0] - local.position[0],
-      ent.position[2] - local.position[2]
-    )
-    this._canInteract = dist < 4
+  onEvent(payload) {
+    if (payload.type === 'interact_response') { this._msg = payload.message; this._expire = Date.now() + 3000 }
   },
 
   render(ctx) {
@@ -998,8 +1015,8 @@ client: {
     return {
       position: ctx.entity.position,
       custom: ctx.entity.custom,
-      ui: this._canInteract
-        ? h('div', { style: 'position:fixed;bottom:40%;left:50%;transform:translateX(-50%);color:#fff;background:rgba(0,0,0,0.7);padding:8px 16px;border-radius:8px' }, 'Press E to interact')
+      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
     }
   }
@@ -1086,9 +1103,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
 
@@ -1110,6 +1127,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/interactable/index.js

@@ -3,10 +3,9 @@ export default {
     setup(ctx) {
       ctx.entity.custom = { mesh: 'box', color: 0x00ff88, sx: 1.5, sy: 0.5, sz: 1.5, label: 'INTERACT' }
       ctx.state.interactionCount = 0
-
       ctx.physics.setStatic(true)
       ctx.physics.addBoxCollider([0.75, 0.25, 0.75])
-      ctx.physics.setInteractable(3.5)
+      ctx.interactable({ prompt: 'Press E to interact', radius: 3.5, cooldown: 500 })
     },
 
     onInteract(ctx, player) {
@@ -25,33 +24,7 @@ export default {
   },
 
   client: {
-    setup(engine) {
-      this._lastMessage = null
-      this._messageExpire = 0
-      this._canInteract = false
-      this._wasRegistered = false
-    },
-
-    onFrame(dt, engine) {
-      const ent = engine.client?.state?.entities?.find(e => e.app === 'interactable')
-      const pos = ent?.position
-      const local = engine.client?.state?.players?.find(p => p.id === engine.playerId)
-      if (!pos || !local?.position) {
-        if (this._wasRegistered) { engine.mobileControls?.unregisterInteractable(this._wasRegistered); this._wasRegistered = false }
-        return
-      }
-      const dx = pos[0]-local.position[0], dy = pos[1]-local.position[1], dz = pos[2]-local.position[2]
-      const canInteract = dx*dx+dy*dy+dz*dz < 3.5*3.5
-      if (canInteract && !this._wasRegistered) { engine.mobileControls?.registerInteractable(ent.id, 'INTERACT'); this._wasRegistered = ent.id }
-      else if (!canInteract && this._wasRegistered) { engine.mobileControls?.unregisterInteractable(this._wasRegistered); this._wasRegistered = false }
-      this._canInteract = canInteract
-    },
-
-    teardown(engine) {
-      if (this._wasRegistered) { engine.mobileControls?.unregisterInteractable(this._wasRegistered); this._wasRegistered = false }
-    },
-
-    onEvent(payload, engine) {
+    onEvent(payload) {
       if (payload.type === 'interact_response') { this._lastMessage = payload.message; this._messageExpire = Date.now() + 3000 }
       if (payload.type === 'interact_effect') { this._lastMessage = 'Someone interacted!'; this._messageExpire = Date.now() + 1500 }
     },
@@ -65,9 +38,7 @@ export default {
         const opacity = Math.min(1, ((this._messageExpire - Date.now()) / 3000) * 2)
         ui.push(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;font-size:20px;text-align:center;border:2px solid #0f0;opacity:${opacity}` }, this._lastMessage))
       }
-      const custom = { ...ctx.entity.custom }
-      if (this._canInteract) { custom.glow = true; custom.glowColor = 0x00ff88; custom.glowIntensity = 0.5 }
-      return { position: pos, rotation: ctx.entity.rotation, custom, ui: ui.length > 0 ? h('div', null, ...ui) : null }
+      return { position: pos, rotation: ctx.entity.rotation, custom: ctx.entity.custom, ui: ui.length > 0 ? h('div', null, ...ui) : null }
     }
   }
 }

package/client/app.js

@@ -999,13 +999,32 @@ function renderAppUI(state) {
       if (result?.ui) uiFragments.push({ id: entity.id, ui: result.ui })
     } catch (e) { console.error('[ui]', entity.id, e.message) }
   }
-const hudVdom = createElement('div', { id: 'hud' },
+  const interactPrompt = _buildInteractPrompt(state)
+  const hudVdom = createElement('div', { id: 'hud' },
     createElement('div', { id: 'info' }, `FPS: ${fpsDisplay} | Players: ${state.players.length} | Tick: ${client.currentTick} | RTT: ${Math.round(client.getRTT())}ms | Buf: ${client.getBufferHealth()}`),
-    ...uiFragments.map(f => createElement('div', { 'data-app': f.id }, f.ui))
+    ...uiFragments.map(f => createElement('div', { 'data-app': f.id }, f.ui)),
+    interactPrompt
   )
   try { applyDiff(uiRoot, hudVdom) } catch (e) { console.error('[ui] diff:', e.message) }
 }
 
+function _buildInteractPrompt(state) {
+  const local = state.players.find(p => p.id === client.playerId)
+  if (!local?.position) return null
+  const lx = local.position[0], ly = local.position[1], lz = local.position[2]
+  for (const entity of state.entities) {
+    const cfg = entity.custom?._interactable
+    if (!cfg || !entity.position) continue
+    const dx = entity.position[0] - lx, dy = entity.position[1] - ly, dz = entity.position[2] - lz
+    if (dx * dx + dy * dy + dz * dz < cfg.radius * cfg.radius) {
+      return createElement('div', {
+        style: 'position:fixed;bottom:40%;left:50%;transform:translateX(-50%);color:#fff;background:rgba(0,0,0,0.7);padding:8px 16px;border-radius:8px;pointer-events:none'
+      }, cfg.prompt)
+    }
+  }
+  return null
+}
+
 const client = new PhysicsNetworkClient({
   url: `${window.location.protocol === 'https:' ? 'wss:' : 'ws:'}//${window.location.host}/ws`,
   predictionEnabled: true,

package/package.json

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

package/src/apps/AppContext.js

@@ -173,6 +173,18 @@ export class AppContext {
 
   get debug() { return this._debugger }
 
+  interactable(config = {}) {
+    const ent = this._entity
+    const radius = config.radius ?? 3
+    const prompt = config.prompt ?? 'Press E'
+    const cooldown = config.cooldown ?? 500
+    ent._interactable = true
+    ent._interactRadius = radius
+    ent._interactCooldown = cooldown
+    if (!ent.custom) ent.custom = {}
+    ent.custom._interactable = { prompt, radius }
+  }
+
   get collider() {
     const ent = this._entity
     return {

package/src/apps/AppRuntime.js

@@ -194,7 +194,8 @@ export class AppRuntime {
         if (dx*dx+dy*dy+dz*dz > e._interactRadius**2) continue
         const key = `${e.id}:${p.id}`
         const last = this._interactCooldowns.get(key) || 0
-        if (p.lastInput?.interact && now - last > 500) {
+        const cooldown = e._interactCooldown ?? 500
+        if (p.lastInput?.interact && now - last > cooldown) {
           this._interactCooldowns.set(key, now)
           this.fireEvent(e.id, 'onInteract', p)
           const bus = this._eventBus.scope ? this._eventBus : null

package/src/client/InputHandler.js

@@ -142,6 +142,7 @@ export class InputHandler {
       crouch: this.keys.get('c') || this.keys.get('control') || false,
       shoot: this.mouseDown,
       reload: this.keys.get('r') || false,
+      interact: this.keys.get('e') || false,
       editToggle: this.editModeCooldown,
       mouseX: this.mouseX,
       mouseY: this.mouseY