spoint 0.1.31 → 0.1.33

package/SKILL.md

@@ -762,6 +762,10 @@ App reloads never happen mid-tick. Queue drains at end of each tick. After each
 
 ## Client Rendering
 
+### 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.
+
 ### render(ctx) Return Value
 
 ```js

package/client/app.js

@@ -752,7 +752,10 @@ async function createPlayerVRM(id) {
     }
     if (!_vrmWarmupDone) {
       _vrmWarmupDone = true
-      requestAnimationFrame(() => { renderer.compile(scene, camera); console.log('[shader] vrm warmup compile done') })
+      renderer.compileAsync(scene, camera).then(() => console.log('[shader] vrm warmup compileAsync done')).catch(() => {
+        renderer.compile(scene, camera)
+        console.log('[shader] vrm warmup compile done (fallback)')
+      })
     }
   } catch (e) { console.error('[vrm]', id, e.message) }
   return group
@@ -926,6 +929,7 @@ function loadEntityModel(entityId, entityState) {
     const ep = entityState.position; group.position.set(ep[0], ep[1], ep[2])
     const er = entityState.rotation; if (er) group.quaternion.set(er[0], er[1], er[2], er[3])
     scene.add(group)
+    renderer.compileAsync(group, camera).catch(() => renderer.compile(group, camera))
     entityMeshes.set(entityId, group)
     pendingLoads.delete(entityId)
     if (!environmentLoaded) { environmentLoaded = true; checkAllLoaded() }
@@ -948,6 +952,7 @@ function loadEntityModel(entityId, entityState) {
     })
     model.updateMatrixWorld(true)
     scene.add(model)
+    renderer.compileAsync(model, camera).catch(() => renderer.compile(model, camera))
     entityMeshes.set(entityId, model)
     cam.setEnvironment(colliders)
     scene.remove(ground)
@@ -1073,13 +1078,18 @@ let lastHealth = 100
 let _shaderWarmupDone = false
 let _vrmWarmupDone = false
 
-function warmupShaders() {
+async function warmupShaders() {
   if (_shaderWarmupDone) return
   _shaderWarmupDone = true
   const ext = renderer.extensions.get('KHR_parallel_shader_compile')
   if (ext) console.log('[shader] KHR_parallel_shader_compile active')
-  renderer.compile(scene, camera)
-  console.log('[shader] warmup compile done')
+  try {
+    await renderer.compileAsync(scene, camera)
+    console.log('[shader] warmup compileAsync done')
+  } catch {
+    renderer.compile(scene, camera)
+    console.log('[shader] warmup compile done (fallback)')
+  }
 }
 
 function checkAllLoaded() {
@@ -1089,7 +1099,7 @@ function checkAllLoaded() {
   if (!firstSnapshotReceived) return
   loadingMgr.setStage('INIT')
   loadingMgr.complete()
-  loadingScreen.hide().then(() => requestAnimationFrame(warmupShaders)).catch(() => requestAnimationFrame(warmupShaders))
+  loadingScreen.hide().then(() => warmupShaders()).catch(() => warmupShaders())
   loadingScreenHidden = true
 }
 
@@ -1324,6 +1334,7 @@ function loadQueuedModels() {
         group.position.set(x, y, z)
         group.userData.isDroppedModel = true
         scene.add(group)
+        renderer.compileAsync(group, camera).catch(() => renderer.compile(group, camera))
         const envApp = appModules.get('environment')
         if (envApp?.onEvent) {
           envApp.onEvent({

package/package.json

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