@lanmower/entrypoint 0.16.0

package/src/sdk/ClientMessageHandler.js

@@ -0,0 +1,80 @@
+import { MSG } from '../protocol/MessageTypes.js'
+import { SnapshotEncoder } from '../netcode/SnapshotEncoder.js'
+import { unpack } from '../protocol/msgpack.js'
+
+export function createMessageRouter(deps) {
+  const { emitter, quality, stateInspector, send, getState, setState } = deps
+
+  function handleSnapshot(data) {
+    try {
+      const decoded = SnapshotEncoder.decode(data)
+      if (decoded.tick) {
+        stateInspector.recordSnapshotDelay(Date.now() - (decoded.timestamp || 0))
+        setState('tick', decoded.tick)
+      }
+      for (const p of decoded.players || []) getState('players').set(p.id, p)
+      for (const e of decoded.entities || []) getState('entities').set(e.id, e)
+      emitter.emit('snapshot', decoded)
+    } catch (e) {
+      emitter.emit('error', e)
+    }
+  }
+
+  return function onMessage(raw) {
+    const buf = raw instanceof ArrayBuffer ? new Uint8Array(raw) : (raw instanceof Uint8Array ? raw : new Uint8Array(raw.buffer, raw.byteOffset, raw.byteLength))
+    let msg
+    try { msg = unpack(buf) } catch (e) { return }
+    if (!msg || typeof msg !== 'object') return
+    const byteLen = buf.length || buf.byteLength || 0
+    quality.recordBytesIn(byteLen)
+
+    if (msg.type === MSG.HEARTBEAT) {
+      send(MSG.HEARTBEAT_ACK, { ts: msg.payload?.ts })
+      return
+    }
+    if (msg.type === MSG.HEARTBEAT_ACK && msg.payload?.ts) {
+      quality.recordRtt(Date.now() - msg.payload.ts)
+      quality.recordHeartbeatReceived()
+      return
+    }
+    if (msg.type === MSG.HANDSHAKE_ACK) {
+      setState('playerId', msg.payload.playerId)
+      setState('sessionToken', msg.payload.sessionToken)
+      setState('tick', msg.payload.tick)
+      emitter.emit('connect', { playerId: msg.payload.playerId, tick: msg.payload.tick })
+      return
+    }
+    if (msg.type === MSG.SNAPSHOT) { handleSnapshot(msg.payload); return }
+    if (msg.type === MSG.PLAYER_LEAVE) {
+      getState('players').delete(msg.payload.playerId)
+      emitter.emit('playerLeave', msg.payload.playerId)
+      return
+    }
+    if (msg.type === MSG.RECONNECT_ACK) {
+      setState('playerId', msg.payload.playerId)
+      setState('sessionToken', msg.payload.sessionToken)
+      setState('tick', msg.payload.tick)
+      setState('reconnecting', false)
+      setState('reconnectAttempts', 0)
+      emitter.emit('reconnect', msg.payload)
+      return
+    }
+    if (msg.type === MSG.STATE_RECOVERY) {
+      const decoded = SnapshotEncoder.decode(msg.payload.snapshot)
+      for (const p of decoded.players || []) getState('players').set(p.id, p)
+      for (const e of decoded.entities || []) getState('entities').set(e.id, e)
+      emitter.emit('stateRecovery', decoded)
+      return
+    }
+    if (msg.type === MSG.STATE_CORRECTION) {
+      stateInspector.recordCorrection(getState('playerId'), null, msg.payload, 0)
+      emitter.emit('correction', msg.payload)
+      return
+    }
+    if (msg.type === MSG.DISCONNECT_REASON) {
+      emitter.emit('disconnectReason', msg.payload)
+      return
+    }
+    emitter.emit('message', msg)
+  }
+}

package/src/sdk/ReloadHandlers.js

@@ -0,0 +1,68 @@
+function swapInstance(target, NewClass, constructArgs, stateKeys) {
+  const oldProto = Object.getPrototypeOf(target)
+  const oldOwnDescriptors = Object.getOwnPropertyDescriptors(target)
+  try {
+    const fresh = new NewClass(...constructArgs)
+    Object.setPrototypeOf(target, NewClass.prototype)
+    const freshDescriptors = Object.getOwnPropertyDescriptors(fresh)
+    for (const key of Object.keys(freshDescriptors)) {
+      if (!stateKeys.includes(key)) {
+        Object.defineProperty(target, key, freshDescriptors[key])
+      }
+    }
+    for (const key of Object.keys(oldOwnDescriptors)) {
+      if (!(key in freshDescriptors) && !stateKeys.includes(key)) {
+        delete target[key]
+      }
+    }
+  } catch (e) {
+    Object.setPrototypeOf(target, oldProto)
+    for (const [key, desc] of Object.entries(oldOwnDescriptors)) {
+      Object.defineProperty(target, key, desc)
+    }
+    for (const key of Object.keys(target)) {
+      if (!(key in oldOwnDescriptors)) delete target[key]
+    }
+    throw e
+  }
+}
+
+export function createReloadHandlers(deps) {
+  const {
+    networkState, playerManager, physicsIntegration,
+    lagCompensator, physics, appRuntime, connections
+  } = deps
+
+  const reloadTickHandler = async () => {
+    const { createTickHandler: refreshHandler } = await import('./TickHandler.js?' + Date.now())
+    return refreshHandler(deps)
+  }
+
+  const reloadPhysicsIntegration = async () => {
+    const { PhysicsIntegration: New } = await import('../netcode/PhysicsIntegration.js?' + Date.now())
+    swapInstance(physicsIntegration, New, [{ ...physicsIntegration.config, physicsWorld: physics }], ['playerBodies'])
+  }
+
+  const reloadLagCompensator = async () => {
+    const { LagCompensator: New } = await import('../netcode/LagCompensator.js?' + Date.now())
+    swapInstance(lagCompensator, New, [lagCompensator.historyWindow], ['playerHistory'])
+  }
+
+  const reloadPlayerManager = async () => {
+    const { PlayerManager: New } = await import('../netcode/PlayerManager.js?' + Date.now())
+    swapInstance(playerManager, New, [], ['players', 'inputBuffers', 'nextPlayerId'])
+  }
+
+  const reloadNetworkState = async () => {
+    const { NetworkState: New } = await import('../netcode/NetworkState.js?' + Date.now())
+    swapInstance(networkState, New, [], ['players', 'tick', 'timestamp'])
+  }
+
+  return {
+    reloadTickHandler,
+    reloadPhysicsIntegration,
+    reloadLagCompensator,
+    reloadPlayerManager,
+    reloadNetworkState
+  }
+}

package/src/sdk/ReloadManager.js

@@ -0,0 +1,126 @@
+import { watch } from 'node:fs/promises'
+import { resolve } from 'node:path'
+
+export class ReloadManager {
+  constructor() {
+    this._watchers = new Map()
+    this._moduleCache = new Map()
+    this._reloadState = new Map()
+    this._debounceTimers = new Map()
+    this._failureCounters = new Map()
+    this._validators = new Map()
+    this._MAX_FAILURES = 3
+    this._MAX_BACKOFF = 400
+  }
+
+  addWatcher(moduleId, filePath, onReload, validator) {
+    const absPath = resolve(filePath)
+    if (this._watchers.has(moduleId)) return
+    this._reloadState.set(moduleId, { inProgress: false, lastSuccess: null, failureCount: 0 })
+    this._failureCounters.set(moduleId, 0)
+    if (validator) this._validators.set(moduleId, validator)
+    const startWatch = async () => {
+      try {
+        const ac = new AbortController()
+        this._watchers.set(moduleId, ac)
+        const watcher = watch(absPath, { signal: ac.signal })
+        ;(async () => {
+          try {
+            for await (const event of watcher) {
+              this._debounce(moduleId, () => this._handleReload(moduleId, onReload))
+            }
+          } catch (e) {
+            if (e.name !== 'AbortError') {
+              console.error(`[ReloadManager] watch error for ${moduleId}:`, e.message)
+            }
+          }
+        })()
+      } catch (e) {
+        console.error(`[ReloadManager] failed to start watcher for ${moduleId}:`, e.message)
+      }
+    }
+    startWatch()
+  }
+
+  _debounce(moduleId, fn) {
+    if (this._debounceTimers.has(moduleId)) {
+      clearTimeout(this._debounceTimers.get(moduleId))
+    }
+    this._failureCounters.set(moduleId, 0)
+    const timer = setTimeout(() => {
+      fn()
+      this._debounceTimers.delete(moduleId)
+    }, 100)
+    this._debounceTimers.set(moduleId, timer)
+  }
+
+  async _handleReload(moduleId, onReload) {
+    const state = this._reloadState.get(moduleId)
+    if (!state) return
+    if (state.inProgress) return
+    state.inProgress = true
+    const failureCount = this._failureCounters.get(moduleId) || 0
+    if (failureCount >= this._MAX_FAILURES) {
+      console.error(`[ReloadManager] ${moduleId} exceeded max failures, stopping auto-reload`)
+      state.inProgress = false
+      return
+    }
+    const validator = this._validators.get(moduleId)
+    if (validator) {
+      try {
+        const valid = await validator()
+        if (!valid) {
+          console.warn(`[ReloadManager] ${moduleId} failed pre-reload validation, skipping`)
+          state.inProgress = false
+          return
+        }
+      } catch (e) {
+        console.warn(`[ReloadManager] ${moduleId} validation error, skipping:`, e.message)
+        state.inProgress = false
+        return
+      }
+    }
+    try {
+      await onReload()
+      this._failureCounters.set(moduleId, 0)
+      state.lastSuccess = Date.now()
+      console.log(`[ReloadManager] successfully reloaded ${moduleId}`)
+    } catch (e) {
+      const newFailureCount = failureCount + 1
+      this._failureCounters.set(moduleId, newFailureCount)
+      const backoff = Math.min(100 * Math.pow(2, failureCount - 1), this._MAX_BACKOFF)
+      console.error(`[ReloadManager] reload failed for ${moduleId} (${newFailureCount}/${this._MAX_FAILURES}):`, e.message)
+      if (newFailureCount < this._MAX_FAILURES) {
+        console.log(`[ReloadManager] retrying ${moduleId} in ${backoff}ms`)
+        await new Promise(resolve => setTimeout(resolve, backoff))
+        state.inProgress = false
+        await this._handleReload(moduleId, onReload)
+        return
+      } else {
+        console.error(`[ReloadManager] ${moduleId} gave up after ${newFailureCount} failures`)
+      }
+    }
+    state.inProgress = false
+  }
+
+  stopWatcher(moduleId) {
+    const ac = this._watchers.get(moduleId)
+    if (ac) ac.abort()
+    this._watchers.delete(moduleId)
+    this._debounceTimers.delete(moduleId)
+  }
+
+  stopAllWatchers() {
+    for (const ac of this._watchers.values()) ac.abort()
+    this._watchers.clear()
+    for (const timer of this._debounceTimers.values()) clearTimeout(timer)
+    this._debounceTimers.clear()
+  }
+
+  cacheModule(moduleId, module) { this._moduleCache.set(moduleId, module) }
+  getModule(moduleId) { return this._moduleCache.get(moduleId) }
+  getState(moduleId) { return this._reloadState.get(moduleId) }
+  getStats() {
+    return { watchers: this._watchers.size, modules: this._moduleCache.size, failures: Object.fromEntries(this._failureCounters) }
+  }
+}

package/src/sdk/ServerAPI.js

@@ -0,0 +1,133 @@
+import { createServer as createHttpServer } from 'node:http'
+import { WebSocketServer as WSServer } from 'ws'
+import { MSG } from '../protocol/MessageTypes.js'
+import { SnapshotEncoder } from '../netcode/SnapshotEncoder.js'
+import { createStaticHandler } from './StaticHandler.js'
+import { WebSocketTransport } from '../transport/WebSocketTransport.js'
+import { WebTransportServer } from '../transport/WebTransportServer.js'
+
+export function createServerAPI(ctx) {
+  const { config, port, tickRate, staticDirs, appLoader, appRuntime, physics, stageLoader } = ctx
+  const { tickSystem, playerManager, networkState, lagCompensator, connections, sessions, inspector, emitter, reloadManager, eventBus, eventLog, storage } = ctx
+
+  return {
+    physics,
+    runtime: appRuntime,
+    loader: appLoader,
+    tickSystem,
+    playerManager,
+    networkState,
+    lagCompensator,
+    connections,
+    sessions,
+    inspector,
+    emitter,
+    reloadManager,
+    eventBus,
+    eventLog,
+    storage,
+    on: emitter.on.bind(emitter),
+    off: emitter.off.bind(emitter),
+
+    stageLoader,
+
+    async loadWorld(worldDef) {
+      ctx.currentWorldDef = worldDef
+      if (worldDef.spawnPoint) ctx.worldSpawnPoint = [...worldDef.spawnPoint]
+      await appLoader.loadAll()
+      const stage = stageLoader.loadFromDefinition('main', worldDef)
+      return { entities: new Map(), apps: new Map(), count: stage.entityCount }
+    },
+
+    async start() {
+      await appLoader.loadAll()
+      return new Promise((resolve, reject) => {
+        if (staticDirs.length > 0) {
+          ctx.httpServer = createHttpServer(createStaticHandler(staticDirs))
+          ctx.wss = new WSServer({ server: ctx.httpServer, path: '/ws' })
+          ctx.httpServer.on('error', reject)
+          ctx.httpServer.listen(port, () => {
+            attachWSHandlers(ctx)
+            resolve({ port: ctx.port, tickRate: ctx.tickRate })
+          })
+        } else {
+          ctx.wss = new WSServer({ port }, () => {
+            attachWSHandlers(ctx)
+            resolve({ port: ctx.port, tickRate: ctx.tickRate })
+          })
+          ctx.wss.on('error', reject)
+        }
+      })
+    },
+
+    stop() {
+      tickSystem.stop()
+      appLoader.stopWatching()
+      reloadManager.stopAllWatchers()
+      connections.destroy()
+      sessions.destroyAll()
+      if (ctx.wtServer) ctx.wtServer.stop()
+      if (ctx.wss) ctx.wss.close()
+      if (ctx.httpServer) ctx.httpServer.close()
+      physics.destroy()
+    },
+
+    send(id, type, p) {
+      return connections.send(id, type, p)
+    },
+
+    broadcast(type, p) {
+      connections.broadcast(type, p)
+    },
+
+    getPlayerCount() {
+      return playerManager.getPlayerCount()
+    },
+
+    getEntityCount() {
+      return appRuntime.entities.size
+    },
+
+    getSnapshot() {
+      return appRuntime.getSnapshot()
+    },
+
+    reloadTickHandler: async () => {
+      ctx.setTickHandler(await ctx.reloadHandlers.reloadTickHandler())
+    },
+
+    getReloadStats() {
+      return reloadManager.getStats()
+    },
+
+    getAllStats() {
+      return {
+        connections: connections.getAllStats(),
+        inspector: inspector.getAllClients(connections),
+        sessions: sessions.getActiveCount(),
+        tick: tickSystem.currentTick,
+        players: playerManager.getPlayerCount()
+      }
+    }
+  }
+}
+
+function attachWSHandlers(ctx) {
+  ctx.wss.on('connection', (socket) => {
+    ctx.onClientConnect(new WebSocketTransport(socket))
+  })
+  if (ctx.config.webTransport) {
+    const wtp = ctx.config.webTransport.port || 4433
+    ctx.wtServer = new WebTransportServer({
+      port: wtp,
+      cert: ctx.config.webTransport.cert,
+      key: ctx.config.webTransport.key
+    })
+    ctx.wtServer.on('session', ctx.onClientConnect)
+    if (ctx.wtServer.start()) console.log()
+  }
+  ctx.tickSystem.onTick(ctx.onTick)
+  ctx.tickSystem.start()
+  ctx.appLoader.watchAll()
+  ctx.setupSDKWatchers()
+}

package/src/sdk/ServerHandlers.js

@@ -0,0 +1,76 @@
+import { MSG, DISCONNECT_REASONS } from '../protocol/MessageTypes.js'
+import { SnapshotEncoder } from '../netcode/SnapshotEncoder.js'
+
+export function createConnectionHandlers(ctx) {
+  const { tickSystem, playerManager, networkState, lagCompensator, physicsIntegration, connections, sessions, appLoader, appRuntime, emitter, inspector } = ctx
+
+  function onClientConnect(transport) {
+    const sp = [...ctx.worldSpawnPoint]
+    const playerId = playerManager.addPlayer(transport, { position: sp })
+    networkState.addPlayer(playerId, { position: sp })
+    physicsIntegration.addPlayerCollider(playerId, 0.4)
+    physicsIntegration.setPlayerPosition(playerId, sp)
+    const playerState = playerManager.getPlayer(playerId).state
+    lagCompensator.recordPlayerPosition(playerId, playerState.position, playerState.rotation, playerState.velocity, tickSystem.currentTick)
+    const client = connections.addClient(playerId, transport)
+    client.sessionToken = sessions.create(playerId, playerManager.getPlayer(playerId).state)
+    connections.send(playerId, MSG.HANDSHAKE_ACK, { playerId, tick: tickSystem.currentTick, sessionToken: client.sessionToken, tickRate: ctx.tickRate })
+    if (ctx.currentWorldDef) {
+      connections.send(playerId, MSG.WORLD_DEF, ctx.currentWorldDef)
+    }
+    const clientModules = appLoader.getClientModules()
+    for (const [appName, code] of Object.entries(clientModules)) {
+      connections.send(playerId, MSG.APP_MODULE, { app: appName, code })
+    }
+    const snap = appRuntime.getSnapshot()
+    connections.send(playerId, MSG.SNAPSHOT, { seq: ++ctx.snapshotSeq, ...SnapshotEncoder.encode(snap) })
+    appRuntime.fireMessage('game', { type: 'player_join', playerId })
+    emitter.emit('playerJoin', { id: playerId })
+  }
+
+  connections.on('message', (clientId, msg) => {
+    if (inspector.handleMessage(clientId, msg)) return
+    if (msg.type === MSG.INPUT || msg.type === MSG.PLAYER_INPUT) {
+      playerManager.addInput(clientId, msg.payload?.input || msg.payload)
+      return
+    }
+    if (msg.type === MSG.APP_EVENT) {
+      if (msg.payload?.entityId) appRuntime.fireInteract(msg.payload.entityId, { id: clientId })
+      if (msg.payload?.type === 'fire') {
+        const shooter = playerManager.getPlayer(clientId)
+        const pos = shooter?.state?.position || [0, 0, 0]
+        const origin = [pos[0], pos[1] + 0.9, pos[2]]
+        appRuntime.fireMessage('game', { ...msg.payload, shooterId: clientId, origin })
+      }
+      return
+    }
+    if (msg.type === MSG.RECONNECT) {
+      const session = sessions.get(msg.payload?.sessionToken)
+      if (!session) {
+        connections.send(clientId, MSG.DISCONNECT_REASON, { code: DISCONNECT_REASONS.INVALID_SESSION })
+        return
+      }
+      const snap = networkState.getSnapshot()
+      const ents = appRuntime.getSnapshot()
+      connections.send(clientId, MSG.RECONNECT_ACK, { playerId: session.playerId, tick: tickSystem.currentTick, sessionToken: msg.payload.sessionToken })
+      connections.send(clientId, MSG.STATE_RECOVERY, { snapshot: SnapshotEncoder.encode({ tick: snap.tick, timestamp: snap.timestamp, players: snap.players, entities: ents.entities }), tick: tickSystem.currentTick })
+      return
+    }
+    emitter.emit('message', clientId, msg)
+  })
+
+  connections.on('disconnect', (clientId, reason) => {
+    const client = connections.getClient(clientId)
+    if (client?.sessionToken) { const p = playerManager.getPlayer(clientId); if (p) sessions.update(client.sessionToken, { state: p.state }) }
+    appRuntime.fireMessage('game', { type: 'player_leave', playerId: clientId })
+    physicsIntegration.removePlayerCollider(clientId)
+    lagCompensator.clearPlayerHistory(clientId)
+    inspector.removeClient(clientId)
+    playerManager.removePlayer(clientId)
+    networkState.removePlayer(clientId)
+    connections.broadcast(MSG.PLAYER_LEAVE, { playerId: clientId })
+    emitter.emit('playerLeave', { id: clientId, reason })
+  })
+
+  return { onClientConnect }
+}

package/src/sdk/StaticHandler.js

@@ -0,0 +1,32 @@
+import { readFileSync, existsSync } from 'node:fs'
+import { join, extname } from 'node:path'
+
+const MIME_TYPES = {
+  '.html': 'text/html', '.js': 'text/javascript', '.css': 'text/css',
+  '.json': 'application/json', '.glb': 'model/gltf-binary', '.gltf': 'model/gltf+json',
+  '.png': 'image/png', '.jpg': 'image/jpeg', '.webp': 'image/webp',
+  '.svg': 'image/svg+xml', '.wasm': 'application/wasm'
+}
+
+export function createStaticHandler(dirs) {
+  return (req, res) => {
+    const url = req.url.split('?')[0]
+    for (const { prefix, dir } of dirs) {
+      if (!url.startsWith(prefix)) continue
+      const relative = url === prefix ? '/index.html' : url.slice(prefix.length)
+      const fp = join(dir, relative)
+      if (existsSync(fp)) {
+        const ext = extname(fp)
+        const headers = { 'Content-Type': MIME_TYPES[ext] || 'application/octet-stream' }
+        if (ext === '.js' || ext === '.html' || ext === '.css') {
+          headers['Cache-Control'] = 'no-cache, no-store, must-revalidate'
+        }
+        res.writeHead(200, headers)
+        res.end(readFileSync(fp))
+        return
+      }
+    }
+    res.writeHead(404)
+    res.end('not found')
+  }
+}

package/src/sdk/TickHandler.js

@@ -0,0 +1,84 @@
+import { MSG } from '../protocol/MessageTypes.js'
+import { SnapshotEncoder } from '../netcode/SnapshotEncoder.js'
+import { applyMovement, DEFAULT_MOVEMENT } from '../shared/movement.js'
+
+export function createTickHandler(deps) {
+  const {
+    networkState, playerManager, physicsIntegration,
+    lagCompensator, physics, appRuntime, connections,
+    movement: m = {}, stageLoader, eventLog
+  } = deps
+  const movement = { ...DEFAULT_MOVEMENT, ...m }
+  const collisionRestitution = m.collisionRestitution || 0.2
+  const collisionDamping = m.collisionDamping || 0.25
+  let snapshotSeq = 0
+
+  return function onTick(tick, dt) {
+    networkState.setTick(tick, Date.now())
+    for (const player of playerManager.getConnectedPlayers()) {
+      const inputs = playerManager.getInputs(player.id)
+      const st = player.state
+      let inp = null
+
+      if (inputs.length > 0) {
+        inp = inputs[inputs.length - 1].data
+        if (inp) {
+          const yaw = inp.yaw || 0
+          st.rotation = [0, Math.sin(yaw / 2), 0, Math.cos(yaw / 2)]
+        }
+        playerManager.clearInputs(player.id)
+      }
+
+      applyMovement(st, inp, movement, dt)
+      const updated = physicsIntegration.updatePlayerPhysics(player.id, st, dt)
+      st.position = updated.position
+      st.velocity = updated.velocity
+      st.onGround = updated.onGround
+      lagCompensator.recordPlayerPosition(player.id, st.position, st.rotation, st.velocity, tick)
+      networkState.updatePlayer(player.id, {
+        position: st.position, rotation: st.rotation,
+        velocity: st.velocity, onGround: st.onGround,
+        health: st.health, inputSequence: player.inputSequence
+      })
+    }
+    const players = playerManager.getConnectedPlayers()
+    for (const player of players) {
+      const collisions = physicsIntegration.checkCollisionWithOthers(player.id, players)
+      for (const collision of collisions) {
+        const other = playerManager.getPlayer(collision.playerId)
+        if (!other) continue
+        const dx = collision.normal[0], dy = collision.normal[1], dz = collision.normal[2]
+        const relVx = other.state.velocity[0] - player.state.velocity[0]
+        const relVz = other.state.velocity[2] - player.state.velocity[2]
+        const relDotNorm = relVx * dx + relVz * dz
+        if (relDotNorm >= 0) continue
+        const impulse = (1 + collisionRestitution) * relDotNorm * 0.5
+        player.state.velocity[0] -= impulse * dx * collisionDamping
+        player.state.velocity[2] -= impulse * dz * collisionDamping
+        other.state.velocity[0] += impulse * dx * collisionDamping
+        other.state.velocity[2] += impulse * dz * collisionDamping
+      }
+    }
+    physics.step(dt)
+    appRuntime.tick(tick, dt)
+    const playerSnap = networkState.getSnapshot()
+    snapshotSeq++
+    if (stageLoader && stageLoader.getActiveStage()) {
+      for (const player of players) {
+        const pos = player.state.position
+        const entitySnap = appRuntime.getSnapshotForPlayer(pos, stageLoader.getActiveStage().spatial.relevanceRadius)
+        const combined = { tick: playerSnap.tick, timestamp: playerSnap.timestamp, players: playerSnap.players, entities: entitySnap.entities }
+        connections.send(player.id, MSG.SNAPSHOT, { seq: snapshotSeq, ...SnapshotEncoder.encode(combined) })
+      }
+    } else {
+      const entitySnap = appRuntime.getSnapshot()
+      const combined = { tick: playerSnap.tick, timestamp: playerSnap.timestamp, players: playerSnap.players, entities: entitySnap.entities }
+      connections.broadcast(MSG.SNAPSHOT, { seq: snapshotSeq, ...SnapshotEncoder.encode(combined) })
+    }
+    try {
+      appRuntime._drainReloadQueue()
+    } catch (e) {
+      console.error('[TickHandler] reload queue error:', e.message)
+    }
+  }
+}