spoint

Physics and netcode SDK for authoritative-server multiplayer games. Jolt physics, hot reload, app-based world logic, Three.js client.

Demo: https://anentrypoint.github.io/spoint/

Quick Start

npx spoint
# or
npm install && npm start
# open http://localhost:3001

Creating Apps

node ./bin/create-app.js my-app

Or manually create apps/<name>/index.js:

export default {
  server: {
    setup(ctx) {
      ctx.state.counter = ctx.state.counter || 0
    },
    update(ctx, dt) {
      ctx.state.counter += dt
    },
    onInteract(ctx, player) { },
    onCollision(ctx, other) { }
  },
  client: {
    setup(engine) { },
    render(ctx) {
      return { custom: { mesh: 'box', color: 0xff0000, sx: 1, sy: 1, sz: 1 } }
    }
  }
}

World Config (apps/world/index.js)

export default {
  port: 3001,
  tickRate: 64,
  gravity: [0, -18, 0],
  movement: { maxSpeed: 14, sprintSpeed: 24, groundAccel: 300, airAccel: 30, friction: 5, stopSpeed: 1, jumpImpulse: 5.5 },
  player: { health: 100, capsuleRadius: 0.28, capsuleHalfHeight: 0.63, modelScale: 1.323, feetOffset: 0.212 },
  scene: { skyColor: 0x54c5eb, sunColor: 0xffffff, sunIntensity: 1.5, sunPosition: [21, 50, 20] },
  camera: { fov: 70, shoulderOffset: 0.35, zoomStages: [0, 1.5, 3, 5, 8], defaultZoomIndex: 2 },
  entities: [
    { id: 'env', model: './apps/maps/mymap.glb', position: [0, 0, 0], scale: [1, 1, 1], bodyType: 'static' },
    { id: 'game', position: [0, 0, 0], app: 'tps-game' }
  ],
  playerModel: './apps/tps-game/cleetus.vrm',
  spawnPoint: [0, 2, 0]
}

Server-Side ctx API

Property	Description
ctx.state	Persistent state (survives hot reload)
ctx.entity	.id, .position, .rotation, .scale, .velocity, .custom, .destroy()
ctx.physics	.addBoxCollider(), .addSphereCollider(), .addCapsuleCollider(), .addTrimeshCollider(), .addConvexFromModel()
ctx.interactable({ prompt, radius })	Register E-key interaction
ctx.world	.spawn(id, cfg), .destroy(id), .getEntity(id), .query(filter)
ctx.players	.getAll(), .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) — wildcard * suffix supported
ctx.lagCompensator	.getPlayerStateAtTime(pid, ms) for hit detection
ctx.raycast(origin, dir, maxDist)	Physics raycast

Client Engine API

Property	Description
engine.scene	THREE.Scene
engine.camera	THREE.PerspectiveCamera
engine.renderer	THREE.WebGLRenderer or WebGPURenderer
engine.THREE	Three.js module
engine.client	Network client (PhysicsNetworkClient or LocalClient)
engine.playerId	Local player ID
engine.cam	Camera controller
engine.players	.getMesh(id), .getState(id), .getAnimator(id)

Editor (in-browser)

Press P to toggle editor mode:

• G / R / S — translate / rotate / scale gizmo
• F — focus camera on selected entity
• Del — delete selected entity
• Drag-and-drop .glb files to place models

Singleplayer Mode

Add ?singleplayer to the URL to run without a server. Loads client/singleplayer-world.json.

Architecture

server.js                         Entry point
src/sdk/server.js                 Creates subsystems
src/sdk/TickHandler.js            Per-tick: movement → physics → collisions → apps → snapshot
src/physics/World.js              Jolt physics wrapper
src/netcode/PhysicsIntegration.js CharacterVirtual per player
src/apps/AppRuntime.js            Entity system, app lifecycle
client/app.js                     Three.js renderer, VRM loading, input loop
client/LocalClient.js             Serverless drop-in for singleplayer

Load Testing

npm run bots

Env vars: BOT_COUNT, BOT_DURATION, BOT_HZ, BOT_URL

License

MIT