@lagless/create 0.0.38 → 0.0.39

package/templates/pixi-react/CLAUDE.md

@@ -2,78 +2,254 @@
 
 ## What This Is
 
-<%= projectName %> is a multiplayer browser game built with **Lagless**, a deterministic ECS framework. TypeScript, simulate/rollback netcode, all simulation state in a single ArrayBuffer.
+<%= projectName %> is a multiplayer browser game built with **Lagless** — a deterministic ECS framework with simulate/rollback netcode. All simulation state lives in a single ArrayBuffer. Server relays inputs, clients run deterministic simulation.
 
 ## Commands
 
 ```bash
-# Install
-pnpm install
-
-# Start game server (Bun)
-pnpm dev:backend
+pnpm install                # Install dependencies
+pnpm codegen                # Regenerate ECS code from schema (MUST run after schema changes)
+pnpm dev                    # Start backend + frontend + dev-player (all at once)
+pnpm dev:backend            # Game server only (Bun, auto-reload)
+pnpm dev:frontend           # Frontend only (Vite HMR)
+pnpm dev:player             # Dev-player multiplayer testing tool (port 4210)
+```
 
-# Start frontend dev server (Vite)
-pnpm dev:frontend
+## Project Structure
 
-# Regenerate ECS code after schema changes
-pnpm codegen
+```
+<%= packageName %>-simulation/       # Shared deterministic game logic
+  src/lib/schema/ecs.yaml           # ECS schema definition → run pnpm codegen
+  src/lib/code-gen/                  # GENERATED — never edit manually
+  src/lib/systems/                   # Game systems (execution order = array order)
+  src/lib/signals/                   # Rollback-aware events
+  src/lib/arena.ts                   # Arena config (systems, signals, ECS config)
+<%= packageName %>-frontend/         # React + Pixi.js game client
+  src/app/game-view/                 # Pixi rendering components
+  src/app/screens/                   # Game screens (title, game)
+  src/app/hooks/                     # React hooks (match start, inputs)
+<%= packageName %>-backend/          # Bun game server (relay model, NO simulation)
+  src/main.ts                        # Server entry point
+  src/game-hooks.ts                  # Room lifecycle hooks
 ```
 
-## Architecture
+## Quick Recipe: Adding a Feature
+
+1. **Schema** — Add components/inputs/filters to `<%= packageName %>-simulation/src/lib/schema/ecs.yaml`
+2. **Codegen** — Run `pnpm codegen`
+3. **System** — Create `my-feature.system.ts` with `@ECSSystem()` decorator
+4. **Register** — Add system to `systems` array in `systems/index.ts` (order matters!)
+5. **Render** — Add Pixi.js view component using `filterView()` or `<FilterViews>`
+6. **Input** — Wire UI events via `drainInputs` in runner-provider
+
+## ECS System Pattern
+
+```typescript
+import { ECSSystem, IECSSystem } from '@lagless/core';
+
+@ECSSystem()
+export class MySystem implements IECSSystem {
+  constructor(
+    private readonly _transform: Transform2d,      // component (unsafe typed arrays)
+    private readonly _filter: PlayerFilter,         // filter (iterable entity list)
+    private readonly _entities: EntitiesManager,    // entity CRUD
+    private readonly _prng: PRNG,                   // deterministic random
+    private readonly _config: ECSConfig,            // simulation config
+  ) {}
+
+  update(tick: number): void {
+    for (const entity of this._filter) {
+      this._transform.unsafe.positionX[entity] += 1;
+    }
+  }
+}
+```
 
-### Three Packages
+## Input Handling Pattern
+
+```typescript
+// In runner-provider.tsx — drainInputs callback:
+drainInputs={(tick, addRPC) => {
+  const dir = getDirection(); // from keyboard/joystick
+  addRPC(MoveInput, { directionX: dir.x, directionY: dir.y });
+}}
+
+// In system — reading inputs:
+const rpcs = this._input.collectTickRPCs(tick, MoveInput);
+for (const rpc of rpcs) {
+  const slot = rpc.meta.playerSlot;
+  const dirX = finite(rpc.data.directionX); // ALWAYS sanitize!
+  const dirY = finite(rpc.data.directionY);
+  // use dirX, dirY...
+}
+
+// Sanitization helper:
+const finite = (v: number): number => Number.isFinite(v) ? v : 0;
+```
 
-- **<%= packageName %>-simulation** — Shared deterministic game logic (ECS systems, components, signals)
-- **<%= packageName %>-frontend** — React + Pixi.js game client
-- **<%= packageName %>-backend** — Bun game server (relay model, no simulation)
+## Rendering Pattern
+
+```typescript
+// FilterViews — auto-manages lifecycle for entities matching a filter
+<FilterViews filter={runner.Core.PlayerFilter} View={PlayerView} />
+
+// filterView — define a view component for an entity
+const PlayerView = filterView(({ entity }, ref) => {
+  const transform = runner.Core.Transform2d;
+  // onCreate: set up sprites
+  // Return Pixi container
+  return <pixiContainer ref={ref} />;
+}, {
+  onUpdate: ({ entity }, container, runner) => {
+    container.position.set(
+      transform.unsafe.positionX[entity],
+      transform.unsafe.positionY[entity]
+    );
+  },
+});
+```
 
-### ECS Memory Model
+## Signal Pattern (Rollback-Aware Events)
 
-All state lives in one contiguous ArrayBuffer with Structure-of-Arrays layout. Snapshot = `ArrayBuffer.slice(0)`. Rollback = `Uint8Array.set()` from snapshot.
+```typescript
+// Define signal in signals/index.ts:
+@ECSSignal()
+export class ScoreSignal extends Signal<{ slot: number; points: number }> {}
 
-### Simulation Loop
+// Emit in system:
+this._scoreSignal.emit(tick, { slot: 0, points: 100 });
 
-```
-1. clock.update(dt)
-2. targetTick = floor(accTime / frameLength)
-3. checkAndRollback() — if remote inputs arrived
-4. simulationTicks: for each tick → run systems in order → process signals
-5. inputProvider.update() — drain inputs, send to server
-6. interpolationFactor = leftover / frameLength
+// Subscribe in view (three streams):
+signal.Predicted.subscribe(e => playSound());   // instant feedback
+signal.Verified.subscribe(e => updateScore());   // survived all rollbacks
+signal.Cancelled.subscribe(e => undoSound());    // was rolled back
 ```
 
-### Input System
+## DETERMINISM RULES (CRITICAL)
 
-RPCs are deterministically ordered by `(playerSlot, ordinal, seq)`. Local inputs are scheduled `currentTick + inputDelay` ticks ahead. Server relays inputs to all clients.
+**Breaking these causes permanent desync between clients — game becomes unplayable.**
 
-### Key Conventions
+**ALWAYS use:**
+- `MathOps.sin/cos/atan2/sqrt/clamp` — WASM-backed, deterministic across platforms
+- `PRNG.getFloat()/getRandomInt()` — deterministic random (state in ArrayBuffer)
+- Set `prevPositionX/Y = positionX/Y` when spawning entities (avoids interpolation jump)
 
-- **Determinism is paramount**: Same inputs + same seed = identical state on every client
-- All deterministic math must use `MathOps` (WASM-backed), never `Math.*` trig functions
-- `MathOps.init()` must be called before simulation starts
-- When spawning entities: always set `prevPositionX/Y = positionX/Y` to avoid interpolation jumps
-- `@abraham/reflection` must be imported before any decorated class
-- Generated code in `code-gen/` directories — never edit manually, regenerate from YAML
-- Systems array order = execution order (deterministic)
+**NEVER use in simulation code:**
+- `Math.sin/cos/tan/atan2/sqrt/pow/log` — platform-dependent floating point
+- `Math.random()` — non-deterministic
+- `Date.now()` or `performance.now()` — non-deterministic
+- `Array.sort()` without explicit comparator — unstable sort order
+- `for...in` on objects — non-deterministic key order
+- `Map/Set` iteration — insertion-order dependent on network timing
 
-### Schema & Codegen
+**SAFE Math functions (platform-identical):**
+`Math.abs`, `Math.min`, `Math.max`, `Math.floor`, `Math.ceil`, `Math.round`, `Math.trunc`, `Math.sign`, `Math.fround`
 
-ECS schema is defined in `<%= packageName %>-simulation/src/lib/schema/ecs.yaml`. Run `pnpm codegen` after changes.
+## Input Validation Rules
 
-Supported field types: `uint8`, `uint16`, `uint32`, `int8`, `int16`, `int32`, `float32`, `float64`, `uint8[N]` (fixed arrays).
+All RPC data from players is potentially malicious. **In every system reading RPCs:**
 
-### Adding Components/Systems
+1. `Number.isFinite(value)` FIRST — rejects NaN and Infinity
+2. `MathOps.clamp(value, min, max)` SECOND — bounds to valid range
+3. **Never** `MathOps.clamp(NaN, min, max)` — returns NaN, propagates everywhere
 
-1. Add to `ecs.yaml`, run `pnpm codegen`
-2. Create system file in `systems/` with `@ECSSystem()` decorator
-3. Add to systems array in `systems/index.ts` (order matters)
-4. Systems get dependencies via constructor injection (DI container)
+```typescript
+const finite = (v: number): number => Number.isFinite(v) ? v : 0;
+let dirX = MathOps.clamp(finite(rpc.data.directionX), -1, 1);
+```
+
+## Schema Quick Reference
+
+```yaml
+components:
+  MyComponent:
+    field: float32          # Types: uint8, uint16, uint32, int8, int16, int32, float32, float64
+    arrayField: uint8[16]   # Fixed-size array
+  TagComponent: {}          # Empty = tag (bitmask only, zero memory per entity)
+
+singletons:
+  GameState:
+    phase: uint8
 
-### Multiplayer
+playerResources:
+  PlayerResource:
+    score: uint32
+
+inputs:
+  MyInput:
+    value: float32
+
+filters:
+  MyFilter:
+    include: [Transform2d, MyComponent]
+    exclude: [Frozen]       # Optional
+```
 
-- Server never runs simulation — relay model
-- `RelayInputProvider` handles prediction + rollback
-- `RelayConnection` manages WebSocket to relay server
-- State transfer for late-join via `StateRequest`/`StateResponse`
-- `RoomHooks` in backend define game lifecycle (join, leave, reconnect)
+## Key APIs Cheat Sheet
+
+| Class | Purpose | Access |
+|-------|---------|--------|
+| `EntitiesManager` | Create/remove entities, add/remove components | DI constructor |
+| `Component.unsafe.field[entity]` | Read/write component data (hot path) | DI constructor |
+| `Component.getCursor(entity)` | Convenient single-entity access | DI constructor |
+| `Filter` | Iterate entities matching component mask | DI constructor, iterable |
+| `PRNG` | Deterministic random: `getFloat()`, `getRandomInt(from, to)` | DI constructor |
+| `ECSConfig` | `maxEntities`, `maxPlayers`, `frameLength`, `tickRate` | DI constructor |
+| `AbstractInputProvider` | `collectTickRPCs(tick, InputClass)` | DI constructor |
+| `Signal` | `emit(tick, data)` / `.Predicted/.Verified/.Cancelled.subscribe()` | DI constructor |
+| `Singleton` | Global typed fields, `singleton.field` | DI constructor |
+| `PlayerResource` | Per-player data, `playerResource.field[slot]` | DI constructor |
+<% if (simulationType === 'physics2d') { -%>
+| `PhysicsWorldManager2d` | Create/remove bodies and colliders | DI constructor |
+| `CollisionEvents2d` | Drain collision start/end events | DI constructor |
+<% } else if (simulationType === 'physics3d') { -%>
+| `PhysicsWorldManager3d` | Create/remove bodies and colliders | DI constructor |
+| `CollisionEvents3d` | Drain collision start/end events | DI constructor |
+<% } -%>
+
+## System Execution Order
+
+Systems run in array order every tick. Canonical ordering:
+
+1. `SavePrevTransformSystem` — store previous positions for interpolation
+2. `PlayerConnectionSystem` — handle join/leave server events
+3. `ApplyMoveInputSystem` — read RPCs, apply to entities
+<% if (simulationType === 'physics2d') { -%>
+4. `PhysicsStepSystem` — step Rapier 2D, sync transforms
+<% } else if (simulationType === 'physics3d') { -%>
+4. `PhysicsStepSystem` — step Rapier 3D, sync transforms
+<% } else { -%>
+4. Game logic systems (integrate, damping, boundary, etc.)
+<% } -%>
+5. `PlayerLeaveSystem` — cleanup disconnected player entities
+6. `HashVerificationSystem` — detect simulation divergence (always last)
+
+## Detailed Documentation
+
+| File | Contents |
+|------|----------|
+| [docs/01-schema-and-codegen.md](docs/01-schema-and-codegen.md) | YAML schema format, field types, codegen workflow, generated files |
+| [docs/02-ecs-systems.md](docs/02-ecs-systems.md) | Writing systems, DI tokens, entity lifecycle, prefabs, PRNG |
+| [docs/03-determinism.md](docs/03-determinism.md) | **CRITICAL** — determinism rules, pitfalls, debugging divergence |
+| [docs/04-input-system.md](docs/04-input-system.md) | RPCs, drainInputs, collectTickRPCs, sanitization, server events |
+| [docs/05-signals.md](docs/05-signals.md) | Predicted/Verified/Cancelled events, rollback behavior |
+| [docs/06-rendering.md](docs/06-rendering.md) | FilterViews, VisualSmoother, Pixi.js patterns |
+| [docs/07-multiplayer.md](docs/07-multiplayer.md) | Relay architecture, RoomHooks, state transfer, reconnect |
+<% if (simulationType === 'physics2d') { -%>
+| [docs/08-physics2d.md](docs/08-physics2d.md) | Rapier 2D integration, bodies, colliders, collision events |
+<% } else if (simulationType === 'physics3d') { -%>
+| [docs/08-physics3d.md](docs/08-physics3d.md) | Rapier 3D integration, character controller, animation |
+<% } -%>
+| [docs/09-recipes.md](docs/09-recipes.md) | Step-by-step cookbook for common game features |
+| [docs/10-common-mistakes.md](docs/10-common-mistakes.md) | "Never do X" reference + error solutions |
+| [docs/api-quick-reference.md](docs/api-quick-reference.md) | One-page API cheat sheet |
+
+## Source Reference
+
+`docs/sources/lagless/` contains a full clone of the Lagless framework repository for deep reference.
+- `libs/` — all framework library source code
+- `circle-sumo/` — complete example game (2D, gameplay focused)
+- `sync-test/` — determinism verification test bench
+- `roblox-like/` — 3D example with character controller + BabylonJS
+
+**Do NOT import from `docs/sources/`** — always use `@lagless/*` npm packages.

package/templates/pixi-react/README.md

@@ -12,18 +12,28 @@ A multiplayer game built with [Lagless](https://github.com/GbGr/lagless) — a d
 
 ```bash
 pnpm install
-
-# Terminal 1 — Start the game server
-pnpm dev:backend
-
-# Terminal 2 — Start the frontend dev server
-pnpm dev:frontend
+pnpm codegen    # Generate ECS code from schema
+pnpm dev        # Start backend + frontend + dev-player
 ```
 
 Open http://localhost:<%= frontendPort %> in your browser. Click "Play Local" for single-player or "Play Online" for multiplayer.
 
 Press **F3** to toggle the debug panel (shows network stats, tick info, hash verification).
 
+You can also run services individually:
+
+```bash
+pnpm dev:backend    # Game server (Bun, watches for changes)
+pnpm dev:frontend   # Frontend (Vite HMR)
+pnpm dev:player     # Dev-player (multiplayer testing tool, port 4210)
+```
+
+## Dev Player
+
+The **dev-player** (http://localhost:4210) is a multiplayer testing tool that opens multiple game instances in a grid. It auto-matchmakes them, displays per-instance network stats, and provides a hash timeline for detecting simulation divergence between clients.
+
+Use it to test multiplayer without opening multiple browser tabs manually.
+
 ## Project Structure
 
 ```

package/templates/pixi-react/__packageName__-backend/package.json

@@ -10,6 +10,7 @@
   "dependencies": {
     "<%= packageName %>-simulation": "workspace:*",
     "@lagless/relay-game-server": "^<%= laglessVersion %>",
+    "@lagless/dev-tools": "^<%= laglessVersion %>",
     "@lagless/misc": "^<%= laglessVersion %>",
     "reflect-metadata": "^0.2.0"
   },

package/templates/pixi-react/__packageName__-backend/src/main.ts

@@ -1,5 +1,6 @@
 import 'reflect-metadata';
 import { RelayGameServer } from '@lagless/relay-game-server';
+import { setupDevTools } from '@lagless/dev-tools';
 import { <%= projectName %>InputRegistry } from '<%= packageName %>-simulation';
 import { gameHooks } from './game-hooks.js';
 
@@ -25,4 +26,5 @@ const server = new RelayGameServer({
   },
 });
 
+setupDevTools(server);
 server.start();

package/templates/pixi-react/__packageName__-frontend/package.json

@@ -16,6 +16,14 @@
     "@lagless/net-wire": "^<%= laglessVersion %>",
     "@lagless/react": "^<%= laglessVersion %>",
     "@lagless/pixi-react": "^<%= laglessVersion %>",
+<% if (simulationType === 'physics2d') { -%>
+    "@lagless/physics2d": "^<%= laglessVersion %>",
+    "@dimforge/rapier2d-compat": "^0.14.0",
+<% } else if (simulationType === 'physics3d') { -%>
+    "@lagless/physics3d": "^<%= laglessVersion %>",
+    "@lagless/physics-shared": "^<%= laglessVersion %>",
+    "@dimforge/rapier3d-compat": "^0.14.0",
+<% } -%>
     "@abraham/reflection": "^0.12.0",
     "pixi.js": "^8.12.0",
     "@pixi/react": "^8.0.5",

package/templates/pixi-react/__packageName__-frontend/src/app/game-view/grid-background.tsx

@@ -10,7 +10,11 @@ export const GridBackground: FC = () => {
     if (!g) return;
 
     const w = <%= projectName %>Arena.width;
+<% if (simulationType === 'physics3d') { -%>
+    const h = <%= projectName %>Arena.depth;
+<% } else { -%>
     const h = <%= projectName %>Arena.height;
+<% } -%>
     const step = 100;
 
     g.clear();

package/templates/pixi-react/__packageName__-frontend/src/app/game-view/player-view.tsx

@@ -1,3 +1,70 @@
+<% if (simulationType === 'physics3d') { -%>
+import { useImperativeHandle, useRef } from 'react';
+import { Container, Graphics } from 'pixi.js';
+import { filterView, FilterViewRef } from '@lagless/pixi-react';
+import { useRunner } from './runner-provider';
+import { PlayerBody, <%= projectName %>Arena, Transform3d } from '<%= packageName %>-simulation';
+import { VisualSmoother2d } from '@lagless/misc';
+
+const PLAYER_COLORS = [0xff4444, 0x4488ff, 0x44ff44, 0xffff44];
+
+// Top-down rendering: 3D positionX → screen X, positionZ → screen Y
+const SCALE = 20; // pixels per world unit
+const OFFSET_X = 400;
+const OFFSET_Y = 300;
+
+export const PlayerView = filterView(({ entity }, ref) => {
+  const runner = useRunner();
+  const containerRef = useRef<Container>(null);
+  const graphicsRef = useRef<Graphics>(null);
+  const smootherRef = useRef<VisualSmoother2d>(new VisualSmoother2d());
+
+  const transform3d = runner.DIContainer.resolve(Transform3d);
+  const playerBody = runner.DIContainer.resolve(PlayerBody);
+
+  useImperativeHandle(ref, (): FilterViewRef => ({
+    onCreate() {
+      const g = graphicsRef.current;
+      if (!g) return;
+      const slot = playerBody.unsafe.playerSlot[entity];
+      const radius = playerBody.unsafe.radius[entity] * SCALE;
+      const color = PLAYER_COLORS[slot % PLAYER_COLORS.length];
+      g.clear();
+      g.circle(0, 0, radius);
+      g.fill(color);
+      g.circle(0, 0, radius);
+      g.stroke({ color: 0xffffff, width: 2, alpha: 0.3 });
+    },
+    onUpdate() {
+      const container = containerRef.current;
+      if (!container) return;
+      const smoother = smootherRef.current;
+      const factor = runner.Simulation.interpolationFactor;
+
+      // Map 3D (X, Z) to 2D screen space (top-down view)
+      smoother.update(
+        transform3d.unsafe.prevPositionX[entity] * SCALE + OFFSET_X,
+        transform3d.unsafe.prevPositionZ[entity] * SCALE + OFFSET_Y,
+        transform3d.unsafe.positionX[entity] * SCALE + OFFSET_X,
+        transform3d.unsafe.positionZ[entity] * SCALE + OFFSET_Y,
+        factor,
+      );
+
+      container.x = smoother.x;
+      container.y = smoother.y;
+    },
+    onDestroy() {
+      // cleanup
+    },
+  }));
+
+  return (
+    <pixiContainer ref={containerRef}>
+      <pixiGraphics ref={graphicsRef} />
+    </pixiContainer>
+  );
+});
+<% } else { -%>
 import { useImperativeHandle, useRef } from 'react';
 import { Container, Graphics } from 'pixi.js';
 import { filterView, FilterViewRef } from '@lagless/pixi-react';
@@ -57,3 +124,4 @@ export const PlayerView = filterView(({ entity }, ref) => {
     </pixiContainer>
   );
 });
+<% } -%>

package/templates/pixi-react/__packageName__-frontend/src/app/game-view/runner-provider.tsx

@@ -7,6 +7,11 @@ import {
   PlayerJoined,
   ReportHash,
   <%= projectName %>Arena,
+<% if (simulationType !== 'raw') { -%>
+  PhysicsRefs,
+  PhysicsRefsFilter,
+  PlayerFilter,
+<% } -%>
 } from '<%= packageName %>-simulation';
 import { createContext, FC, ReactNode, useContext, useEffect, useState } from 'react';
 import { useTick } from '@pixi/react';
@@ -16,6 +21,12 @@ import { ECSConfig, LocalInputProvider, RPC, createHashReporter } from '@lagless
 import { RelayInputProvider, RelayConnection } from '@lagless/relay-client';
 import { getMatchInfo } from '../hooks/use-start-multiplayer-match';
 import { UUID } from '@lagless/misc';
+import { useDevBridge } from '@lagless/react';
+<% if (simulationType === 'physics2d') { -%>
+import { PhysicsWorldManager2d, type RapierModule2d } from '@lagless/physics2d';
+<% } else if (simulationType === 'physics3d') { -%>
+import { PhysicsWorldManager3d, type RapierModule3d } from '@lagless/physics3d';
+<% } -%>
 
 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
 const RunnerContext = createContext<<%= projectName %>Runner>(null!);
@@ -66,6 +77,23 @@ export const RunnerProvider: FC<RunnerProviderProps> = ({ children }) => {
         return;
       }
 
+<% if (simulationType === 'physics2d') { -%>
+      // Load Rapier 2D WASM
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const RAPIER = (await import('@dimforge/rapier2d-compat')).default as any;
+      await RAPIER.init();
+      const rapier = RAPIER as unknown as RapierModule2d;
+      if (disposed) { inputProvider.dispose(); return; }
+
+<% } else if (simulationType === 'physics3d') { -%>
+      // Load Rapier 3D WASM
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const RAPIER = (await import('@dimforge/rapier3d-compat')).default as any;
+      await RAPIER.init();
+      const rapier = RAPIER as unknown as RapierModule3d;
+      if (disposed) { inputProvider.dispose(); return; }
+
+<% } -%>
       if (inputProvider instanceof RelayInputProvider) {
         const matchInfo = getMatchInfo(inputProvider);
         if (matchInfo) {
@@ -94,14 +122,40 @@ export const RunnerProvider: FC<RunnerProviderProps> = ({ children }) => {
           if (disposed) { inputProvider.dispose(); return; }
 
           const seededConfig = new ECSConfig({ ...inputProvider.ecsConfig, seed: serverHello.seed });
+<% if (simulationType === 'raw') { -%>
           _runner = new <%= projectName %>Runner(seededConfig, inputProvider, <%= projectName %>Systems, <%= projectName %>Signals);
+<% } else { -%>
+          _runner = new <%= projectName %>Runner(seededConfig, inputProvider, <%= projectName %>Systems, <%= projectName %>Signals, rapier);
+<% } -%>
         } else {
+<% if (simulationType === 'raw') { -%>
           _runner = new <%= projectName %>Runner(inputProvider.ecsConfig, inputProvider, <%= projectName %>Systems, <%= projectName %>Signals);
+<% } else { -%>
+          _runner = new <%= projectName %>Runner(inputProvider.ecsConfig, inputProvider, <%= projectName %>Systems, <%= projectName %>Signals, rapier);
+<% } -%>
         }
       } else {
+<% if (simulationType === 'raw') { -%>
         _runner = new <%= projectName %>Runner(inputProvider.ecsConfig, inputProvider, <%= projectName %>Systems, <%= projectName %>Signals);
+<% } else { -%>
+        _runner = new <%= projectName %>Runner(inputProvider.ecsConfig, inputProvider, <%= projectName %>Systems, <%= projectName %>Signals, rapier);
+<% } -%>
       }
 
+<% if (simulationType !== 'raw') { -%>
+      // Hook state transfer to rebuild ColliderEntityMap after receiving external state
+      const worldManager = _runner.PhysicsWorldManager;
+      _runner.Simulation.addStateTransferHandler(() => {
+        worldManager.colliderEntityMap.clear();
+        const physicsFilter = _runner.DIContainer.resolve(PhysicsRefsFilter);
+        const refs = _runner.DIContainer.resolve(PhysicsRefs);
+        const refsUnsafe = refs.unsafe;
+        for (const e of physicsFilter) {
+          worldManager.registerCollider(refsUnsafe.colliderHandle[e], e);
+        }
+      });
+
+<% } -%>
       // Set up keyboard input drainer with hash reporting
       const reportHash = createHashReporter(_runner, {
         reportInterval: <%= projectName %>Arena.hashReportInterval,
@@ -127,6 +181,7 @@ export const RunnerProvider: FC<RunnerProviderProps> = ({ children }) => {
         reportHash(addRPC);
       });
 
+      _runner.Simulation.enableHashTracking(<%= projectName %>Arena.hashReportInterval);
       _runner.start();
 
       if (inputProvider instanceof RelayInputProvider) {
@@ -167,6 +222,8 @@ export const RunnerProvider: FC<RunnerProviderProps> = ({ children }) => {
     };
   }, [v, navigate]);
 
+  useDevBridge(runner, { hashTrackingInterval: <%= projectName %>Arena.hashReportInterval });
+
   return !runner ? null : <RunnerContext.Provider value={runner}>{children}</RunnerContext.Provider>;
 };
 

package/templates/pixi-react/__packageName__-frontend/src/app/hooks/use-start-multiplayer-match.ts

@@ -5,7 +5,9 @@ import { useCallback, useRef, useState } from 'react';
 import { useNavigate } from 'react-router-dom';
 import { ProviderStore } from './use-start-match';
 
-const SERVER_URL = import.meta.env.VITE_RELAY_URL || 'ws://localhost:<%= serverPort %>';
+const _params = new URLSearchParams(window.location.search);
+const SERVER_URL = _params.get('serverUrl') || import.meta.env.VITE_RELAY_URL || 'ws://localhost:<%= serverPort %>';
+const SCOPE = _params.get('scope') || '<%= packageName %>';
 
 export type MatchmakingState = 'idle' | 'queuing' | 'connecting' | 'error';
 
@@ -48,7 +50,7 @@ export const useStartMultiplayerMatch = () => {
       ws.send(
         JSON.stringify({
           type: 'join',
-          scope: '<%= packageName %>',
+          scope: SCOPE,
         }),
       );
     };
@@ -85,9 +87,7 @@ export const useStartMultiplayerMatch = () => {
     };
 
     ws.onclose = () => {
-      if (state === 'queuing') {
-        setState('idle');
-      }
+      setState((prev) => (prev === 'queuing' ? 'idle' : prev));
     };
   }, [state]);
 

package/templates/pixi-react/__packageName__-frontend/src/app/screens/title.screen.tsx

@@ -1,6 +1,7 @@
-import { FC } from 'react';
+import { FC, useEffect } from 'react';
 import { useStartMatch } from '../hooks/use-start-match';
 import { useStartMultiplayerMatch } from '../hooks/use-start-multiplayer-match';
+import { DevBridge } from '@lagless/react';
 
 export const TitleScreen: FC = () => {
   const { isBusy, startMatch } = useStartMatch();
@@ -8,6 +9,22 @@ export const TitleScreen: FC = () => {
 
   const isMultiplayerBusy = multiplayer.state !== 'idle';
 
+  // Dev-bridge: auto-match on URL param or parent command
+  useEffect(() => {
+    const params = new URLSearchParams(window.location.search);
+    if (params.get('autoMatch') === 'true' && multiplayer.state === 'idle') {
+      multiplayer.startMatch();
+    }
+    const bridge = DevBridge.fromUrlParams();
+    if (!bridge) return;
+    bridge.sendMatchState(multiplayer.state === 'idle' ? 'idle' : multiplayer.state);
+    return bridge.onParentMessage((msg) => {
+      if (msg.type === 'dev-bridge:start-match' && multiplayer.state === 'idle') {
+        multiplayer.startMatch();
+      }
+    });
+  }, [multiplayer.state]);
+
   return (
     <div style={styles.screen}>
       <div style={styles.title}><%= projectName %></div>

package/templates/pixi-react/__packageName__-simulation/package.json

@@ -18,6 +18,13 @@
     "@lagless/math": "^<%= laglessVersion %>",
     "@lagless/binary": "^<%= laglessVersion %>",
     "@lagless/misc": "^<%= laglessVersion %>",
+<% if (simulationType === 'physics2d') { -%>
+    "@lagless/physics2d": "^<%= laglessVersion %>",
+    "@lagless/physics-shared": "^<%= laglessVersion %>",
+<% } else if (simulationType === 'physics3d') { -%>
+    "@lagless/physics3d": "^<%= laglessVersion %>",
+    "@lagless/physics-shared": "^<%= laglessVersion %>",
+<% } -%>
     "@swc/helpers": "~0.5.11"
   }
 }