Spawnpoint

Multiplayer game server SDK. 128 TPS authoritative server, Jolt Physics WASM, WebSocket transport, hot reload.

Quick Start

npm install
node server.js
# http://localhost:8080

Architecture

server.js                    Entry point, calls boot()
src/sdk/server.js            Creates all subsystems, wires them together
src/sdk/TickHandler.js       Per-tick: movement -> physics -> collisions -> app tick -> snapshot
src/sdk/ReloadManager.js     File watchers for SDK hot reload
src/apps/AppRuntime.js       Entity system, app lifecycle, timers, collision events
src/apps/AppLoader.js        Loads apps from apps/ directory, validates, watches for changes
src/physics/World.js          Jolt Physics wrapper (bodies, characters, raycasts)
src/netcode/PhysicsIntegration.js  CharacterVirtual per player, gravity application
src/connection/ConnectionManager.js  WebSocket client management, heartbeat, msgpack encode/decode
src/protocol/msgpack.js       Hand-rolled msgpack encoder/decoder
client/app.js                Three.js renderer, VRM loading, entity rendering, input loop

World Config

apps/world/index.js exports the world definition:

export default {
  port: 8080,
  tickRate: 128,
  gravity: [0, -9.81, 0],
  movement: { maxSpeed: 4.0, groundAccel: 10.0, airAccel: 1.0, friction: 6.0, stopSpeed: 2.0, jumpImpulse: 4.0 },
  player: { health: 100, capsuleRadius: 0.4, capsuleHalfHeight: 0.9, mass: 120, modelScale: 1.323, feetOffset: 0.212 },
  scene: { skyColor: 0x87ceeb, sunColor: 0xffffff, sunIntensity: 1.5, sunPosition: [21, 50, 20] },
  camera: { fov: 70, shoulderOffset: 0.35, zoomStages: [0, 1.5, 3, 5, 8], defaultZoomIndex: 2 },
  animation: { mixerTimeScale: 1.3, walkTimeScale: 2.0, sprintTimeScale: 0.56, fadeTime: 0.15 },
  entities: [
    { id: 'environment', model: './apps/tps-game/schwust.glb', position: [0, 0, 0], app: 'environment' },
    { id: 'game', position: [0, 0, 0], app: 'tps-game' }
  ],
  playerModel: './apps/tps-game/Cleetus.vrm',
  spawnPoint: [-35, 3, -65]
}

Creating Apps

Create apps/<name>/index.js:

export default {
  server: {
    setup(ctx) {
      // Called once on spawn and on hot reload
      // ctx.state persists across hot reloads
      ctx.state.counter = ctx.state.counter || 0
    },
    update(ctx, dt) {
      // Called every tick (128/sec)
      ctx.state.counter += dt
    },
    teardown(ctx) {
      // Called on destroy or before hot reload
    },
    onMessage(ctx, msg) {
      // Receives player_join, player_leave, fire, and custom APP_EVENT messages
      if (msg.type === 'player_join') { /* ... */ }
    },
    onInteract(ctx, player) {
      // Called when client sends APP_EVENT with this entity's ID
    },
    onCollision(ctx, other) {
      // Called when this entity's collider overlaps another entity's collider
    }
  },
  client: {
    setup(engine) {
      // engine.scene, engine.camera, engine.renderer, engine.THREE, engine.client, engine.cam
    },
    render(ctx) {
      // Return visual state. ctx.entity, ctx.state, ctx.h (createElement), ctx.engine, ctx.players
      return {
        position: ctx.entity.position,
        custom: { mesh: 'box', color: 0xff0000, sx: 1, sy: 1, sz: 1 },
        ui: ctx.h('div', {}, 'Hello')
      }
    },
    onInput(input, engine) { },
    onFrame(dt, engine) { },
    onEvent(payload, engine) { },
    onMouseDown(e, engine) { },
    onMouseUp(e, engine) { }
  }
}

Server-Side ctx API

| Property | Description | |---|---| | ctx.state | Persistent state object (survives hot reload) | | ctx.entity | Entity proxy: .id, .position, .rotation, .scale, .velocity, .custom, .destroy() | | ctx.physics | .addBoxCollider(size), .addSphereCollider(r), .addCapsuleCollider(r, h), .addTrimeshCollider(), .setDynamic(bool), .addForce(vec3), .setVelocity(vec3) | | ctx.world | .spawn(id, cfg), .destroy(id), .attach(eid, app), .getEntity(id), .query(filter), .nearby(pos, radius) | | ctx.players | .getAll(), .getNearest(pos, r), .send(pid, msg), .broadcast(msg), .setPosition(pid, pos) | | ctx.time | .tick, .deltaTime, .elapsed, .after(sec, fn), .every(sec, fn) | | ctx.bus | .on(channel, fn), .emit(channel, data), .once(channel, fn), .handover(targetEntityId, state) | | ctx.network | .broadcast(msg), .sendTo(id, msg) | | ctx.storage | .get(key), .set(key, val), .delete(key), .list(prefix), .has(key) | | ctx.config | Entity config passed from world definition | | ctx.raycast(origin, dir, maxDist) | Physics raycast against world geometry |

Client Engine API

| Property | Description | |---|---| | engine.scene | THREE.Scene | | engine.camera | THREE.PerspectiveCamera | | engine.renderer | THREE.WebGLRenderer | | engine.THREE | Three.js module | | engine.client | PhysicsNetworkClient instance | | engine.playerId | Local player ID | | engine.cam | Camera controller: .yaw, .pitch, .getAimDirection(pos), .setMode(m), .applyConfig(cfg) | | engine.players | .getMesh(id), .getState(id), .getAnimator(id), .setExpression(id, name, val) | | engine.createElement | webjsx createElement for UI |

Entity Custom Mesh Properties

When an entity has no model, the client builds geometry from entity.custom:

| Field | Description | |---|---| | mesh | 'box' (default), 'cylinder', 'sphere' | | color | Hex color (default 0xff8800) | | sx, sy, sz | Box dimensions | | r | Radius for sphere/cylinder | | h | Height for cylinder | | spin | Y-axis rotation speed (radians/sec) | | hover | Vertical bob amplitude | | light | PointLight color | | lightIntensity, lightRange | PointLight params | | emissive, emissiveIntensity | Material emissive |

EventBus Channels

Apps communicate via ctx.bus:

// Publisher
ctx.bus.emit('combat.fire', { shooterId, origin, direction })

// Subscriber (supports wildcard)
ctx.bus.on('combat.*', (event) => {
  // event.channel, event.data, event.meta.sourceEntity, event.meta.timestamp
})

Scoped subscriptions auto-cleanup on entity destroy/hot reload.

Dependencies

• jolt-physics - WASM physics engine
• ws - WebSocket server
• webjsx - JSX-like DOM diffing for client UI
• d3-octree - Spatial indexing

License

MIT