@lagless/create 0.0.38 → 0.0.39

package/templates/pixi-react/docs/03-determinism.md

@@ -0,0 +1,204 @@
+# Determinism — THE MOST CRITICAL DOCUMENT
+
+## Why Determinism Matters
+
+Lagless uses **deterministic lockstep with rollback**. Every client runs the same simulation independently. If any client produces a different result from the same inputs, the simulations **permanently diverge** — players see different game states and the game is unplayable. There is no automatic recovery without a full state reset.
+
+## The Golden Rule
+
+**Same inputs + same initial state + same PRNG seed = byte-identical simulation state on every client, every platform, every time.**
+
+## ALWAYS Do These
+
+### Use MathOps for Trigonometry and Square Root
+
+```typescript
+import { MathOps } from '@lagless/math';
+
+// CORRECT — WASM-backed, identical on all platforms
+const s = MathOps.sin(angle);
+const c = MathOps.cos(angle);
+const a = MathOps.atan2(dy, dx);
+const d = MathOps.sqrt(dx * dx + dy * dy);
+const v = MathOps.clamp(value, min, max);
+```
+
+### Use PRNG for Randomness
+
+```typescript
+// CORRECT — deterministic, state stored in ArrayBuffer
+const random = this._prng.getFloat();           // [0, 1)
+const roll = this._prng.getRandomInt(1, 7);     // [1, 7) = 1-6
+```
+
+### Set prevPosition on Entity Spawn
+
+```typescript
+// CORRECT — prevents one-frame interpolation jump from (0,0)
+this._transform.set(entity, {
+  positionX: spawnX,
+  positionY: spawnY,
+  prevPositionX: spawnX,
+  prevPositionY: spawnY,
+});
+```
+
+### Initialize MathOps Before Simulation
+
+```typescript
+// In app startup (main.tsx or runner-provider.tsx):
+await MathOps.init();
+```
+
+## NEVER Do These in Simulation Code
+
+### Platform-Dependent Math
+
+```typescript
+// WRONG — results differ between browsers/platforms
+Math.sin(x);     // Use MathOps.sin(x)
+Math.cos(x);     // Use MathOps.cos(x)
+Math.tan(x);     // Use MathOps.tan(x)
+Math.atan2(y,x); // Use MathOps.atan2(y, x)
+Math.sqrt(x);    // Use MathOps.sqrt(x)
+Math.pow(x, y);  // Use MathOps.pow(x, y) or x ** y for integer powers
+Math.log(x);     // Use MathOps.log(x)
+Math.exp(x);     // Use MathOps.exp(x)
+```
+
+### Non-Deterministic Sources
+
+```typescript
+// WRONG — different on every client
+Math.random();           // Use PRNG.getFloat()
+Date.now();              // Use tick number instead
+performance.now();       // Use tick number instead
+new Date();              // Use tick number instead
+crypto.getRandomValues(); // Use PRNG
+```
+
+### Unstable Iteration
+
+```typescript
+// WRONG — sort is not stable without comparator, may differ between engines
+array.sort();
+// CORRECT
+array.sort((a, b) => a - b);
+
+// WRONG — key order is not guaranteed
+for (const key in obj) { ... }
+// CORRECT — use arrays or Maps with deterministic insertion order
+
+// CAUTION — Map/Set iteration order depends on insertion order
+// Only safe if insertions happen in deterministic order (e.g., by entity ID)
+```
+
+## SAFE Math Functions
+
+These JavaScript Math functions are **safe** — they produce identical results on all platforms because they operate on exact integer or bit-level operations:
+
+```typescript
+Math.abs(x)      // absolute value
+Math.min(a, b)   // minimum
+Math.max(a, b)   // maximum
+Math.floor(x)    // round down
+Math.ceil(x)     // round up
+Math.round(x)    // round to nearest
+Math.trunc(x)    // truncate decimal
+Math.sign(x)     // sign (-1, 0, 1)
+Math.fround(x)   // round to float32
+Math.hypot(a, b) // safe — but prefer MathOps.sqrt(a*a + b*b) for consistency
+```
+
+## NaN Propagation — Silent Killer
+
+NaN is the most dangerous desync source because it propagates silently through all operations:
+
+```
+NaN + 5 = NaN
+MathOps.clamp(NaN, 0, 1) = NaN     // clamp does NOT fix NaN!
+MathOps.sin(NaN) = NaN
+Rapier body.setTranslation({x: NaN, y: NaN}) → corrupted physics state
+```
+
+**The chain:** Malicious/buggy RPC → `NaN` in field → `MathOps.clamp(NaN, -1, 1)` → still `NaN` → entity position → physics engine → **permanent divergence across all clients**
+
+**The fix:** Always check `Number.isFinite()` BEFORE any math:
+
+```typescript
+const finite = (v: number): number => Number.isFinite(v) ? v : 0;
+
+// In system:
+let dirX = finite(rpc.data.directionX);  // NaN → 0, Infinity → 0
+dirX = MathOps.clamp(dirX, -1, 1);       // Now safe to clamp
+```
+
+## Float32 Precision
+
+The framework stores most values as `float32`. TypedArray access automatically truncates `float64` → `float32`. Do NOT manually cast with `Math.fround()` — the framework handles it.
+
+However, **intermediate calculations** in JavaScript are always `float64`. This is fine as long as you write results back through typed arrays (which truncate) and don't compare intermediate float64 values across clients.
+
+## Debugging Divergence
+
+### Step 1: Detect
+
+Open the F3 debug panel → hash verification table. Red entries = divergence detected at that tick.
+
+### Step 2: Reproduce
+
+Use dev-player (`pnpm dev:player`) with 2+ instances. Perform the same actions. Watch for hash mismatch.
+
+### Step 3: Narrow Down
+
+Binary search by adding temporary hash checks between systems:
+
+```typescript
+// In systems/index.ts — temporarily split execution to find diverging system
+export const systems = [
+  SavePrevTransformSystem,
+  PlayerConnectionSystem,     // check hash after this
+  ApplyMoveInputSystem,       // check hash after this
+  IntegrateSystem,            // check hash after this — if diverges here, problem is in IntegrateSystem
+  // ...
+];
+```
+
+### Step 4: Common Causes
+
+1. **`Math.sin/cos` instead of `MathOps.sin/cos`** — most common
+2. **Missing `prevPosition` initialization** — causes one-frame desync on spawn
+3. **`Math.random()` in simulation code** — each client gets different values
+4. **Unsorted array iteration** — `Array.sort()` without comparator
+5. **NaN from unsanitized RPC data** — corrupts physics state
+6. **Reading `Date.now()` or `performance.now()`** — differs per client
+
+## Determinism Code Review Checklist
+
+Before merging any simulation code:
+
+- [ ] No `Math.sin/cos/tan/atan2/sqrt/pow/log/exp` — all use `MathOps.*`
+- [ ] No `Math.random()` — uses `PRNG`
+- [ ] No `Date.now()`, `performance.now()`, `new Date()` — uses tick number
+- [ ] All `Array.sort()` calls have explicit comparator
+- [ ] All RPC fields validated with `Number.isFinite()` before use
+- [ ] All spawned entities have `prevPosition = position`
+- [ ] No `for...in` loops on objects with variable key order
+- [ ] No external state (DOM, global variables, closures over non-deterministic data)
+- [ ] PRNG calls are in deterministic order (same code path every tick)
+
+## Testing Determinism
+
+The simplest test: run the same inputs twice and compare final state hashes.
+
+```typescript
+// Run simulation with recorded inputs
+const hash1 = computeStateHash(simulation1.mem.buffer);
+
+// Reset, run same inputs again
+const hash2 = computeStateHash(simulation2.mem.buffer);
+
+assert(hash1 === hash2, 'Simulation is not deterministic!');
+```
+
+The framework's hash verification system does this automatically in multiplayer — each client reports state hashes and they're compared. Use the F3 debug panel to monitor.

package/templates/pixi-react/docs/04-input-system.md

@@ -0,0 +1,255 @@
+# Input System
+
+## Architecture Overview
+
+```
+Client UI → drainInputs() → addRPC() → RPCHistory → WebSocket → Server
+Server → relay to all clients → TickInputFanout → RPCHistory
+System → collectTickRPCs(tick, InputClass) → process RPCs
+```
+
+1. **Client sends inputs** via `drainInputs` callback (called every frame)
+2. **RPCs are scheduled** at `currentTick + inputDelay` ticks ahead
+3. **Server relays** inputs to all connected clients
+4. **Systems read RPCs** via `collectTickRPCs(tick, InputClass)` during simulation
+5. **Rollback** occurs when remote inputs arrive for already-simulated ticks
+
+## Client Side: drainInputs
+
+The `drainInputs` callback is passed to the ECSRunner and called every frame. It receives the current tick and an `addRPC` function.
+
+```typescript
+// In runner-provider.tsx:
+<RunnerProvider
+  drainInputs={(tick, addRPC) => {
+    // Read keyboard/joystick state
+    const keys = getActiveKeys();
+    let dirX = 0, dirY = 0;
+    if (keys.has('ArrowLeft') || keys.has('a')) dirX -= 1;
+    if (keys.has('ArrowRight') || keys.has('d')) dirX += 1;
+    if (keys.has('ArrowUp') || keys.has('w')) dirY -= 1;
+    if (keys.has('ArrowDown') || keys.has('s')) dirY += 1;
+
+    // Send input RPC
+    addRPC(MoveInput, { directionX: dirX, directionY: dirY });
+  }}
+/>
+```
+
+### When to Send RPCs
+
+- **Every frame** for continuous inputs (movement) — even if direction is (0,0)
+- **On action** for discrete inputs (shoot, use ability) — only when triggered
+- **Batch** if multiple inputs happen same frame — each `addRPC()` creates a separate RPC
+
+### Virtual Joystick
+
+```typescript
+import { VirtualJoystickProvider, useVirtualJoystick } from '@lagless/pixi-react';
+
+// Wrap game view:
+<VirtualJoystickProvider>
+  <GameScene />
+</VirtualJoystickProvider>
+
+// In drainInputs:
+const joystick = useVirtualJoystick();
+drainInputs={(tick, addRPC) => {
+  addRPC(MoveInput, {
+    directionX: joystick.current.x,
+    directionY: joystick.current.y,
+  });
+}}
+```
+
+## System Side: Reading RPCs
+
+Systems read inputs via `AbstractInputProvider.collectTickRPCs()`:
+
+```typescript
+@ECSSystem()
+export class ApplyMoveInputSystem implements IECSSystem {
+  constructor(
+    private readonly _input: AbstractInputProvider,
+    private readonly _playerBody: PlayerBody,
+    private readonly _velocity: Velocity2d,
+    private readonly _filter: PlayerFilter,
+  ) {}
+
+  update(tick: number): void {
+    const rpcs = this._input.collectTickRPCs(tick, MoveInput);
+    for (const rpc of rpcs) {
+      // rpc.meta — metadata
+      const slot = rpc.meta.playerSlot;    // which player sent this
+      const seq = rpc.meta.seq;            // sequence number
+
+      // rpc.data — the input fields defined in YAML
+      const dirX = rpc.data.directionX;
+      const dirY = rpc.data.directionY;
+
+      // Find and update the player's entity
+      for (const entity of this._filter) {
+        if (this._playerBody.unsafe.playerSlot[entity] !== slot) continue;
+        this._velocity.unsafe.velocityX[entity] = dirX * speed;
+        this._velocity.unsafe.velocityY[entity] = dirY * speed;
+        break;
+      }
+    }
+  }
+}
+```
+
+### RPC Ordering
+
+RPCs are deterministically ordered by `(playerSlot, ordinal, seq)`. This means:
+- Same RPCs produce the same order regardless of network arrival order
+- Multiple RPCs per tick from the same player are ordered by sequence number
+- Different input types from the same player use ordinal for stable ordering
+
+## Input Sanitization
+
+**All RPC data must be treated as potentially malicious.** The binary layer validates message structure but NOT field values — NaN, Infinity, and out-of-range numbers pass through.
+
+```typescript
+// Helper: returns 0 for NaN/Infinity, value otherwise
+const finite = (v: number): number => Number.isFinite(v) ? v : 0;
+
+// In system:
+update(tick: number): void {
+  const rpcs = this._input.collectTickRPCs(tick, MoveInput);
+  for (const rpc of rpcs) {
+    // Step 1: Reject non-finite values
+    let dirX = finite(rpc.data.directionX);
+    let dirY = finite(rpc.data.directionY);
+
+    // Step 2: Clamp to valid range
+    dirX = MathOps.clamp(dirX, -1, 1);
+    dirY = MathOps.clamp(dirY, -1, 1);
+
+    // Now safe to use dirX, dirY
+  }
+}
+```
+
+### Why This Order Matters
+
+```typescript
+// WRONG — NaN passes through clamp
+MathOps.clamp(NaN, -1, 1)  // → NaN (NOT -1 or 0!)
+
+// CORRECT — check finite first
+finite(NaN)                  // → 0
+MathOps.clamp(0, -1, 1)     // → 0 ✓
+```
+
+### What to Validate
+
+| Field Type | Validation |
+|-----------|-----------|
+| Direction vector (float32) | `finite()` → `clamp(-1, 1)` per component |
+| Angle (float32) | `finite()` — any finite value valid for trig |
+| Speed/power (float32) | `finite()` → `clamp(0, maxSpeed)` |
+| Boolean (uint8) | Treat as `!= 0` — auto-masked to 0-255 by framework |
+| Entity ID (uint32) | Verify entity exists before using |
+
+## Server Events
+
+Server events are RPCs emitted by the server (not by players). They represent authoritative game events.
+
+### Emitting from Server Hooks
+
+```typescript
+// In game-hooks.ts:
+const hooks: RoomHooks = {
+  onPlayerJoin: (ctx, player) => {
+    ctx.emitServerEvent(PlayerJoined, {
+      slot: player.slot,
+      playerId: player.id,
+    });
+  },
+  onPlayerLeave: (ctx, player, reason) => {
+    ctx.emitServerEvent(PlayerLeft, {
+      slot: player.slot,
+      reason,
+    });
+  },
+};
+```
+
+### Reading Server Events in Systems
+
+Server events are read the same way as player RPCs:
+
+```typescript
+const rpcs = this._input.collectTickRPCs(tick, PlayerJoined);
+for (const rpc of rpcs) {
+  const slot = rpc.data.slot;
+  // Create entity for new player...
+}
+```
+
+The key difference: server events have `rpc.meta.playerSlot === SERVER_SLOT` (255).
+
+## Adding a New Input Type
+
+1. **Schema** — Add to `ecs.yaml`:
+   ```yaml
+   inputs:
+     ShootInput:
+       targetX: float32
+       targetY: float32
+       power: float32
+   ```
+
+2. **Codegen** — Run `pnpm codegen`
+
+3. **Send from client** — In `drainInputs`:
+   ```typescript
+   if (shootButtonPressed) {
+     addRPC(ShootInput, { targetX: mouseX, targetY: mouseY, power: 1.0 });
+   }
+   ```
+
+4. **Read in system** — Create or update a system:
+   ```typescript
+   const rpcs = this._input.collectTickRPCs(tick, ShootInput);
+   for (const rpc of rpcs) {
+     let targetX = finite(rpc.data.targetX);
+     let targetY = finite(rpc.data.targetY);
+     let power = MathOps.clamp(finite(rpc.data.power), 0, 1);
+     // Create projectile entity...
+   }
+   ```
+
+## Input Delay
+
+Local inputs are scheduled at `currentTick + inputDelay` ticks ahead. This gives RPCs time to reach the server and be relayed to other clients before that tick is simulated.
+
+- **Higher input delay** → fewer rollbacks, more latency feel
+- **Lower input delay** → more responsive, more rollbacks on high latency
+- **Default:** adaptive, managed by `InputDelayController`
+
+The input delay is automatically adjusted based on network conditions. You generally don't need to configure it.
+
+## Hash Reporting
+
+Hash reporting sends periodic state hashes to the server for divergence detection.
+
+```typescript
+// In runner-provider.tsx:
+import { createHashReporter } from '@lagless/core';
+
+// After runner creation:
+const hashReporter = createHashReporter(runner, {
+  inputProvider: runner.InputProviderInstance,
+  ReportHashInput: ReportHash,
+});
+
+// In drainInputs:
+drainInputs={(tick, addRPC) => {
+  hashReporter.drain(tick, addRPC);  // Report hashes for verified ticks
+  // ... other inputs
+}}
+```
+
+The `HashVerificationSystem` on the simulation side compares reported hashes and emits `DivergenceSignal` on mismatch.

package/templates/pixi-react/docs/05-signals.md

@@ -0,0 +1,175 @@
+# Signals — Rollback-Aware Events
+
+## Overview
+
+Signals are the bridge between deterministic simulation and non-deterministic view layer. They handle the complexity of rollback by providing three event streams:
+
+- **Predicted** — fired immediately when the signal is emitted (may be rolled back later)
+- **Verified** — fired when the signal survives all rollbacks (guaranteed permanent)
+- **Cancelled** — fired when a previously predicted signal is rolled back (undo)
+
+## Why Three Streams?
+
+In a rollback-based multiplayer game:
+1. Player shoots → system emits signal → **Predicted**: play gunshot sound
+2. Network delivers remote player's dodge input → rollback to before the shot
+3. Re-simulation: shot never happened → **Cancelled**: stop gunshot sound
+4. OR: re-simulation confirms the shot → **Verified**: add score, show hit marker
+
+## Defining a Signal
+
+Signals are classes decorated with `@ECSSignal()` that extend `Signal<TData>`:
+
+```typescript
+// In signals/index.ts:
+import { ECSSignal, Signal } from '@lagless/core';
+
+@ECSSignal()
+export class ScoreSignal extends Signal<{ slot: number; points: number }> {}
+
+@ECSSignal()
+export class DeathSignal extends Signal<{ entityId: number; killerSlot: number }> {}
+
+@ECSSignal()
+export class ExplosionSignal extends Signal<{ x: number; y: number; radius: number }> {}
+```
+
+The generic type `TData` defines the event payload. It must be a plain object with primitive values (for shallow comparison during rollback verification).
+
+## Emitting Signals in Systems
+
+```typescript
+@ECSSystem()
+export class CombatSystem implements IECSSystem {
+  constructor(
+    private readonly _scoreSignal: ScoreSignal,
+    private readonly _deathSignal: DeathSignal,
+  ) {}
+
+  update(tick: number): void {
+    // When something happens:
+    if (playerDied) {
+      this._deathSignal.emit(tick, { entityId: entity, killerSlot: killerSlot });
+      this._scoreSignal.emit(tick, { slot: killerSlot, points: 100 });
+    }
+  }
+}
+```
+
+**Key:** `emit(tick, data)` — the tick is used for rollback tracking.
+
+## Subscribing in View Layer
+
+```typescript
+// In a React component or game-view setup:
+useEffect(() => {
+  const sub1 = scoreSignal.Predicted.subscribe(event => {
+    // Instant feedback — may be rolled back
+    showFloatingText(`+${event.data.points}`);
+  });
+
+  const sub2 = scoreSignal.Verified.subscribe(event => {
+    // Permanent — survived all rollbacks
+    updateScoreboard(event.data.slot, event.data.points);
+  });
+
+  const sub3 = scoreSignal.Cancelled.subscribe(event => {
+    // Undo the prediction
+    removeFloatingText();
+  });
+
+  return () => {
+    sub1.unsubscribe();
+    sub2.unsubscribe();
+    sub3.unsubscribe();
+  };
+}, []);
+```
+
+## Verification Mechanism
+
+Signals are verified via `verifiedTick` — the latest tick guaranteed to never be rolled back.
+
+| Input Provider | verifiedTick | Meaning |
+|---------------|-------------|---------|
+| `LocalInputProvider` | `= simulation.tick` | Immediate — no rollback possible in single-player |
+| `ReplayInputProvider` | `= simulation.tick` | Immediate — replaying recorded inputs |
+| `RelayInputProvider` | `= max(serverTick) - 1` | Server-confirmed, hard guarantee |
+
+Each tick, `SignalsRegistry.onTick(verifiedTick)` processes:
+1. All ticks from `_lastVerifiedTick + 1` to `verifiedTick`
+2. Compares `_awaitingVerification` (predicted) against `_pending` (actual after re-simulation)
+3. Matching signals → **Verified** stream
+4. Missing signals (were predicted but not re-emitted) → **Cancelled** stream
+
+## Use Case Guide
+
+| Scenario | Predicted | Verified | Cancelled |
+|----------|----------|---------|-----------|
+| Sound effects | Play sound | — | Stop/fade sound |
+| Score display | Show floating +100 | Update scoreboard | Remove floating text |
+| Particle effects | Spawn particles | — | Fade particles early |
+| Death/respawn | Play death animation | Remove entity from UI | Reverse death animation |
+| Chat/notifications | — | Show message | — |
+| Achievement | — | Award achievement | — |
+
+**Rule of thumb:**
+- Use **Predicted** for immediate sensory feedback (sounds, particles, animations)
+- Use **Verified** for permanent game state changes (score, achievements, chat)
+- Use **Cancelled** to undo Predicted effects when rollback happens
+
+## Signal Registration
+
+Signals must be registered in the arena config alongside systems:
+
+```typescript
+// In arena.ts:
+import { ScoreSignal, DeathSignal } from './signals/index.js';
+
+export const arenaConfig = {
+  // ...
+  signals: [ScoreSignal, DeathSignal],
+};
+```
+
+## Deduplication
+
+Signals use shallow object comparison (`_dataEquals`) for deduplication. If the same signal with identical data is emitted at the same tick across prediction and re-simulation, it's treated as the same event (Verified, not double-emitted).
+
+This means signal data should contain only primitive values, not references. Object identity is compared field-by-field.
+
+## Common Patterns
+
+### Sound Effect with Rollback Protection
+
+```typescript
+// Predicted: play sound immediately
+explosionSignal.Predicted.subscribe(e => {
+  const sound = playExplosionSound(e.data.x, e.data.y);
+  pendingSounds.set(e.tick, sound);
+});
+
+// Cancelled: stop sound if rolled back
+explosionSignal.Cancelled.subscribe(e => {
+  const sound = pendingSounds.get(e.tick);
+  if (sound) sound.stop();
+  pendingSounds.delete(e.tick);
+});
+
+// Verified: cleanup tracking (sound already playing)
+explosionSignal.Verified.subscribe(e => {
+  pendingSounds.delete(e.tick);
+});
+```
+
+### Score with Verified-Only Update
+
+```typescript
+// Only update scoreboard on verified events
+scoreSignal.Verified.subscribe(e => {
+  setScores(prev => ({
+    ...prev,
+    [e.data.slot]: (prev[e.data.slot] ?? 0) + e.data.points,
+  }));
+});
+```