spoint 0.1.0 → 0.1.11

package/README.md

@@ -1,250 +1,175 @@
-# Spawnpoint SDK - Multiplayer Physics + Netcode
+# Spawnpoint
 
-Production-ready SDK for building multiplayer physics-based games and simulations with 128 TPS fixed timestep, hot-reload support, and display-engine agnostic architecture.
-
-## WAVE 5: PRODUCTION READY ✓
-
-**Status: All systems verified and operational**
-- Server startup: ~1.8 seconds
-- Tick rate: 128 TPS (7.8125ms per tick)
-- Network snapshots: 70% compression via msgpackr
-- All 6 apps coexist: environment, interactive-door, patrol-npc, physics-crate, tps-game, world
-- TPS game: 38 validated spawn points via raycasting
-- Code quality: All files < 200 lines, zero duplication
-- Stability: Zero crashes in 30+ second test, zero memory leaks
-- Hot reload: Working without player disconnections
-- Live entity management: Spawn/remove working during gameplay
+Multiplayer game server SDK. 128 TPS authoritative server, Jolt Physics WASM, WebSocket transport, hot reload.
 
 ## Quick Start
-
+ 
 ```bash
-# Install dependencies
 npm install
-
-# Start server (port 8080)
 node server.js
+# http://localhost:8080
+```
 
-# In another terminal: Run client test
-node wave5-test.mjs
+## Architecture
 
-# Expected output:
-# [tps-game] 38 spawn points validated
-# [server] http://localhost:8080 @ 128 TPS
-# Client connects and receives continuous snapshots
+```
+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
 ```
 
-## Architecture
+## World Config
 
-**Server-Side (Physics + Netcode)**
-- Jolt Physics WASM for real rigid body simulation
-- 128 TPS fixed timestep via setImmediate loop
-- Binary msgpackr protocol over WebSocket
-- Automatic lag compensation and prediction
-- Hot reload support without disconnections
-
-**Client-Side (Display-Engine Agnostic)**
-- Receives position/rotation/velocity snapshots
-- Client-side input prediction
-- Server reconciliation blending
-- Display engine agnostic (works with THREE.js, Babylon, PlayCanvas, etc.)
-
-**Apps System**
-- Single-file app format: `server` + `client` object
-- Dynamic entity spawning and removal
-- App hot-reload with state persistence
-- Context API for physics, world, players, events
-
-## File Structure (30 files, all under 200 lines)
-
-**Production Apps**
-- `apps/world/index.js` - World definition and spawn configuration
-- `apps/environment/index.js` - Static trimesh collider
-- `apps/interactive-door/index.js` - Proximity-based kinematic door
-- `apps/patrol-npc/index.js` - Waypoint-based NPC patrol
-- `apps/physics-crate/index.js` - Dynamic physics object
-- `apps/tps-game/index.js` - Full multiplayer TPS game
-
-**SDK Core (19 files)**
-- `src/physics/` - Jolt WASM integration
-- `src/netcode/` - Tick system, networking, snapshots
-- `src/client/` - Client prediction and reconciliation
-- `src/apps/` - App loader, runtime, context
-- `src/sdk/` - Server and client SDKs
-- `src/protocol/` - Message types and encoding
-
-## Performance Verified
-
-| Metric | Target | Verified |
-|--------|--------|----------|
-| Startup | < 2 sec | ~1.8s ✓ |
-| First snapshot | < 1000ms | < 500ms ✓ |
-| Tick rate | 124+ TPS | 124-125 TPS ✓ |
-| Memory | Stable | Stable, no leaks ✓ |
-| Network | 70% compression | msgpackr verified ✓ |
-| Max players | 5+ | 5+ tested ✓ |
-| Max entities | 50+ | 50+ tested ✓ |
-
-## Example Application
+`apps/world/index.js` exports the world definition:
+
+```javascript
+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`:
 
 ```javascript
-// apps/custom-game/index.js
 export default {
   server: {
     setup(ctx) {
-      ctx.state.score = 0
-      ctx.physics.setDynamic(true)
-      ctx.physics.addBoxCollider([1, 1, 1])
+      // Called once on spawn and on hot reload
+      // ctx.state persists across hot reloads
+      ctx.state.counter = ctx.state.counter || 0
     },
     update(ctx, dt) {
-      ctx.state.score += 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) {
-      console.log('Hit:', other.id)
+      // 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 {
-        model: ctx.entity.model,
         position: ctx.entity.position,
-        rotation: ctx.entity.rotation,
-        custom: { score: ctx.state.score }
+        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) { }
   }
 }
 ```
 
-## Dependencies
-
-- **jolt-physics** - Production physics engine
-- **msgpackr** - Binary encoding (70% smaller snapshots)
-- **ws** - WebSocket server
-
-## Code Quality
-
-- All 30 source files under 200 lines
-- Zero code duplication
-- Zero hardcoded values (all config-driven)
-- Minimal logging (important events only)
-- No test files (real integration testing only)
-- Hot reload architecture mandatory
-
-## Network Protocol
-
-**Binary Snapshot Format (msgpackr)**
-- Players: [id, px, py, pz, rx, ry, rz, rw, vx, vy, vz, onGround, health, inputSeq]
-- Entities: [id, model, px, py, pz, rx, ry, rz, rw, bodyType, custom]
-- Quantized for ~70% compression vs JSON
-- Broadcast every tick (128 per second)
-
-## Display Engine Agnostic
-
-The SDK works with any display engine:
-- **THREE.js** - `position`, `rotation` apply directly to Object3D
-- **Babylon.js** - Maps to TransformNode properties
-- **PlayCanvas** - Native compatibility
-- **Custom engine** - Receive raw position/rotation/velocity data
-
-## Creating Apps
-
-Apps are single-file modules with `server` and `client` objects:
+## 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`:
 
 ```javascript
-export default {
-  server: {
-    setup(ctx) { },        // Called once on app load
-    update(ctx, dt) { },   // Called each tick
-    teardown(ctx) { },     // Called on hot reload
-    onCollision(ctx, other) { },  // Collision event
-    onInteract(ctx, player) { },  // Proximity event
-    onMessage(ctx, msg) { }       // Custom messages
-  },
-  client: {
-    render(ctx) { }        // Return render data
-  }
-}
-```
+// Publisher
+ctx.bus.emit('combat.fire', { shooterId, origin, direction })
 
-Context (`ctx`) provides:
-- `ctx.entity` - Current entity data
-- `ctx.physics` - Physics API (gravity, colliders, forces)
-- `ctx.world` - World API (spawn, destroy, raycast)
-- `ctx.players` - Player API (list, nearest, send, broadcast)
-- `ctx.state` - Persistent app state (survives hot reload)
-- `ctx.time` - Tick, deltaTime, elapsed
-- `ctx.events` - Event emitter (emit, on, off)
-- `ctx.network` - Network API (broadcast, sendTo)
-
-## Hot Reload
-
-Apps reload without disconnecting players:
-- Edit app file → Server detects change
-- TickSystem pauses for atomic reload
-- Old app teardown, new app setup
-- World state preserved
-- Clients notified but stay connected
-- Player input continues flowing
-
-## WAVE 5 Verification Summary
-
-All systems verified production-ready:
-
-✓ Cold boot test: Server starts in ~1.8 seconds
-✓ Client connection: ws://localhost:8080/ws
-✓ Snapshots: 128 TPS continuous delivery
-✓ All 6 apps: Coexisting without conflicts
-✓ TPS game: 38 spawn points validated via raycasting
-✓ Hot reload: Working without disconnections
-✓ Entity management: Live spawn/remove working
-✓ Tick rate: 124-125 TPS verified
-✓ Zero crashes: 30+ second test completed
-✓ Memory: Stable, zero leaks
-✓ Code quality: All < 200 lines per file
-✓ Documentation: Complete in CLAUDE.md
-
-## Getting Started
-
-```bash
-# Install and start
-npm install
-node server.js
-
-# In another terminal
-node wave5-test.mjs
+// Subscriber (supports wildcard)
+ctx.bus.on('combat.*', (event) => {
+  // event.channel, event.data, event.meta.sourceEntity, event.meta.timestamp
+})
 ```
 
-Expected output:
-```
-[tps-game] 38 spawn points validated
-[server] http://localhost:8080 @ 128 TPS
-[WAVE5] Client connected to ws://localhost:8080/ws
-[WAVE5] World state received
-... snapshots streaming at 128 TPS
-```
+Scoped subscriptions auto-cleanup on entity destroy/hot reload.
 
-## Documentation
-
-Complete technical reference available in **CLAUDE.md**:
-- Architecture overview
-- Server tick system (128 TPS)
-- Physics engine (Jolt WASM)
-- Network protocol (binary msgpackr)
-- App system (single-file format)
-- Context API reference
-- Hot reload guarantees
-- Performance specifications
-
-## Status
-
-**PRODUCTION READY** ✓
-
-The Spawnpoint SDK is fully verified and ready for deployment. All systems have been tested through comprehensive cold-boot validation, end-to-end functionality testing, and 30+ second stability verification.
-
-No known issues. Zero crashes. Zero memory leaks. Stable tick rate. Complete documentation.
+## Dependencies
 
-Ready for production use.
+- `jolt-physics` - WASM physics engine
+- `ws` - WebSocket server
+- `webjsx` - JSX-like DOM diffing for client UI
+- `d3-octree` - Spatial indexing
 
 ## License
 
-GPL-3.0-only
+MIT

package/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: spoint
+description: Work with spoint - a multiplayer physics game server SDK. Scaffolds apps locally, runs engine from npm package.
+---
+
+# spoint
+
+You are helping a developer work with the spoint multiplayer game server SDK.
+
+## Setup (First Time)
+
+When no `apps/` directory exists in the current working directory, scaffold it:
+
+```bash
+bunx spoint scaffold
+bunx spoint
+```
+
+This copies the default apps (world config, tps-game, environment, etc.) into `./apps/` and starts the server. The engine (src/, client/) always comes from the npm package - never from the user's local folder.
+
+## Daily Use
+
+```bash
+bunx spoint          # start server (port 3001, 128 TPS)
+```
+
+Open http://localhost:3001 in browser. Apps hot-reload on file save.
+
+## Creating Apps
+
+```bash
+bunx spoint-create-app my-app
+bunx spoint-create-app --template physics my-physics-object
+bunx spoint-create-app --template interactive my-button
+bunx spoint-create-app --template spawner my-spawner
+```
+
+## App Structure
+
+Apps live in `apps/<name>/index.js` and export a default object:
+
+```js
+export default {
+  server: {
+    setup(ctx) {
+      ctx.entity.custom = { mesh: 'box', color: 0x00ff00 }
+      ctx.physics.setStatic(true)
+      ctx.physics.addBoxCollider([0.5, 0.5, 0.5])
+    },
+    update(ctx, dt) {},
+    teardown(ctx) {}
+  },
+  client: {
+    render(ctx) {
+      return { position: ctx.entity.position, rotation: ctx.entity.rotation, custom: ctx.entity.custom }
+    }
+  }
+}
+```
+
+## World Config
+
+Edit `apps/world/index.js` to configure port, tickRate, gravity, movement, entities, and scene. The `entities` array auto-spawns apps on start.
+
+## Key Facts
+
+- Engine files (src/, client/) come from the npm package - never edit them
+- Only `apps/` is local to the user's project (their CWD)
+- `ctx.state` survives hot reload; timers and bus subscriptions do not
+- 128 TPS server, 60Hz client input, exponential lerp interpolation
+
+## Physics
+
+```js
+// Static
+ctx.physics.setStatic(true)
+ctx.physics.addBoxCollider([halfX, halfY, halfZ])
+
+// Dynamic
+ctx.physics.setDynamic(true)
+ctx.physics.setMass(5)
+```
+
+## EventBus
+
+```js
+ctx.bus.on('combat.hit', (data) => {})
+ctx.bus.emit('combat.hit', { damage: 10 })
+// Wildcard: 'combat.*' catches all combat.* events
+```
+
+## Debugging
+
+- Server: `globalThis.__DEBUG__.server` in Node REPL
+- Client: `window.debug` in browser console (exposes scene, camera, renderer, client)