spoint 0.1.45 → 0.1.47

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
@@ -909,21 +930,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 +993,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 +1009,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
     }
   }

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/LoadingManager.js

@@ -1,3 +1,5 @@
+import { fetchCached } from './ModelCache.js'
+
 export class LoadingManager extends EventTarget {
   static STAGES = {
     CONNECTING: { name: 'CONNECTING', label: 'Connecting...', range: [0, 10] },
@@ -76,32 +78,7 @@ export class LoadingManager extends EventTarget {
 
   async fetchWithProgress(url) {
     try {
-      const response = await fetch(url)
-      if (!response.ok) throw new Error(`HTTP ${response.status}`)
-      const contentLength = parseInt(response.headers.get('content-length') || '0', 10)
-      const isGzip = (response.headers.get('content-encoding') || '').includes('gzip')
-      const useTotal = contentLength > 0 && !isGzip
-      const reader = response.body.getReader()
-      const chunks = []
-      let receivedLength = 0
-
-      while (true) {
-        const { done, value } = await reader.read()
-        if (done) break
-        chunks.push(value)
-        receivedLength += value.length
-        if (useTotal) {
-          this.updateProgress(receivedLength, contentLength)
-        }
-      }
-
-      const result = new Uint8Array(receivedLength)
-      let position = 0
-      for (const chunk of chunks) {
-        result.set(chunk, position)
-        position += chunk.length
-      }
-      return result
+      return await fetchCached(url, (received, total) => this.updateProgress(received, total))
     } catch (error) {
       console.error('[loading] fetch failed:', url, error)
       throw error

package/client/ModelCache.js

@@ -0,0 +1,76 @@
+const DB_NAME = 'spawnpoint-model-cache'
+const DB_VERSION = 1
+const STORE = 'models'
+
+let _db = null
+
+async function openDB() {
+  if (_db) return _db
+  return new Promise((resolve, reject) => {
+    const req = indexedDB.open(DB_NAME, DB_VERSION)
+    req.onupgradeneeded = e => e.target.result.createObjectStore(STORE)
+    req.onsuccess = e => { _db = e.target.result; resolve(_db) }
+    req.onerror = () => reject(req.error)
+  })
+}
+
+async function dbGet(key) {
+  const db = await openDB()
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(STORE, 'readonly')
+    const req = tx.objectStore(STORE).get(key)
+    req.onsuccess = () => resolve(req.result)
+    req.onerror = () => reject(req.error)
+  })
+}
+
+async function dbPut(key, value) {
+  const db = await openDB()
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(STORE, 'readwrite')
+    const req = tx.objectStore(STORE).put(value, key)
+    req.onsuccess = () => resolve()
+    req.onerror = () => reject(req.error)
+  })
+}
+
+export async function fetchCached(url, onProgress) {
+  let cached = null
+  try { cached = await dbGet(url) } catch {}
+
+  if (cached?.etag) {
+    const head = await fetch(url, { method: 'HEAD' }).catch(() => null)
+    const serverEtag = head?.headers?.get('etag')
+    if (serverEtag && serverEtag === cached.etag) {
+      return new Uint8Array(cached.buffer)
+    }
+  }
+
+  const response = await fetch(url)
+  if (!response.ok) throw new Error(`HTTP ${response.status}`)
+  const etag = response.headers.get('etag') || ''
+  const contentLength = parseInt(response.headers.get('content-length') || '0', 10)
+  const isGzip = (response.headers.get('content-encoding') || '').includes('gzip')
+  const useTotal = contentLength > 0 && !isGzip
+  const reader = response.body.getReader()
+  const chunks = []
+  let received = 0
+
+  while (true) {
+    const { done, value } = await reader.read()
+    if (done) break
+    chunks.push(value)
+    received += value.length
+    if (useTotal && onProgress) onProgress(received, contentLength)
+  }
+
+  const result = new Uint8Array(received)
+  let pos = 0
+  for (const chunk of chunks) { result.set(chunk, pos); pos += chunk.length }
+
+  if (etag) {
+    try { await dbPut(url, { etag, buffer: result.buffer }) } catch {}
+  }
+
+  return result
+}

package/client/app.js

@@ -15,6 +15,7 @@ import { VRButton } from 'three/addons/webxr/VRButton.js'
 import { XRControllerModelFactory } from 'three/addons/webxr/XRControllerModelFactory.js'
 import { XRHandModelFactory } from 'three/addons/webxr/XRHandModelFactory.js'
 import { LoadingManager } from './LoadingManager.js'
+import { fetchCached } from './ModelCache.js'
 import { createLoadingScreen } from './createLoadingScreen.js'
 import { MobileControls, detectDevice } from './MobileControls.js'
 import { ARControls, createARButton } from './ARControls.js'
@@ -956,7 +957,7 @@ function loadEntityModel(entityId, entityState) {
   }
   loadingMgr.setStage('RESOURCES')
   const url = entityState.model.startsWith('./') ? '/' + entityState.model.slice(2) : entityState.model
-  gltfLoader.load(url, (gltf) => {
+  const onGltfLoad = (gltf) => {
     const model = gltf.scene
     const mp = entityState.position; model.position.set(mp[0], mp[1], mp[2])
     const mr = entityState.rotation; if (mr) model.quaternion.set(mr[0], mr[1], mr[2], mr[3])
@@ -979,7 +980,11 @@ function loadEntityModel(entityId, entityState) {
     if (!environmentLoaded) { environmentLoaded = true; checkAllLoaded() }
     if (firstSnapshotEntityPending.has(entityId)) { firstSnapshotEntityPending.delete(entityId); if (firstSnapshotEntityPending.size === 0) checkAllLoaded() }
     if (loadingScreenHidden) renderer.compileAsync(scene, camera).catch(() => renderer.compile(scene, camera))
-  }, (progress) => { if (progress.total > 0) console.log('[gltf]', url, Math.round(Math.min(progress.loaded, progress.total) / progress.total * 100) + '%') }, (err) => { console.error('[gltf]', url, err); pendingLoads.delete(entityId); if (firstSnapshotEntityPending.has(entityId)) { firstSnapshotEntityPending.delete(entityId); if (firstSnapshotEntityPending.size === 0) checkAllLoaded() } })
+  }
+  const onGltfErr = (err) => { console.error('[gltf]', url, err); pendingLoads.delete(entityId); if (firstSnapshotEntityPending.has(entityId)) { firstSnapshotEntityPending.delete(entityId); if (firstSnapshotEntityPending.size === 0) checkAllLoaded() } }
+  fetchCached(url).then(buf => {
+    gltfLoader.parse(buf.buffer.slice(0), '', onGltfLoad, onGltfErr)
+  }).catch(onGltfErr)
 }
 
 function renderAppUI(state) {
@@ -994,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.45",
+  "version": "0.1.47",
   "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

package/src/sdk/StaticHandler.js

@@ -45,9 +45,18 @@ export function createStaticHandler(dirs) {
         } else if (ext === '.glb' || ext === '.vrm' || ext === '.gltf') {
           headers['Cache-Control'] = 'public, max-age=86400, immutable'
         }
-        const { content, gzipped } = getCached(fp, ext)
+        const { content, gzipped, mtime } = getCached(fp, ext)
         if (gzipped) headers['Content-Encoding'] = 'gzip'
         headers['Content-Length'] = content.length
+        if (ext === '.glb' || ext === '.vrm' || ext === '.gltf') {
+          headers['ETag'] = `"${mtime.toString(16)}"`
+          const ifNoneMatch = req.headers['if-none-match']
+          if (ifNoneMatch === headers['ETag']) {
+            res.writeHead(304, { 'ETag': headers['ETag'], 'Cache-Control': headers['Cache-Control'] })
+            res.end()
+            return
+          }
+        }
         res.writeHead(200, headers)
         res.end(content)
         return