spoint 0.1.603 → 0.1.604

package/client/app.js

@@ -43,6 +43,7 @@ import { createTerrainBackdrop } from './core/TerrainBackdrop.js'
 import { createSculptOverlay } from './core/SculptOverlay.js'
 import { createVegetation } from './core/Vegetation.js'
 import { createRocks } from './core/Rocks.js'
+import { createCaveMeshes } from './core/CaveMeshes.js'
 import { createSceneOcclusion } from './core/SceneOcclusion.js'
 import { createOcclusionQueryBudget } from './core/OcclusionQueryBudget.js'
 import { createGrass } from './core/Grass.js'
@@ -502,6 +503,16 @@ function _ensureRocks(tb) {
     .then(r => { rocks = r; if (window.__app) window.__app.rocks = r; sceneOcclusion.register('rocks', r) })
     .catch(e => console.error('[rocks] init failed:', e?.message || e))
 }
+function _ensureCaves(tb) {
+  if (caveMeshes || !tb || !_terrainCfg) return null
+  const caveCfg = _terrainCfg.caveCarve
+  if (!Array.isArray(caveCfg) || caveCfg.length === 0) return null
+  try {
+    caveMeshes = createCaveMeshes({ scene, cfg: caveCfg })
+    if (window.__app) window.__app.caveMeshes = caveMeshes
+  } catch (e) { console.error('[caves] init failed:', e?.message || e) }
+  return null
+}
 function _ensureGrass(tb) {
   if (grass || !tb || !_terrainCfg) return null
   const vcfg = _terrainCfg.vegetation || {}
@@ -580,6 +591,7 @@ async function _buildWorldScenery() {
     const rp = _ensureRocks(tb); if (rp) { await rp; _hp('after-rocks') }
     const gp = _ensureGrass(tb); if (gp) { await gp; _hp('after-grass') }
     const vp = _ensureVegetation(tb); if (vp) { await vp; _hp('after-veg') }
+    _ensureCaves(tb); _hp('after-caves')
     _ensureWeather(tb); _hp('after-weather')
   } else {
     _dbgTerrain('planet backdrop unavailable (init failed) -> skipping vegetation/rocks/grass to avoid a broken-shader GPU leak')
@@ -666,7 +678,7 @@ const clickPrompt = document.getElementById('click-prompt')
 if (deviceInfo.isMobile && clickPrompt) clickPrompt.style.display = 'none'
 const _pids = new Set(), _eids = new Set()
 let worldConfig={}, vrmBuffer=null, animAssets=null, assetsLoaded=false, firstSnapshotReceived=false, _fitShadowTimer=null
-let terrainBackdrop=null, _terrainCfg=null, vegetation=null, rocks=null, grass=null, colliderDebug=null, weather=null, sculptOverlay=null
+let terrainBackdrop=null, _terrainCfg=null, vegetation=null, rocks=null, grass=null, colliderDebug=null, weather=null, sculptOverlay=null, caveMeshes=null
 // Late-join GPU-visible sculpt backfill (terrain-sculpt-late-join-gpu-resync): MSG.TERRAIN_SCULPT_SYNC
 // can (and on a real connection reliably does -- terrain scenery build is async, WORLD_DEF/SNAPSHOT/this
 // sync all arrive near-instantly on the same connection) reach the client BEFORE _buildWorldScenery has
@@ -1008,7 +1020,8 @@ const engineCtx = {
       try { rocks && rocks.dispose && rocks.dispose() } catch (e) { _dbgTerrain('rocks dispose failed on reseed:', e?.message || e) }
       sceneOcclusion.unregister('vegetation'); sceneOcclusion.unregister('rocks'); sceneOcclusion.unregister('grass')
       try { grass && grass.dispose && grass.dispose() } catch (e) { _dbgTerrain('grass dispose failed on reseed:', e?.message || e) }
-      vegetation = null; rocks = null; grass = null
+      try { caveMeshes && caveMeshes.dispose && caveMeshes.dispose() } catch (e) { _dbgTerrain('caveMeshes dispose failed on reseed:', e?.message || e) }
+      vegetation = null; rocks = null; grass = null; caveMeshes = null
       // Weather itself isn't seed-derived (camera-relative, no placement hash), but it holds the OLD
       // terrain frame closed over for ground-height sampling -- a stale frame after reseed would sample
       // splash contact against the pre-reseed terrain. Dispose + let _ensureWeather below rebuild
@@ -1024,7 +1037,7 @@ const engineCtx = {
         try { const f = tb.frame; if (f) setSeaLevelY((f.offsetY || 0) - (f.anchorHeight || 0), scene) } catch (_) {}
         if (seedChanged && tb && window.__terrain) {
           const rp = _ensureRocks(tb); const gp = _ensureGrass(tb); const vp = _ensureVegetation(tb)
-          _ensureWeather(tb)
+          _ensureCaves(tb); _ensureWeather(tb)
           return Promise.all([rp, gp, vp].filter(Boolean)).catch(e => console.error('[terrain] reseed veg/rock/grass rebuild failed:', e?.message || e))
         }
       })

package/client/core/CaveMeshes.js

@@ -0,0 +1,42 @@
+import * as THREE from 'three'
+import { polygonizeCaveVolume, loadCaveCarveLayer } from '/src/terrain/CaveSDF.js'
+
+function buildVolumeMesh(vol, res, material) {
+  const mesh = polygonizeCaveVolume(vol, res)
+  if (mesh.vc === 0) return null
+  const g = new THREE.BufferGeometry()
+  g.setAttribute('position', new THREE.BufferAttribute(mesh.positions.slice(), 3))
+  g.setIndex(new THREE.BufferAttribute(mesh.indices.slice(0, mesh.ic), 1))
+  g.computeVertexNormals()
+  g.computeBoundingBox()
+  g.computeBoundingSphere()
+  const obj = new THREE.Mesh(g, material)
+  obj.matrixAutoUpdate = false
+  obj.updateMatrix()
+  return obj
+}
+
+export function createCaveMeshes({ scene, cfg, res = 24 }) {
+  const group = new THREE.Group()
+  group.name = 'cave-meshes'
+  const material = new THREE.MeshStandardMaterial({ color: 0x2a2a2c, roughness: 0.95, metalness: 0.0, side: THREE.BackSide })
+  const objects = []
+  const volumesSpec = Array.isArray(cfg) ? cfg : []
+  const layer = loadCaveCarveLayer({ version: 2, volumes: volumesSpec })
+  for (const vol of layer.volumes) {
+    const obj = buildVolumeMesh(vol, res, material)
+    if (obj) { group.add(obj); objects.push(obj) }
+  }
+  if (scene) scene.add(group)
+
+  function dispose() {
+    for (const obj of objects) { obj.geometry.dispose(); scene && scene.remove(obj) }
+    objects.length = 0
+    scene && scene.remove(group)
+    material.dispose()
+  }
+
+  const api = { group, objects, dispose, get volumeCount() { return objects.length } }
+  if (typeof window !== 'undefined') window.__caveMeshes = api
+  return api
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spoint",
-  "version": "0.1.603",
+  "version": "0.1.604",
   "description": "Physics and netcode SDK for multiplayer game servers",
   "type": "module",
   "workspaces": [

package/src/sdk/RoomOrchestrator.js

@@ -65,7 +65,7 @@ export class RoomOrchestrator {
    * @param {number} [opts.maxRestarts] - max restarts per worker within restartWindowMs; default 3
    * @param {number} [opts.restartWindowMs] - sliding window for crash rate limiting; default 60000
    */
-  constructor({ sdkRoot, projectRoot, workerCount = 2, portRange = [19000, 19999], elasticScaling = false, elasticScaleUpThreshold = 0.8, elasticScaleDownCooldownMs = 120000, elasticScaleCheckIntervalMs = 30000, workerHosts = {}, restartOnCrash = true, maxRestarts = 3, restartWindowMs = 60000 } = {}) {
+  constructor({ sdkRoot, projectRoot, workerCount = 2, portRange = [19000, 19999], elasticScaling = false, elasticScaleUpThreshold = 0.8, elasticScaleDownCooldownMs = 120000, elasticScaleCheckIntervalMs = 30000, workerHosts = {}, restartOnCrash = true, maxRestarts = 3, restartWindowMs = 60000, externalWorkerHeartbeatIntervalMs = 10000 } = {}) {
     if (!sdkRoot) throw new Error('RoomOrchestrator requires { sdkRoot }')
     this.sdkRoot = sdkRoot
     this.projectRoot = projectRoot || sdkRoot
@@ -97,6 +97,8 @@ export class RoomOrchestrator {
     this._emptiedAt = new Map() // workerIndex -> timestamp when it last became empty (for scale-down cooldown)
     this._retiring = new Set() // workerIndexes currently draining (reject new room placement, retiring handled by _onWorkerRetired once empty)
     this._elasticStats = { spawns: 0, retires: 0, lastCheck: 0, lastDecision: '' }
+    this._externalWorkerHeartbeatIntervalMs = externalWorkerHeartbeatIntervalMs
+    this._externalHeartbeatTimer = null
   }
 
   // Non-overlapping sub-range per worker so N independent RoomDirectory instances (each with zero
@@ -268,6 +270,25 @@ export class RoomOrchestrator {
     if (this._elasticTimer) { clearInterval(this._elasticTimer); this._elasticTimer = null }
   }
 
+  startExternalWorkerHeartbeat() {
+    if (this._externalHeartbeatTimer) return
+    this._externalHeartbeatTimer = setInterval(() => this._externalHeartbeatCheck(), this._externalWorkerHeartbeatIntervalMs)
+    this._externalHeartbeatTimer.unref?.()
+  }
+
+  stopExternalWorkerHeartbeat() {
+    if (this._externalHeartbeatTimer) { clearInterval(this._externalHeartbeatTimer); this._externalHeartbeatTimer = null }
+  }
+
+  async _externalHeartbeatCheck() {
+    const checks = []
+    for (let i = 0; i < this.workers.length; i++) {
+      const entry = this.workers[i]
+      if (entry && entry.ready && entry.isExternal) checks.push(this._sendExternal(entry, { type: 'GET_STATUS' }).catch(() => null))
+    }
+    await Promise.all(checks)
+  }
+
   async _elasticCheck() {
     const now = Date.now()
     this._elasticStats.lastCheck = now

package/src/terrain/CaveSDF.js

@@ -1,5 +1,14 @@
 import { marchRockSurface } from './RockShapes.js'
 
+function tunnelHash(seed, i) {
+  let h = seed | 0
+  h = Math.imul(h ^ (i | 0), 0x27d4eb2d) >>> 0
+  h ^= h >>> 15; h = Math.imul(h, 0x2c1b3c6d) >>> 0
+  h ^= h >>> 12; h = Math.imul(h, 0x297a2d39) >>> 0
+  h ^= h >>> 15
+  return (h >>> 0) / 4294967296
+}
+
 export function makeSphereCaveSDF(cx, cy, cz, radius) {
   return (x, y, z) => {
     const dx = x - cx, dy = y - cy, dz = z - cz
@@ -7,23 +16,65 @@ export function makeSphereCaveSDF(cx, cy, cz, radius) {
   }
 }
 
+export function makeCylinderCaveSDF(cx, cy, cz, radius, halfHeight, axis = 'y') {
+  return (x, y, z) => {
+    const dx = x - cx, dy = y - cy, dz = z - cz
+    let radial, along, halfSpan
+    if (axis === 'x') { radial = Math.hypot(dy, dz); along = dx; halfSpan = halfHeight }
+    else if (axis === 'z') { radial = Math.hypot(dx, dy); along = dz; halfSpan = halfHeight }
+    else { radial = Math.hypot(dx, dz); along = dy; halfSpan = halfHeight }
+    const dRadial = radial - radius
+    const dAlong = Math.abs(along) - halfSpan
+    const outsideX = Math.max(dRadial, 0), outsideY = Math.max(dAlong, 0)
+    const outsideDist = Math.hypot(outsideX, outsideY)
+    const insideDist = Math.min(Math.max(dRadial, dAlong), 0)
+    return outsideDist + insideDist
+  }
+}
+
+export function makeTunnelCaveSDF(seed, radius, length, axis = 'y', warpAmp = 0.15, warpFreq = 2.5) {
+  return (x, y, z) => {
+    let along, u, v
+    if (axis === 'x') { along = x; u = y; v = z }
+    else if (axis === 'z') { along = z; u = x; v = y }
+    else { along = y; u = x; v = z }
+    const t = Math.max(-1, Math.min(1, along / (length * 0.5)))
+    const sampleIdx = Math.round((t + 1) * 0.5 * 1000)
+    const warpU = (tunnelHash(seed, sampleIdx * 2) * 2 - 1) * warpAmp * Math.sin(t * Math.PI * warpFreq + tunnelHash(seed, 1) * 6.28318)
+    const warpV = (tunnelHash(seed, sampleIdx * 2 + 1) * 2 - 1) * warpAmp * Math.cos(t * Math.PI * warpFreq + tunnelHash(seed, 2) * 6.28318)
+    const du = u - warpU, dv = v - warpV
+    const dRadial = Math.hypot(du, dv) - radius
+    const dAlong = Math.abs(along) - length * 0.5
+    const outsideX = Math.max(dRadial, 0), outsideY = Math.max(dAlong, 0)
+    const outsideDist = Math.hypot(outsideX, outsideY)
+    const insideDist = Math.min(Math.max(dRadial, dAlong), 0)
+    return outsideDist + insideDist
+  }
+}
+
 export function polygonizeCaveSDF(sdf, res = 24) {
   return marchRockSurface(res, sdf)
 }
 
-export function createCaveVolume(worldX, worldY, worldZ, worldRadius) {
-  const sdf = makeSphereCaveSDF(0, 0, 0, 1)
+function localSDFFor(shape) {
+  if (shape.kind === 'cylinder') return makeCylinderCaveSDF(0, 0, 0, 1, shape.halfHeight ?? 1, shape.axis ?? 'y')
+  if (shape.kind === 'tunnel') return makeTunnelCaveSDF(shape.seed ?? 0, 1, shape.length ?? 2, shape.axis ?? 'y', shape.warpAmp ?? 0.15, shape.warpFreq ?? 2.5)
+  return makeSphereCaveSDF(0, 0, 0, 1)
+}
+
+export function createCaveVolume(worldX, worldY, worldZ, worldRadius, shape = { kind: 'sphere' }) {
+  const sdf = localSDFFor(shape)
   const localToWorld = (lx, ly, lz) => [worldX + lx * worldRadius, worldY + ly * worldRadius, worldZ + lz * worldRadius]
   const worldToLocal = (wx, wy, wz) => [(wx - worldX) / worldRadius, (wy - worldY) / worldRadius, (wz - worldZ) / worldRadius]
   const worldSDF = (wx, wy, wz) => {
     const [lx, ly, lz] = worldToLocal(wx, wy, wz)
     return sdf(lx, ly, lz) * worldRadius
   }
-  return { sdf: worldSDF, localToWorld, worldToLocal, worldX, worldY, worldZ, worldRadius }
+  return { sdf: worldSDF, localSDF: sdf, localToWorld, worldToLocal, worldX, worldY, worldZ, worldRadius, shape }
 }
 
 export function polygonizeCaveVolume(caveVolume, res = 24) {
-  const local = polygonizeCaveSDF((lx, ly, lz) => makeSphereCaveSDF(0, 0, 0, 1)(lx, ly, lz), res)
+  const local = polygonizeCaveSDF(caveVolume.localSDF, res)
   const positions = new Float32Array(local.positions.length)
   for (let v = 0; v < local.vc; v++) {
     const [wx, wy, wz] = caveVolume.localToWorld(local.positions[v * 3], local.positions[v * 3 + 1], local.positions[v * 3 + 2])
@@ -34,13 +85,37 @@ export function polygonizeCaveVolume(caveVolume, res = 24) {
   return { positions: positions.subarray(0, local.vc * 3), vc: local.vc, indices: local.indices, ic: local.ic }
 }
 
+function volumeVerticalSpan(vol, horizontalDist) {
+  if (vol.shape.kind === 'cylinder' || vol.shape.kind === 'tunnel') {
+    if (horizontalDist > vol.worldRadius) return 0
+    return vol.worldRadius * (vol.shape.halfHeight ?? 1)
+  }
+  return Math.sqrt(Math.max(0, vol.worldRadius * vol.worldRadius - horizontalDist * horizontalDist))
+}
+
 export function createCaveCarveLayer() {
   const volumes = []
 
   function addSphereCave(worldX, worldY, worldZ, worldRadius) {
     if (!Number.isFinite(worldX) || !Number.isFinite(worldY) || !Number.isFinite(worldZ)) return { added: false }
     if (!Number.isFinite(worldRadius) || worldRadius <= 0) return { added: false }
-    volumes.push(createCaveVolume(worldX, worldY, worldZ, worldRadius))
+    volumes.push(createCaveVolume(worldX, worldY, worldZ, worldRadius, { kind: 'sphere' }))
+    return { added: true, count: volumes.length }
+  }
+
+  function addCylinderCave(worldX, worldY, worldZ, worldRadius, halfHeight, axis = 'y') {
+    if (!Number.isFinite(worldX) || !Number.isFinite(worldY) || !Number.isFinite(worldZ)) return { added: false }
+    if (!Number.isFinite(worldRadius) || worldRadius <= 0) return { added: false }
+    if (!Number.isFinite(halfHeight) || halfHeight <= 0) return { added: false }
+    volumes.push(createCaveVolume(worldX, worldY, worldZ, worldRadius, { kind: 'cylinder', halfHeight, axis }))
+    return { added: true, count: volumes.length }
+  }
+
+  function addTunnelCave(worldX, worldY, worldZ, worldRadius, length, axis = 'y', seed = 0, warpAmp = 0.15, warpFreq = 2.5) {
+    if (!Number.isFinite(worldX) || !Number.isFinite(worldY) || !Number.isFinite(worldZ)) return { added: false }
+    if (!Number.isFinite(worldRadius) || worldRadius <= 0) return { added: false }
+    if (!Number.isFinite(length) || length <= 0) return { added: false }
+    volumes.push(createCaveVolume(worldX, worldY, worldZ, worldRadius, { kind: 'tunnel', length: length / worldRadius, axis, seed, warpAmp, warpFreq }))
     return { added: true, count: volumes.length }
   }
 
@@ -51,7 +126,8 @@ export function createCaveCarveLayer() {
       const dx = x - vol.worldX, dz = z - vol.worldZ
       const horizontalDist = Math.hypot(dx, dz)
       if (horizontalDist > vol.worldRadius) continue
-      const verticalSpan = Math.sqrt(Math.max(0, vol.worldRadius * vol.worldRadius - horizontalDist * horizontalDist))
+      const verticalSpan = volumeVerticalSpan(vol, horizontalDist)
+      if (verticalSpan <= 0) continue
       const caveTop = vol.worldY + verticalSpan
       if (caveTop < surfaceY) continue
       delta -= (caveTop - surfaceY) + verticalSpan
@@ -69,13 +145,22 @@ export function createCaveCarveLayer() {
   }
 
   function toJSON() {
-    return { version: 1, volumes: volumes.map(v => ({ worldX: v.worldX, worldY: v.worldY, worldZ: v.worldZ, worldRadius: v.worldRadius })) }
+    return {
+      version: 2,
+      volumes: volumes.map(v => ({
+        worldX: v.worldX, worldY: v.worldY, worldZ: v.worldZ, worldRadius: v.worldRadius,
+        kind: v.shape.kind, halfHeight: v.shape.halfHeight, axis: v.shape.axis,
+        length: v.shape.length != null ? v.shape.length * v.worldRadius : undefined,
+        seed: v.shape.seed, warpAmp: v.shape.warpAmp, warpFreq: v.shape.warpFreq,
+      })),
+    }
   }
 
   function clear() { volumes.length = 0 }
 
   return {
-    addSphereCave, heightDeltaAt, wrapHeightFn, toJSON, clear,
+    addSphereCave, addCylinderCave, addTunnelCave, heightDeltaAt, wrapHeightFn, toJSON, clear,
+    get volumes() { return volumes.slice() },
     get volumeCount() { return volumes.length },
   }
 }
@@ -85,7 +170,9 @@ export function loadCaveCarveLayer(json) {
   if (json && Array.isArray(json.volumes)) {
     for (const v of json.volumes) {
       if (!v || !Number.isFinite(v.worldX) || !Number.isFinite(v.worldY) || !Number.isFinite(v.worldZ) || !Number.isFinite(v.worldRadius)) continue
-      layer.addSphereCave(v.worldX, v.worldY, v.worldZ, v.worldRadius)
+      if (v.kind === 'cylinder') layer.addCylinderCave(v.worldX, v.worldY, v.worldZ, v.worldRadius, v.halfHeight ?? 1, v.axis ?? 'y')
+      else if (v.kind === 'tunnel') layer.addTunnelCave(v.worldX, v.worldY, v.worldZ, v.worldRadius, v.length ?? v.worldRadius * 2, v.axis ?? 'y', v.seed ?? 0, v.warpAmp ?? 0.15, v.warpFreq ?? 2.5)
+      else layer.addSphereCave(v.worldX, v.worldY, v.worldZ, v.worldRadius)
     }
   }
   return layer

package/src/terrain/TerrainPhysics.js

@@ -286,7 +286,7 @@ export async function setupTerrainStreaming({ physics, playerManager, worldDef,
   // stays byte-identical, sculpting is purely an on-top layer. heightDeltaJSON (if any) replays prior
   // strokes so a rebuild (reseed/streamer restart) keeps existing sculpting intact.
   const heightDelta = loadHeightDelta(heightDeltaJSON, baseHeightFn)
-  const caveCarve = loadCaveCarveLayer(caveCarveJSON)
+  const caveCarve = loadCaveCarveLayer(caveCarveJSON || (Array.isArray(tcfg.caveCarve) ? { version: 2, volumes: tcfg.caveCarve } : null))
   const heightFn = caveCarve.wrapHeightFn(splineCarve.wrapHeightFn(heightDelta.wrapHeightFn(baseHeightFn)))
   const getCenter = () => {
     let sx = 0, sz = 0, n = 0