@lagless/create 0.0.38 → 0.0.39

package/templates/pixi-react/docs/06-rendering.md

@@ -0,0 +1,256 @@
+# Rendering
+
+## Architecture
+
+Rendering is **non-deterministic** and **read-only**. The view layer reads ECS state but never writes to it. Simulation runs independently of rendering.
+
+```
+Simulation (deterministic)     View Layer (non-deterministic)
+  ECS systems → ArrayBuffer ──→ FilterViews → Pixi.js sprites
+  Tick N state                   Interpolated between ticks
+```
+
+## FilterViews — Entity Lifecycle Management
+
+`FilterViews` from `@lagless/pixi-react` automatically manages Pixi.js containers for entities matching a filter. When an entity enters the filter, a view is created. When it leaves, the view is destroyed.
+
+```tsx
+import { FilterViews } from '@lagless/pixi-react';
+
+// In game scene:
+<FilterViews
+  filter={runner.Core.PlayerFilter}
+  View={PlayerView}
+/>
+```
+
+## filterView — Define Entity Views
+
+`filterView` creates a view component with lifecycle hooks:
+
+```tsx
+import { filterView } from '@lagless/pixi-react';
+
+const PlayerView = filterView(
+  // Render function — called once on entity creation
+  ({ entity, runner }, ref) => {
+    return (
+      <pixiContainer ref={ref}>
+        <pixiGraphics
+          draw={(g) => {
+            g.circle(0, 0, 20);
+            g.fill({ color: 0x4488ff });
+          }}
+        />
+      </pixiContainer>
+    );
+  },
+  {
+    // Called every render frame — update positions
+    onUpdate: ({ entity, runner }, container) => {
+      const transform = runner.Core.Transform2d;
+      const sim = runner.Simulation;
+
+      // Use interpolation for smooth rendering between ticks
+      const factor = sim.interpolationFactor;
+      const prevX = transform.unsafe.prevPositionX[entity];
+      const prevY = transform.unsafe.prevPositionY[entity];
+      const currX = transform.unsafe.positionX[entity];
+      const currY = transform.unsafe.positionY[entity];
+
+      container.position.set(
+        prevX + (currX - prevX) * factor,
+        prevY + (currY - prevY) * factor,
+      );
+    },
+  },
+);
+```
+
+### filterView Lifecycle
+
+| Hook | When | Use For |
+|------|------|---------|
+| Render function | Entity enters filter | Create sprites, set up initial state |
+| `onUpdate` | Every render frame | Update position, rotation, animation |
+| `onDestroy` | Entity leaves filter | Cleanup (optional, auto-handled) |
+
+## VisualSmoother2d — Rollback Smoothing
+
+`VisualSmoother2d` handles both simulation↔render interpolation AND rollback lag smoothing. Without it, entities teleport when a rollback changes their position.
+
+```typescript
+import { VisualSmoother2d } from '@lagless/misc';
+
+// Create one per entity (e.g., in filterView render):
+const smoother = new VisualSmoother2d();
+
+// In onUpdate:
+onUpdate: ({ entity, runner }, container) => {
+  const transform = runner.Core.Transform2d;
+  const sim = runner.Simulation;
+
+  const smoothed = smoother.update(
+    transform.unsafe.prevPositionX[entity],
+    transform.unsafe.prevPositionY[entity],
+    transform.unsafe.positionX[entity],
+    transform.unsafe.positionY[entity],
+    sim.interpolationFactor,
+    sim.clock.deltaTime,
+  );
+
+  container.position.set(smoothed.x, smoothed.y);
+}
+```
+
+### How VisualSmoother2d Works
+
+1. **Normal tick:** Interpolates between prevPosition and position using interpolationFactor
+2. **After rollback:** Detects position jump, absorbs it into an offset
+3. **Decay:** Offset decays exponentially (halfLife=200ms) — entity slides smoothly to correct position
+4. **No feedback loop:** Stores raw sim position (not smoothed) for next-frame comparison
+
+## Pixi.js Setup
+
+The template uses Pixi.js 8 with `@pixi/react` for declarative rendering.
+
+```tsx
+// In main.tsx:
+import '@abraham/reflection';
+import { extend } from '@pixi/react';
+import { Container, Graphics, Sprite, Text, Application } from 'pixi.js';
+
+extend({ Container, Graphics, Sprite, Text, Application });
+```
+
+### RunnerTicker
+
+The `RunnerTicker` component connects the simulation loop to Pixi.js's render loop:
+
+```tsx
+import { RunnerTicker } from '@lagless/pixi-react';
+
+// Inside <Application>:
+<RunnerTicker runner={runner} />
+```
+
+This calls `runner.update(deltaTime)` every frame, advancing the simulation.
+
+## Adding New Entity Visuals
+
+### Step 1: Define Component and Filter
+
+```yaml
+# ecs.yaml
+components:
+  Projectile:
+    ownerSlot: uint8
+    radius: float32
+
+filters:
+  ProjectileFilter:
+    include: [Transform2d, Projectile]
+```
+
+### Step 2: Run Codegen
+
+```bash
+pnpm codegen
+```
+
+### Step 3: Create View Component
+
+```tsx
+// game-view/projectile-view.tsx
+import { filterView } from '@lagless/pixi-react';
+import { VisualSmoother2d } from '@lagless/misc';
+
+const ProjectileView = filterView(
+  ({ entity, runner }, ref) => {
+    const smoother = new VisualSmoother2d();
+    const radius = runner.Core.Projectile.unsafe.radius[entity];
+
+    return (
+      <pixiContainer ref={ref} userData={{ smoother }}>
+        <pixiGraphics
+          draw={(g) => {
+            g.circle(0, 0, radius);
+            g.fill({ color: 0xff4444 });
+          }}
+        />
+      </pixiContainer>
+    );
+  },
+  {
+    onUpdate: ({ entity, runner }, container) => {
+      const smoother = container.userData.smoother as VisualSmoother2d;
+      const t = runner.Core.Transform2d;
+      const sim = runner.Simulation;
+
+      const pos = smoother.update(
+        t.unsafe.prevPositionX[entity], t.unsafe.prevPositionY[entity],
+        t.unsafe.positionX[entity], t.unsafe.positionY[entity],
+        sim.interpolationFactor, sim.clock.deltaTime,
+      );
+      container.position.set(pos.x, pos.y);
+    },
+  },
+);
+
+export { ProjectileView };
+```
+
+### Step 4: Add to Game Scene
+
+```tsx
+// game-view/game-scene.tsx
+<FilterViews filter={runner.Core.ProjectileFilter} View={ProjectileView} />
+```
+
+## Performance Tips
+
+- **Use unsafe arrays in `onUpdate`** — avoid `getCursor()` in render loops
+- **Minimize React re-renders** — FilterViews handles lifecycle, don't use React state for positions
+- **Batch draw calls** — use `pixiGraphics.draw()` callback, not imperative calls every frame
+- **Object pooling** — FilterViews already pools containers; entity recycling handles the rest
+- **Avoid allocations** — use `VECTOR2_BUFFER_1..10` scratch vectors in calculation-heavy render code
+
+## Screen Management
+
+The template uses React Router for screen navigation:
+
+```tsx
+// router.tsx
+<Routes>
+  <Route path="/" element={<TitleScreen />} />
+  <Route path="/game" element={<GameScreen />} />
+</Routes>
+```
+
+### Title Screen → Game Screen
+
+```tsx
+// screens/title.screen.tsx
+const navigate = useNavigate();
+const startMatch = useStartMatch(); // or useStartMultiplayerMatch
+
+const handleStart = () => {
+  startMatch();  // sets up runner, navigates to /game
+};
+```
+
+## Debug Panel
+
+The `<DebugPanel>` from `@lagless/react` shows network stats in development:
+
+```tsx
+import { DebugPanel } from '@lagless/react';
+
+<DebugPanel
+  runner={runner}
+  hashVerification={true}  // show hash table
+  // Toggle with F3 key
+/>
+```
+
+Shows: RTT, jitter, input delay, nudger offset, tick, rollback count, FPS, hash verification table, disconnect/reconnect buttons.

package/templates/pixi-react/docs/07-multiplayer.md

@@ -0,0 +1,277 @@
+# Multiplayer
+
+## Architecture
+
+Lagless uses a **relay model**: the server relays inputs between clients but does NOT run the simulation. Clients run identical deterministic simulations independently. The server is authoritative on time (tick assignment) and input acceptance, but clients are authoritative on game state.
+
+```
+Client A ──→ Server (relay) ──→ Client B
+   ↓              ↓                ↓
+Simulation    No simulation    Simulation
+   (same inputs → same state)
+```
+
+## Input Providers
+
+The input provider determines how RPCs are processed:
+
+| Provider | Use Case | Rollback | verifiedTick |
+|----------|---------|---------|-------------|
+| `LocalInputProvider` | Single-player | None | `= tick` |
+| `ReplayInputProvider` | Recorded playback | None | `= tick` |
+| `RelayInputProvider` | Multiplayer | On remote inputs | `= maxServerTick - 1` |
+
+### Single-Player Setup
+
+```typescript
+import { LocalInputProvider } from '@lagless/core';
+
+const inputProvider = new LocalInputProvider(inputRegistry);
+const runner = new MyRunner(arenaConfig, inputProvider);
+```
+
+### Multiplayer Setup
+
+```typescript
+import { RelayInputProvider } from '@lagless/relay-client';
+
+const connection = new RelayConnection({
+  serverUrl: 'ws://localhost:3333',
+  scope: 'my-game',
+});
+
+const inputProvider = new RelayInputProvider(inputRegistry, connection);
+const runner = new MyRunner(arenaConfig, inputProvider);
+
+// Connect and matchmake
+await connection.connect();
+```
+
+## RelayConnection
+
+Manages WebSocket connection to the relay server. Handles matchmaking, reconnection, and message routing.
+
+```typescript
+const connection = new RelayConnection({
+  serverUrl: 'ws://localhost:3333',  // server URL
+  scope: 'my-game',                  // matchmaking scope (game type)
+});
+
+// Connect
+await connection.connect();
+
+// Events
+connection.onMatchFound(() => { ... });
+connection.onDisconnect(() => { ... });
+
+// Disconnect
+connection.disconnect();
+```
+
+## Server Setup
+
+### RelayGameServer
+
+```typescript
+import { RelayGameServer } from '@lagless/relay-game-server';
+import { hooks } from './game-hooks.js';
+import { MyInputRegistry } from '@my-game/simulation';
+
+const server = new RelayGameServer({
+  port: 3333,
+  loggerName: 'MyGameServer',
+  roomType: {
+    name: 'my-game',
+    config: {
+      maxPlayers: 4,
+      reconnectTimeoutMs: 15_000,
+    },
+    hooks,
+    inputRegistry: MyInputRegistry,
+  },
+  matchmaking: {
+    scope: 'my-game',
+    config: {
+      minPlayersToStart: 1,
+      maxPlayers: 4,
+      waitTimeoutMs: 5_000,
+    },
+  },
+});
+
+server.start();
+```
+
+### Dev Tools Integration
+
+For development, add dev-tools for the dev-player testing tool:
+
+```typescript
+import { setupDevTools } from '@lagless/dev-tools';
+
+setupDevTools(server); // Register latency API routes
+server.start();
+```
+
+## Room Hooks
+
+Room hooks define server-side game lifecycle. The server calls these hooks at appropriate times.
+
+```typescript
+import { RoomHooks, PlayerLeaveReason } from '@lagless/relay-server';
+
+export const hooks: RoomHooks = {
+  // Room created (before any players join)
+  onRoomCreated: (ctx) => {
+    console.log('Room created:', ctx.roomId);
+  },
+
+  // Player joins the room
+  onPlayerJoin: (ctx, player) => {
+    ctx.emitServerEvent(PlayerJoined, {
+      slot: player.slot,
+      playerId: player.id,
+    });
+  },
+
+  // Player leaves (disconnect, kick, etc.)
+  onPlayerLeave: (ctx, player, reason) => {
+    ctx.emitServerEvent(PlayerLeft, {
+      slot: player.slot,
+      reason,
+    });
+  },
+
+  // Player reconnects after disconnect
+  onPlayerReconnect: (ctx, player) => {
+    ctx.emitServerEvent(PlayerJoined, {
+      slot: player.slot,
+      playerId: player.id,
+    });
+  },
+
+  // Whether to accept a late-joining player (room already started)
+  shouldAcceptLateJoin: (ctx, player) => {
+    return true; // or false to reject
+  },
+
+  // Whether to accept a reconnecting player
+  shouldAcceptReconnect: (ctx, player) => {
+    return true; // or false to reject
+  },
+
+  // Player reports finished (e.g., game over for them)
+  onPlayerFinished: (ctx, player, result) => {
+    // result is game-specific data
+  },
+
+  // Match ends (all players finished or room timeout)
+  onMatchEnd: (ctx, results) => {
+    // Persist results to database, etc.
+  },
+
+  // Room is being disposed
+  onRoomDisposed: (ctx) => {
+    console.log('Room disposed:', ctx.roomId);
+  },
+};
+```
+
+### RoomContext (ctx)
+
+The `ctx` parameter provides safe room interaction:
+
+```typescript
+ctx.emitServerEvent(InputClass, data);  // Send server-originated RPC
+ctx.getPlayers();                        // Get all player info
+ctx.endMatch(results);                   // End the match
+ctx.roomId;                              // Room identifier
+```
+
+## Server Events via emitServerEvent
+
+Server events are RPCs that originate from the server, not from players. They're used for authoritative game events.
+
+```typescript
+// In hooks:
+ctx.emitServerEvent(PlayerJoined, { slot: player.slot, playerId: player.id });
+ctx.emitServerEvent(PlayerLeft, { slot: player.slot, reason: 0 });
+
+// Custom server events:
+ctx.emitServerEvent(RoundStart, { roundNumber: 1 });
+ctx.emitServerEvent(PowerUpSpawned, { x: 100, y: 200, type: 3 });
+```
+
+Server events have `playerSlot = 255` (SERVER_SLOT) in the RPC metadata.
+
+## State Transfer (Late Join)
+
+When a player joins a room that's already running:
+
+1. Server sends `StateRequest` to all connected clients
+2. Clients export `ArrayBuffer.slice(0)` snapshot + hash + tick
+3. `StateTransfer` picks majority hash (quorum) — protects against corrupted clients
+4. Server sends chosen `StateResponse` to joining player
+5. Server sends **only** events with `tick > stateResult.tick` (events baked into state are not re-sent)
+6. Client applies state via `ECSSimulation.applyExternalState()` — replaces ArrayBuffer, resets clock + snapshots
+
+### What You Need to Do
+
+State transfer works automatically with the framework. However:
+- Ensure all game state is in the ArrayBuffer (components, singletons, player resources)
+- Don't keep simulation state in JavaScript variables or closures
+- Physics: `ColliderEntityMap` must be rebuilt after state transfer (handled by physics runner)
+
+## Reconnect
+
+When a player disconnects:
+
+1. Server tracks `PlayerConnection` as `Disconnected` with configurable timeout (`reconnectTimeoutMs`)
+2. If player reconnects before timeout: state transfer restores their simulation
+3. If timeout expires: `onPlayerLeave` is called with `TIMEOUT` reason
+4. `shouldAcceptReconnect` hook can reject reconnection
+
+### Testing Reconnect
+
+1. Open F3 debug panel in game
+2. Click "Disconnect" button
+3. Wait a few seconds
+4. Click "Reconnect" button
+5. Verify: player resumes with correct state, no permanent desync
+
+## Testing Multiplayer
+
+### Quick Test: Two Browser Tabs
+
+1. Start server: `pnpm dev:backend`
+2. Start client: `pnpm dev:frontend`
+3. Open `http://localhost:4200` in two tabs
+4. Both click "Multiplayer" → they should see each other
+
+### Dev Player Tool
+
+The dev-player opens N game instances in an iframe grid with auto-matchmaking:
+
+1. Start everything: `pnpm dev`
+2. Open `http://localhost:4210`
+3. Set instance count (2-8)
+4. Click "Start" — instances auto-matchmake with unique scope
+
+Features:
+- Per-instance stats (FPS, tick, rollbacks)
+- Hash timeline for divergence detection
+- Per-player latency sliders
+- Auto-match on load
+
+### Debug Panel (F3)
+
+Press F3 in-game to toggle the debug panel:
+- **RTT** — round-trip time to server
+- **Jitter** — RTT variance
+- **Input Delay** — ticks ahead inputs are scheduled
+- **Nudger** — clock offset correction
+- **Tick** — current simulation tick
+- **Rollbacks** — count of rollbacks
+- **FPS** — render frame rate
+- **Hash Table** — state hash comparison (red = divergence)
+- **Disconnect/Reconnect** — buttons for testing