spoint 0.1.671 → 0.1.673

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spoint",
-  "version": "0.1.671",
+  "version": "0.1.673",
   "description": "Physics and netcode SDK for multiplayer game servers",
   "type": "module",
   "workspaces": [
@@ -84,7 +84,6 @@
     "@gltf-transform/functions": "^4.4.0",
     "@pixiv/three-vrm": "^3.5.5",
     "@three.ez/instanced-mesh": "^0.3.15",
-    "alea": "^1.0.1",
     "bvh.js": "^0.0.13",
     "draco3d": "^1.5.7",
     "draco3dgltf": "^1.5.7",

package/src/netcode/LockstepTickSystem.js

@@ -5,7 +5,7 @@
 // either driver.
 //
 // The one deliberate, load-bearing difference from TickSystem: dt is NEVER derived from wall-clock
-// measurement. TickSystem's dilationFactor (_measureTick/_onInterval) adaptively shrinks dt under
+// measurement. TickSystem's dilationFactor (_onTickMeasured/_onInterval) adaptively shrinks dt under
 // server load so ONE authoritative server stays real-time-paced -- exactly the behavior a lockstep
 // peer must never exhibit, since every peer has to independently derive the IDENTICAL dt sequence
 // from tick number alone (deterministic-fixed-point-lockstep-architecture-for-rts-fighting's own
@@ -15,103 +15,34 @@
 // perf.now() delta would reintroduce the exact wall-clock leakage this row exists to bypass, so this
 // driver intentionally does NOT accumulate/measure real elapsed time to decide dt, only to decide
 // WHEN to fire the next already-fixed-size tick (wall clock only paces cadence, never sizes the step).
-export class LockstepTickSystem {
+//
+// Shares TickSystemBase's accumulator/catch-up scheduling loop with TickSystem.js verbatim -- only
+// _computeDt/_onTickMeasured differ (see that file's header comment for the shared-loop rationale).
+import { TickSystemBase } from './TickSystemBase.js'
+
+export class LockstepTickSystem extends TickSystemBase {
   constructor(tickRate = 60) {
-    this.tickRate = tickRate
-    this.tickDuration = 1000 / tickRate
-    this.currentTick = 0
-    this.lastTickTime = 0
-    this.callbacks = []
-    this._state = 'stopped'
-    this._reloadResolve = null
-    this._tickInProgress = false
-    // Fixed at 1.0, permanently -- unlike TickSystem, there is no _measureTick/_onInterval-driven
-    // mutation path at all, so this can never silently drift under load. Kept as a real field (not a
-    // getter constant) purely so any code doing `tickSystem.dilationFactor` for logging/diagnostics
-    // reads the same shape as TickSystem instead of throwing on a missing property.
-    this.dilationFactor = 1.0
-    this._dilationCallbacks = []
-    this._accumulator = 0
-    this._intervalHandle = null
+    super(tickRate)
+    this._tickErrorTag = '[lockstep-tick]'
+    // dilationFactor stays fixed at 1.0 permanently -- unlike TickSystem, there is no
+    // _onTickMeasured-driven mutation path at all, so this can never silently drift under load.
   }
 
-  get running() { return this._state === 'running' }
-
   // Kept for API parity with TickSystem.onDilation -- lockstep mode never dilates, so a registered
-  // callback simply never fires. Real no-op, not a stub thrown away later: any shared caller
-  // (TickHandler.js's server.js:297-style wiring) that unconditionally calls tickSystem.onDilation(...)
-  // must not throw when handed a LockstepTickSystem instead of a TickSystem.
-  onDilation(_cb) { this._dilationCallbacks.push(_cb) }
-
-  onTick(callback) {
-    if (this.callbacks.includes(callback)) return
-    this.callbacks.push(callback)
-  }
-
-  start() {
-    if (this.running) return
-    this._state = 'running'
-    this.lastTickTime = performance.now()
-    this._accumulator = 0
-    const intervalMs = Math.max(1, this.tickDuration / 2)
-    this._intervalHandle = setInterval(() => this._onInterval(), intervalMs)
-    if (this._intervalHandle.unref) this._intervalHandle.unref()
-  }
-
-  _onInterval() {
-    if (!this.running) return
-    const now = performance.now()
-    this._accumulator += now - this.lastTickTime
-    this.lastTickTime = now
-    const maxSteps = 4
-    const maxAccumulated = this.tickDuration * maxSteps
-    if (this._accumulator > maxAccumulated) this._accumulator = maxAccumulated
-    let steps = 0
-    const isPaused = this._state === 'paused'
-    while (this._accumulator >= this.tickDuration && !isPaused && steps < maxSteps) {
-      // dt is always the fixed, undilated tick duration -- the entire point of this driver. A stall
-      // (debugger pause, GC, slow machine) changes HOW MANY fixed-size ticks fire in this catch-up
-      // burst (same maxSteps cap as TickSystem), never the SIZE of any individual tick's dt.
-      this._tickInProgress = true
-      this.currentTick++
-      this._accumulator -= this.tickDuration
-      for (const callback of this.callbacks) {
-        try {
-          callback(this.currentTick, this.tickDuration / 1000)
-        } catch (e) {
-          console.error('[lockstep-tick]', e?.stack || e?.message || e)
-        }
-      }
-      this._tickInProgress = false
-      if (this._reloadResolve) {
-        this._reloadResolve()
-        this._reloadResolve = null
-      }
-      steps++
-    }
-  }
-
-  pauseForReload() {
-    this._state = 'paused'
-    if (!this._tickInProgress) return Promise.resolve()
-    return new Promise(resolve => { this._reloadResolve = resolve })
-  }
-
-  resumeAfterReload() {
-    this._state = 'running'
-    this.lastTickTime = performance.now()
-  }
-
-  stop() {
-    this._state = 'stopped'
-    if (this._intervalHandle) {
-      clearInterval(this._intervalHandle)
-      this._intervalHandle = null
-    }
+  // callback simply never fires (still pushed into _dilationCallbacks for parity, just never invoked).
+  // Real no-op, not a stub thrown away later: any shared caller (TickHandler.js's server.js:297-style
+  // wiring) that unconditionally calls tickSystem.onDilation(...) must not throw when handed a
+  // LockstepTickSystem instead of a TickSystem.
+
+  _computeDt() {
+    // dt is always the fixed, undilated tick duration -- the entire point of this driver. A stall
+    // (debugger pause, GC, slow machine) changes HOW MANY fixed-size ticks fire in this catch-up
+    // burst (same maxSteps cap as TickSystem), never the SIZE of any individual tick's dt.
+    return this.tickDuration / 1000
   }
 
-  getTick() {
-    return this.currentTick
+  _onTickMeasured(_budgetMs) {
+    // no-op: this driver never adapts dt to measured tick cost (see header comment)
   }
 
   getTickDuration() {

package/src/netcode/TickSystem.js

@@ -1,3 +1,5 @@
+import { TickSystemBase } from './TickSystemBase.js'
+
 const DILATION_WINDOW = 60
 const DILATION_THRESHOLD = 0.85
 const DILATION_MIN = 0.1
@@ -7,31 +9,21 @@ const DILATION_MIN_STEP = 0.01
 const DILATION_MAX_STEP = 0.25
 const DILATION_GAIN = 0.5
 
-export class TickSystem {
+export class TickSystem extends TickSystemBase {
   // 60Hz default (was 128) -- mirrors src/sdk/server.js's config.tickRate||60; every real caller passes
   // tickRate explicitly, this is only a defensive fallback for direct instantiation.
   constructor(tickRate = 60) {
-    this.tickRate = tickRate
-    this.tickDuration = 1000 / tickRate
-    this.currentTick = 0
-    this.lastTickTime = 0
-    this.callbacks = []
-    this._state = 'stopped'
-    this._reloadResolve = null
-    this._tickInProgress = false
-    this.dilationFactor = 1.0
-    this._dilationCallbacks = []
+    super(tickRate)
+    this._tickErrorTag = '[tick]'
     this._tickBudgetMs = []
     this._tickBudgetSum = 0
-    this._accumulator = 0
-    this._intervalHandle = null
   }
 
-  get running() { return this._state === 'running' }
-
-  onDilation(cb) { this._dilationCallbacks.push(cb) }
+  _computeDt() {
+    return (this.tickDuration * this.dilationFactor) / 1000
+  }
 
-  _measureTick(budget) {
+  _onTickMeasured(budget) {
     this._tickBudgetMs.push(budget)
     this._tickBudgetSum += budget
     if (this._tickBudgetMs.length > DILATION_WINDOW) {
@@ -57,85 +49,6 @@ export class TickSystem {
     }
   }
 
-  onTick(callback) {
-    // dedup by identity: re-registering the same callback must not fire it N times/tick
-    if (this.callbacks.includes(callback)) return
-    this.callbacks.push(callback)
-  }
-
-  start() {
-    if (this.running) return
-    this._state = 'running'
-    this.lastTickTime = performance.now()
-    this._accumulator = 0
-    // Fixed-timestep scheduling: a single setInterval at roughly half the tick
-    // duration drives the loop; each firing consumes as many whole ticks as have
-    // accumulated (accumulator-based catch-up), instead of a setTimeout(...,1)/
-    // setImmediate busy-loop that drifts and burns CPU re-scheduling every ~1ms.
-    const intervalMs = Math.max(1, this.tickDuration / 2)
-    this._intervalHandle = setInterval(() => this._onInterval(), intervalMs)
-    if (this._intervalHandle.unref) this._intervalHandle.unref()
-  }
-
-  _onInterval() {
-    if (!this.running) return
-    const now = performance.now()
-    this._accumulator += now - this.lastTickTime
-    this.lastTickTime = now
-    const maxSteps = 4
-    // Cap the catch-up burst so a long stall (debugger pause, GC, reload) doesn't
-    // try to replay an unbounded backlog of ticks in one go.
-    const maxAccumulated = this.tickDuration * maxSteps
-    if (this._accumulator > maxAccumulated) this._accumulator = maxAccumulated
-    let steps = 0
-    const isPaused = this._state === 'paused'
-    while (this._accumulator >= this.tickDuration && !isPaused && steps < maxSteps) {
-      const dilatedDuration = this.tickDuration * this.dilationFactor
-      this._tickInProgress = true
-      this.currentTick++
-      this._accumulator -= this.tickDuration
-      const t0 = performance.now()
-      for (const callback of this.callbacks) {
-        // a throwing callback must not abort the loop / wedge pauseForReload's _tickInProgress
-        try {
-          callback(this.currentTick, dilatedDuration / 1000)
-        } catch (e) {
-          console.error('[tick]', e?.stack || e?.message || e)
-        }
-      }
-      this._measureTick(performance.now() - t0)
-      this._tickInProgress = false
-      if (this._reloadResolve) {
-        this._reloadResolve()
-        this._reloadResolve = null
-      }
-      steps++
-    }
-  }
-
-  pauseForReload() {
-    this._state = 'paused'
-    if (!this._tickInProgress) return Promise.resolve()
-    return new Promise(resolve => { this._reloadResolve = resolve })
-  }
-
-  resumeAfterReload() {
-    this._state = 'running'
-    this.lastTickTime = performance.now()
-  }
-
-  stop() {
-    this._state = 'stopped'
-    if (this._intervalHandle) {
-      clearInterval(this._intervalHandle)
-      this._intervalHandle = null
-    }
-  }
-
-  getTick() {
-    return this.currentTick
-  }
-
   getTickDuration() {
     return (this.tickDuration * this.dilationFactor) / 1000
   }

package/src/netcode/TickSystemBase.js

@@ -0,0 +1,107 @@
+// Shared fixed-timestep tick-scheduling base for TickSystem.js (adaptive, wall-clock-dilated) and
+// LockstepTickSystem.js (fixed-dt, deterministic). Both drivers need the IDENTICAL accumulator/catch-up
+// scheduling loop (a single setInterval at ~half the tick duration, consuming whole accumulated ticks
+// per firing, capped at maxSteps=4 so a stall's catch-up burst is bounded) -- what differs is ONLY how
+// each computes the dt handed to callbacks and whether it measures tick cost to adapt dilationFactor.
+// Subclasses override _computeDt() (the per-tick dt in seconds) and _onTickMeasured(budgetMs) (called
+// with each tick's real wall-clock cost, a no-op for the deterministic lockstep driver).
+
+export class TickSystemBase {
+  constructor(tickRate = 60) {
+    this.tickRate = tickRate
+    this.tickDuration = 1000 / tickRate
+    this.currentTick = 0
+    this.lastTickTime = 0
+    this.callbacks = []
+    this._state = 'stopped'
+    this._reloadResolve = null
+    this._tickInProgress = false
+    this.dilationFactor = 1.0
+    this._dilationCallbacks = []
+    this._accumulator = 0
+    this._intervalHandle = null
+  }
+
+  get running() { return this._state === 'running' }
+
+  onDilation(cb) { this._dilationCallbacks.push(cb) }
+
+  onTick(callback) {
+    // dedup by identity: re-registering the same callback must not fire it N times/tick
+    if (this.callbacks.includes(callback)) return
+    this.callbacks.push(callback)
+  }
+
+  start() {
+    if (this.running) return
+    this._state = 'running'
+    this.lastTickTime = performance.now()
+    this._accumulator = 0
+    // Fixed-timestep scheduling: a single setInterval at roughly half the tick
+    // duration drives the loop; each firing consumes as many whole ticks as have
+    // accumulated (accumulator-based catch-up), instead of a setTimeout(...,1)/
+    // setImmediate busy-loop that drifts and burns CPU re-scheduling every ~1ms.
+    const intervalMs = Math.max(1, this.tickDuration / 2)
+    this._intervalHandle = setInterval(() => this._onInterval(), intervalMs)
+    if (this._intervalHandle.unref) this._intervalHandle.unref()
+  }
+
+  _onInterval() {
+    if (!this.running) return
+    const now = performance.now()
+    this._accumulator += now - this.lastTickTime
+    this.lastTickTime = now
+    const maxSteps = 4
+    // Cap the catch-up burst so a long stall (debugger pause, GC, reload) doesn't
+    // try to replay an unbounded backlog of ticks in one go.
+    const maxAccumulated = this.tickDuration * maxSteps
+    if (this._accumulator > maxAccumulated) this._accumulator = maxAccumulated
+    let steps = 0
+    const isPaused = this._state === 'paused'
+    while (this._accumulator >= this.tickDuration && !isPaused && steps < maxSteps) {
+      const dt = this._computeDt()
+      this._tickInProgress = true
+      this.currentTick++
+      this._accumulator -= this.tickDuration
+      const t0 = performance.now()
+      for (const callback of this.callbacks) {
+        // a throwing callback must not abort the loop / wedge pauseForReload's _tickInProgress
+        try {
+          callback(this.currentTick, dt)
+        } catch (e) {
+          console.error(this._tickErrorTag, e?.stack || e?.message || e)
+        }
+      }
+      this._onTickMeasured(performance.now() - t0)
+      this._tickInProgress = false
+      if (this._reloadResolve) {
+        this._reloadResolve()
+        this._reloadResolve = null
+      }
+      steps++
+    }
+  }
+
+  pauseForReload() {
+    this._state = 'paused'
+    if (!this._tickInProgress) return Promise.resolve()
+    return new Promise(resolve => { this._reloadResolve = resolve })
+  }
+
+  resumeAfterReload() {
+    this._state = 'running'
+    this.lastTickTime = performance.now()
+  }
+
+  stop() {
+    this._state = 'stopped'
+    if (this._intervalHandle) {
+      clearInterval(this._intervalHandle)
+      this._intervalHandle = null
+    }
+  }
+
+  getTick() {
+    return this.currentTick
+  }
+}