@lagless/create 0.0.38 → 0.0.39

package/templates/pixi-react/docs/09-recipes.md

@@ -0,0 +1,362 @@
+# Recipes — Step-by-Step Cookbook
+
+## Add a New Component
+
+1. Edit `ecs.yaml`:
+   ```yaml
+   components:
+     Health:
+       current: uint16
+       max: uint16
+   ```
+2. Run `pnpm codegen`
+3. Import in systems: `import { Health } from '../code-gen/core.js';`
+4. Add to constructor DI: `private readonly _health: Health`
+5. Access data: `this._health.unsafe.current[entity]`
+
+## Add a Tag Component
+
+Tags have no fields — they only occupy a bitmask bit (zero memory per entity).
+
+1. Edit `ecs.yaml`:
+   ```yaml
+   components:
+     Frozen: {}
+     Dead: {}
+   ```
+2. Run `pnpm codegen`
+3. Use in systems:
+   ```typescript
+   // Add tag
+   this._entities.addComponent(entity, Frozen);
+   // Remove tag
+   this._entities.removeComponent(entity, Frozen);
+   // Check tag
+   if (this._entities.hasComponent(entity, Frozen)) { ... }
+   ```
+4. Use in filters:
+   ```yaml
+   filters:
+     ActivePlayerFilter:
+       include: [Transform2d, PlayerBody]
+       exclude: [Frozen, Dead]
+   ```
+
+## Add a New System
+
+1. Create `systems/my-feature.system.ts`:
+   ```typescript
+   import { ECSSystem, IECSSystem } from '@lagless/core';
+   import { Transform2d, PlayerFilter } from '../code-gen/core.js';
+
+   @ECSSystem()
+   export class MyFeatureSystem implements IECSSystem {
+     constructor(
+       private readonly _transform: Transform2d,
+       private readonly _filter: PlayerFilter,
+     ) {}
+
+     update(tick: number): void {
+       for (const entity of this._filter) {
+         // your logic here
+       }
+     }
+   }
+   ```
+2. Add to `systems/index.ts`:
+   ```typescript
+   import { MyFeatureSystem } from './my-feature.system.js';
+
+   export const systems = [
+     // ... existing systems
+     MyFeatureSystem,  // add in correct execution order
+     // ... hash verification last
+   ];
+   ```
+
+## Add a New Input Type
+
+1. Edit `ecs.yaml`:
+   ```yaml
+   inputs:
+     ShootInput:
+       targetX: float32
+       targetY: float32
+   ```
+2. Run `pnpm codegen`
+3. Send from client (in `runner-provider.tsx` drainInputs):
+   ```typescript
+   if (mouseClicked) {
+     addRPC(ShootInput, { targetX: mouseWorldX, targetY: mouseWorldY });
+   }
+   ```
+4. Read in system:
+   ```typescript
+   const rpcs = this._input.collectTickRPCs(tick, ShootInput);
+   for (const rpc of rpcs) {
+     const targetX = MathOps.clamp(finite(rpc.data.targetX), -1000, 1000);
+     const targetY = MathOps.clamp(finite(rpc.data.targetY), -1000, 1000);
+     // spawn projectile, etc.
+   }
+   ```
+
+## Add a New Entity Type
+
+1. Define components and filter in `ecs.yaml`:
+   ```yaml
+   components:
+     Projectile:
+       ownerSlot: uint8
+       damage: uint16
+       spawnTick: uint32
+       lifetimeTicks: uint16
+     Velocity2d:
+       velocityX: float32
+       velocityY: float32
+
+   filters:
+     ProjectileFilter:
+       include: [Transform2d, Projectile, Velocity2d]
+   ```
+2. Run `pnpm codegen`
+3. Create spawn logic in a system:
+   ```typescript
+   const entity = this._entities.createEntity();
+   this._entities.addComponent(entity, Transform2d);
+   this._entities.addComponent(entity, Projectile);
+   this._entities.addComponent(entity, Velocity2d);
+
+   this._transform.set(entity, {
+     positionX: startX, positionY: startY,
+     prevPositionX: startX, prevPositionY: startY,
+   });
+   this._projectile.set(entity, {
+     ownerSlot: slot, damage: 10, spawnTick: tick, lifetimeTicks: 60,
+   });
+   ```
+4. Create view component (see [06-rendering.md](06-rendering.md))
+5. Add `<FilterViews filter={runner.Core.ProjectileFilter} View={ProjectileView} />`
+
+## Add a Signal
+
+1. Define in `signals/index.ts`:
+   ```typescript
+   @ECSSignal()
+   export class ExplosionSignal extends Signal<{ x: number; y: number }> {}
+   ```
+2. Register in `arena.ts` signals array
+3. Emit in system:
+   ```typescript
+   this._explosionSignal.emit(tick, { x: posX, y: posY });
+   ```
+4. Subscribe in view:
+   ```typescript
+   explosionSignal.Predicted.subscribe(e => spawnExplosionParticles(e.data.x, e.data.y));
+   explosionSignal.Cancelled.subscribe(e => removeExplosionParticles());
+   ```
+
+## Add a New Screen
+
+1. Create `screens/lobby.screen.tsx`:
+   ```tsx
+   export function LobbyScreen() {
+     const navigate = useNavigate();
+     return (
+       <div>
+         <h1>Lobby</h1>
+         <button onClick={() => navigate('/game')}>Start</button>
+       </div>
+     );
+   }
+   ```
+2. Add route in `router.tsx`:
+   ```tsx
+   <Route path="/lobby" element={<LobbyScreen />} />
+   ```
+
+## Add Bot AI
+
+Bots are simulated as if they were players sending RPCs via server events.
+
+1. Add bot management to server hooks:
+   ```typescript
+   // In game-hooks.ts:
+   onRoomCreated: (ctx) => {
+     // Schedule bot input every tick
+     setInterval(() => {
+       const botSlot = 1; // reserved for bot
+       ctx.emitServerEvent(MoveInput, {
+         directionX: calculateBotDirX(),
+         directionY: calculateBotDirY(),
+       }, botSlot);
+     }, 50); // 20 ticks/sec
+   },
+   ```
+2. Bot inputs flow through the same RPC system — no special handling in simulation
+
+## Add Game Phases (Lobby → Playing → GameOver)
+
+1. Add singleton in `ecs.yaml`:
+   ```yaml
+   singletons:
+     GameState:
+       gamePhase: uint8        # 0=lobby, 1=countdown, 2=playing, 3=gameover
+       phaseStartTick: uint32
+   ```
+2. Create `game-phase.system.ts`:
+   ```typescript
+   @ECSSystem()
+   export class GamePhaseSystem implements IECSSystem {
+     constructor(
+       private readonly _gameState: GameState,
+       private readonly _config: ECSConfig,
+     ) {}
+
+     update(tick: number): void {
+       const phase = this._gameState.gamePhase;
+       const elapsed = tick - this._gameState.phaseStartTick;
+
+       if (phase === 1 && elapsed > 60) { // 3 seconds at 20 tps
+         this._gameState.gamePhase = 2;
+         this._gameState.phaseStartTick = tick;
+       }
+       // ... more phase transitions
+     }
+   }
+   ```
+
+## Add Timer / Countdown
+
+```typescript
+@ECSSystem()
+export class TimerSystem implements IECSSystem {
+  constructor(
+    private readonly _gameState: GameState,
+    private readonly _config: ECSConfig,
+  ) {}
+
+  update(tick: number): void {
+    const elapsed = tick - this._gameState.phaseStartTick;
+    const elapsedSeconds = elapsed * this._config.frameLength;
+    const remainingSeconds = Math.max(0, 120 - elapsedSeconds); // 2 minute timer
+
+    if (remainingSeconds <= 0) {
+      this._gameState.gamePhase = 3; // gameover
+    }
+  }
+}
+```
+
+Display in React:
+```tsx
+const elapsed = runner.Simulation.tick - gameState.phaseStartTick;
+const remaining = Math.max(0, 120 - elapsed / runner.Config.tickRate);
+return <div>{Math.ceil(remaining)}s</div>;
+```
+
+## Add Score Tracking
+
+1. Add to playerResources in `ecs.yaml`:
+   ```yaml
+   playerResources:
+     PlayerResource:
+       score: uint32
+       kills: uint16
+       deaths: uint16
+   ```
+2. Update in system:
+   ```typescript
+   this._playerResource.score[killerSlot] += 100;
+   this._playerResource.kills[killerSlot] += 1;
+   this._playerResource.deaths[victimSlot] += 1;
+   ```
+3. Read in view:
+   ```tsx
+   const score = runner.Core.PlayerResource.score[localSlot];
+   ```
+
+## Add Death / Respawn
+
+```typescript
+@ECSSystem()
+export class DeathRespawnSystem implements IECSSystem {
+  constructor(
+    private readonly _entities: EntitiesManager,
+    private readonly _transform: Transform2d,
+    private readonly _playerBody: PlayerBody,
+    private readonly _filter: PlayerFilter,
+    private readonly _prng: PRNG,
+  ) {}
+
+  update(tick: number): void {
+    for (const entity of this._filter) {
+      if (this._playerBody.unsafe.health[entity] <= 0) {
+        // Death: add Dead tag
+        this._entities.addComponent(entity, Dead);
+
+        // Schedule respawn: store death tick
+        this._playerBody.unsafe.deathTick[entity] = tick;
+      }
+    }
+
+    // Check for respawn
+    for (const entity of this._deadFilter) {
+      const deathTick = this._playerBody.unsafe.deathTick[entity];
+      if (tick - deathTick >= 60) { // 3 seconds at 20 tps
+        this._entities.removeComponent(entity, Dead);
+        // Respawn at random position
+        const x = this._prng.getRandomInt(-400, 400);
+        const y = this._prng.getRandomInt(-300, 300);
+        this._transform.set(entity, {
+          positionX: x, positionY: y,
+          prevPositionX: x, prevPositionY: y,
+        });
+        this._playerBody.unsafe.health[entity] = this._playerBody.unsafe.maxHealth[entity];
+      }
+    }
+  }
+}
+```
+
+## Add Projectile with Lifetime
+
+```typescript
+@ECSSystem()
+export class ProjectileLifetimeSystem implements IECSSystem {
+  constructor(
+    private readonly _entities: EntitiesManager,
+    private readonly _projectile: Projectile,
+    private readonly _filter: ProjectileFilter,
+  ) {}
+
+  update(tick: number): void {
+    for (const entity of this._filter) {
+      const spawnTick = this._projectile.unsafe.spawnTick[entity];
+      const lifetime = this._projectile.unsafe.lifetimeTicks[entity];
+
+      if (tick - spawnTick >= lifetime) {
+        this._entities.removeEntity(entity);
+      }
+    }
+  }
+}
+```
+
+## Add a Singleton
+
+1. Edit `ecs.yaml`:
+   ```yaml
+   singletons:
+     ArenaConfig:
+       radius: float32
+       shrinkRate: float32
+   ```
+2. Run `pnpm codegen`
+3. Access in systems:
+   ```typescript
+   constructor(private readonly _arenaConfig: ArenaConfig) {}
+   update(tick: number): void {
+     const r = this._arenaConfig.radius;
+     this._arenaConfig.radius -= this._arenaConfig.shrinkRate;
+   }
+   ```

package/templates/pixi-react/docs/10-common-mistakes.md

@@ -0,0 +1,224 @@
+# Common Mistakes
+
+## Determinism
+
+### Using Math.sin/cos/atan2/sqrt
+
+**Wrong:**
+```typescript
+const angle = Math.atan2(dy, dx);
+const dist = Math.sqrt(dx * dx + dy * dy);
+```
+**Correct:**
+```typescript
+const angle = MathOps.atan2(dy, dx);
+const dist = MathOps.sqrt(dx * dx + dy * dy);
+```
+**Why:** `Math.*` trig/sqrt results differ between browsers and platforms. MathOps uses WASM for cross-platform determinism.
+
+### Using Math.random()
+
+**Wrong:** `const r = Math.random();`
+**Correct:** `const r = this._prng.getFloat();`
+**Why:** Math.random() produces different values on each client. PRNG state is in the ArrayBuffer and deterministic.
+
+### Forgetting prevPosition on Spawn
+
+**Wrong:**
+```typescript
+this._transform.set(entity, { positionX: 100, positionY: 200 });
+```
+**Correct:**
+```typescript
+this._transform.set(entity, {
+  positionX: 100, positionY: 200,
+  prevPositionX: 100, prevPositionY: 200,
+});
+```
+**Why:** prevPosition defaults to 0. Interpolation between (0,0) and (100,200) causes a one-frame visual jump.
+
+### Array.sort() without Comparator
+
+**Wrong:** `entities.sort();`
+**Correct:** `entities.sort((a, b) => a - b);`
+**Why:** Default sort is lexicographic and engine-dependent. Explicit comparator ensures deterministic order.
+
+### Using Date.now() in Simulation
+
+**Wrong:** `if (Date.now() > deadline) { ... }`
+**Correct:** `if (tick > deadlineTick) { ... }`
+**Why:** Date.now() differs between clients. Use tick count for all time-based logic.
+
+## Input
+
+### Not Sanitizing RPC Data
+
+**Wrong:**
+```typescript
+const dirX = rpc.data.directionX;  // Could be NaN, Infinity
+this._velocity.unsafe.velocityX[entity] = dirX * speed;
+```
+**Correct:**
+```typescript
+const finite = (v: number): number => Number.isFinite(v) ? v : 0;
+let dirX = MathOps.clamp(finite(rpc.data.directionX), -1, 1);
+this._velocity.unsafe.velocityX[entity] = dirX * speed;
+```
+**Why:** Network messages can contain NaN/Infinity. NaN propagates through all math and corrupts state permanently.
+
+### Clamping Before Finite Check
+
+**Wrong:** `MathOps.clamp(rpc.data.value, -1, 1)` — clamp(NaN) returns NaN
+**Correct:** `MathOps.clamp(finite(rpc.data.value), -1, 1)`
+**Why:** MathOps.clamp does NOT handle NaN. Always check `Number.isFinite()` first.
+
+## Schema
+
+### Editing Generated Code
+
+**Wrong:** Editing files in `code-gen/` directory
+**Correct:** Edit `ecs.yaml` and run `pnpm codegen`
+**Why:** Generated files are overwritten on every codegen run. Changes will be lost.
+
+### Declaring Transform2d with simulationType
+
+**Wrong:**
+```yaml
+simulationType: physics2d
+components:
+  Transform2d:         # Already auto-prepended!
+    positionX: float32
+```
+**Correct:**
+```yaml
+simulationType: physics2d
+components:
+  PlayerBody:          # Only declare your own components
+    playerSlot: uint8
+```
+**Why:** `simulationType: physics2d` auto-prepends Transform2d + PhysicsRefs. Declaring them manually causes conflicts.
+
+## Systems
+
+### Wrong System Order
+
+**Wrong:** HashVerificationSystem before game logic systems
+**Correct:** HashVerificationSystem always last
+**Why:** Hash verification must check state after all game logic has run.
+
+### Storing State Outside ArrayBuffer
+
+**Wrong:**
+```typescript
+class MySystem {
+  private _cache = new Map();  // Lost on rollback!
+}
+```
+**Correct:** Store all state in ECS components, singletons, or player resources.
+**Why:** Rollback restores the ArrayBuffer but NOT JavaScript variables. External state causes desync.
+
+### Modifying State in View Layer
+
+**Wrong:**
+```typescript
+// In filterView onUpdate:
+runner.Core.Transform2d.unsafe.positionX[entity] = smoothedX;
+```
+**Correct:** View layer is read-only. Only systems modify ECS state.
+**Why:** View modifications bypass deterministic simulation, causing desync.
+
+## Rendering
+
+### Not Using VisualSmoother2d
+
+**Wrong:**
+```typescript
+container.position.set(
+  transform.unsafe.positionX[entity],
+  transform.unsafe.positionY[entity],
+);
+```
+**Better:**
+```typescript
+const smoothed = smoother.update(prevX, prevY, currX, currY, factor, dt);
+container.position.set(smoothed.x, smoothed.y);
+```
+**Why:** Without smoothing, entities teleport on rollback. VisualSmoother2d absorbs position jumps and decays smoothly.
+
+### Using getCursor in Hot Path
+
+**Wrong:**
+```typescript
+onUpdate: ({ entity }, container) => {
+  const cursor = transform.getCursor(entity);  // Object allocation every frame
+  container.x = cursor.positionX;
+}
+```
+**Correct:**
+```typescript
+onUpdate: ({ entity }, container) => {
+  container.x = transform.unsafe.positionX[entity];  // Direct typed array access
+}
+```
+**Why:** getCursor creates an object per call. In onUpdate (called every frame per entity), use unsafe arrays.
+
+## Physics
+
+### Using handle | 0 for Rapier Handles
+
+**Wrong:** `const index = handle | 0;`
+**Correct:** Use `handleToIndex()` from `@lagless/physics-shared`
+**Why:** Rapier handles are Float64 where low values are denormalized floats. Bitwise OR gives 0 for all of them.
+
+### Setting Dynamic Body Position Directly
+
+**Wrong:**
+```typescript
+this._transform.unsafe.positionX[entity] = newX; // Physics will overwrite!
+```
+**Correct:**
+```typescript
+this._physics.setLinearVelocity(entity, { x: vx, y: vy });
+// or
+this._physics.applyImpulse(entity, { x: fx, y: fy });
+```
+**Why:** PhysicsStep syncs Rapier→ECS, overwriting manual position changes. Move dynamic bodies via forces/velocity.
+
+### Forgetting updateSceneQueries After Restore
+
+The framework handles this automatically, but if you're doing custom Rapier operations:
+**Always** call `world.updateSceneQueries()` after `World.restoreSnapshot()`.
+**Why:** Restored worlds have empty QueryPipeline — ray casts and shape casts will miss all colliders.
+
+## Multiplayer
+
+### Keeping State in Frontend Variables
+
+**Wrong:**
+```typescript
+const [score, setScore] = useState(0);
+// Updated in signal handler, lost on page refresh
+```
+**Better:** Read score from `PlayerResource.score[slot]` in the ArrayBuffer.
+**Why:** React state is not synchronized across clients. ECS state in the ArrayBuffer is.
+
+### Not Testing with Two Players
+
+Always test multiplayer with at least 2 browser tabs or dev-player instances. Single-player testing misses:
+- Rollback behavior
+- Input delay effects
+- State transfer
+- Determinism bugs
+
+## Error Message Solutions
+
+| Error | Cause | Solution |
+|-------|-------|---------|
+| `MathOps not initialized` | MathOps.init() not called | Add `await MathOps.init()` before simulation starts |
+| `Entity X has no component Y` | Component not added before access | Call `addComponent(entity, Y)` first |
+| `Filter overflow` | More entities than maxEntities | Increase `maxEntities` in ECSConfig |
+| `Cannot read property of undefined` in system | DI injection failed | Check constructor parameter type matches imported class |
+| `reflect-metadata` error | Missing import | Add `import '@abraham/reflection'` in main entry point |
+| Hash mismatch in debug panel | Determinism violation | See [03-determinism.md](03-determinism.md) debugging section |
+| `WASM module not found` | MathOps WASM not loaded | Ensure `await MathOps.init()` completes before any math |
+| State transfer failed | No quorum on snapshot hash | Check for determinism bugs — clients diverged before state transfer |