@lagless/create 0.0.36 → 0.0.39

package/templates/pixi-react/docs/01-schema-and-codegen.md

@@ -0,0 +1,244 @@
+# Schema & Codegen
+
+## Overview
+
+All ECS structure is defined in a single YAML file: `<game>-simulation/src/lib/schema/ecs.yaml`. After editing, run `pnpm codegen` to regenerate TypeScript code into `src/lib/code-gen/`.
+
+**Never edit files in `code-gen/` manually** — they are overwritten on every codegen run.
+
+## Codegen Command
+
+```bash
+pnpm codegen
+# Or directly:
+npx @lagless/codegen -c <game>-simulation/src/lib/schema/ecs.yaml
+```
+
+## Field Types
+
+| YAML Type | TypedArray | Bytes | Range |
+|-----------|-----------|-------|-------|
+| `uint8` | Uint8Array | 1 | 0 to 255 |
+| `uint16` | Uint16Array | 2 | 0 to 65,535 |
+| `uint32` | Uint32Array | 4 | 0 to 4,294,967,295 |
+| `int8` | Int8Array | 1 | -128 to 127 |
+| `int16` | Int16Array | 2 | -32,768 to 32,767 |
+| `int32` | Int32Array | 4 | -2,147,483,648 to 2,147,483,647 |
+| `float32` | Float32Array | 4 | ~7 significant digits |
+| `float64` | Float64Array | 8 | ~15 significant digits |
+| `uint8[N]` | Uint8Array | N | Fixed-size byte array (e.g., UUIDs) |
+
+## Components
+
+Components define per-entity data stored in Structure-of-Arrays layout.
+
+```yaml
+components:
+  # Regular component with fields
+  Transform2d:
+    positionX: float32
+    positionY: float32
+    prevPositionX: float32
+    prevPositionY: float32
+
+  # Component with mixed types
+  PlayerBody:
+    playerSlot: uint8
+    radius: float32
+    health: uint16
+
+  # Tag component — no fields, zero memory, bitmask-only
+  Frozen: {}
+
+  # Also a tag (equivalent to {})
+  Dead:
+```
+
+### Tag Components
+
+Components with no fields (`{}` or empty body) are automatically detected as **tags**. They:
+- Occupy zero memory per entity (only a bitmask bit)
+- Work in filters and prefabs like normal components
+- Used for state flags: `Frozen`, `Dead`, `Invincible`, etc.
+
+### Component IDs
+
+Component IDs are sequential bit indices (0, 1, 2, ...) assigned in YAML declaration order. The framework supports up to **64 component types** (auto-detected: 1 Uint32 mask word for ≤32, 2 words for 33-64).
+
+## Singletons
+
+Global typed fields — one copy per simulation (not per entity).
+
+```yaml
+singletons:
+  GameState:
+    gamePhase: uint8       # 0=lobby, 1=playing, 2=gameover
+    roundTimer: uint32
+    arenaRadius: float32
+```
+
+Access in systems: `this._gameState.gamePhase` (read/write directly).
+
+## Player Resources
+
+Per-player data indexed by player slot (0 to maxPlayers-1).
+
+```yaml
+playerResources:
+  PlayerResource:
+    id: uint8[16]                  # Player UUID
+    entity: uint32                 # Player's entity ID
+    connected: uint8               # Boolean: is connected
+    score: uint32
+    lastReportedHash: uint32       # Required for hash verification
+    lastReportedHashTick: uint32   # Required for hash verification
+    hashMismatchCount: uint16      # Required for hash verification
+```
+
+Access in systems: `this._playerResource.score[slot]`.
+
+**Hash verification fields** (`lastReportedHash`, `lastReportedHashTick`, `hashMismatchCount`) are required if you use hash-based divergence detection.
+
+## Inputs (RPCs)
+
+Inputs define the data structure for client→server→client messages.
+
+```yaml
+inputs:
+  # Server event — emitted by server hooks (onPlayerJoin, etc.)
+  PlayerJoined:
+    slot: uint8
+    playerId: uint8[16]
+
+  PlayerLeft:
+    slot: uint8
+    reason: uint8
+
+  # Player input — sent by client via drainInputs/addRPC
+  MoveInput:
+    directionX: float32
+    directionY: float32
+
+  # Hash reporting — required for divergence detection
+  ReportHash:
+    hash: uint32
+    atTick: uint32
+```
+
+### Input Conventions
+- **Server events** (PlayerJoined, PlayerLeft): emitted by `ctx.emitServerEvent()` in RoomHooks
+- **Player inputs** (MoveInput, etc.): sent by client via `addRPC()` in `drainInputs`
+- **ReportHash**: automatically sent by `createHashReporter()` — don't send manually
+
+## Filters
+
+Filters maintain live entity lists matching include/exclude component masks.
+
+```yaml
+filters:
+  PlayerFilter:
+    include: [Transform2d, PlayerBody]
+
+  MovingFilter:
+    include: [Transform2d, Velocity2d]
+
+  FrozenPlayerFilter:
+    include: [Transform2d, PlayerBody, Frozen]
+
+  ActivePlayerFilter:
+    include: [Transform2d, PlayerBody]
+    exclude: [Frozen, Dead]
+```
+
+Filters are iterable in systems: `for (const entity of this._filter) { ... }`.
+Filter data lives in the shared ArrayBuffer and is restored on rollback.
+
+## Simulation Type
+
+The `simulationType` field enables physics engine integration:
+
+```yaml
+# No physics — manual velocity/position management
+# (default, no simulationType field needed)
+
+# Rapier 2D physics
+simulationType: physics2d
+
+# Rapier 3D physics
+simulationType: physics3d
+```
+
+### Auto-Prepended Components
+
+When `simulationType: physics2d`:
+- **Transform2d** (6 fields): `positionX`, `positionY`, `rotation`, `prevPositionX`, `prevPositionY`, `prevRotation`
+- **PhysicsRefs**: `bodyHandle: float64`, `colliderHandle: float64`, `bodyType: uint8`, `collisionLayer: uint16`
+- **PhysicsRefsFilter** automatically created
+
+When `simulationType: physics3d`:
+- **Transform3d** (14 fields): `positionX/Y/Z`, `rotationX/Y/Z/W`, `prevPositionX/Y/Z`, `prevRotationX/Y/Z/W`
+- **PhysicsRefs**: same as 2D
+- **PhysicsRefsFilter** automatically created
+
+**Do NOT declare Transform2d/Transform3d or PhysicsRefs manually** when using a simulationType — they are auto-prepended.
+
+## Generated Files
+
+After running `pnpm codegen`, the following files are generated in `src/lib/code-gen/`:
+
+| File | Contents |
+|------|----------|
+| `core.ts` | All component classes, singleton classes, filter classes, player resource classes |
+| `runner.ts` | `<ProjectName>Runner` class extending `ECSRunner` with typed `Core` accessor |
+| `input-registry.ts` | `<ProjectName>InputRegistry` with all input types registered |
+| `prefabs.ts` | Helper prefab builders for common entity archetypes |
+
+The runner class provides typed access to all ECS objects:
+```typescript
+runner.Core.Transform2d          // component
+runner.Core.PlayerFilter         // filter
+runner.Core.GameState            // singleton
+runner.Core.PlayerResource       // player resource
+```
+
+## Common Schema Patterns
+
+### Player Entity
+```yaml
+components:
+  PlayerBody:
+    playerSlot: uint8
+    radius: float32
+    health: uint16
+    maxHealth: uint16
+
+filters:
+  PlayerFilter:
+    include: [Transform2d, PlayerBody]
+```
+
+### Projectile with Lifetime
+```yaml
+components:
+  Projectile:
+    ownerSlot: uint8
+    damage: uint16
+    spawnTick: uint32
+    lifetimeTicks: uint16
+  Velocity2d:
+    velocityX: float32
+    velocityY: float32
+
+filters:
+  ProjectileFilter:
+    include: [Transform2d, Projectile, Velocity2d]
+```
+
+### Game Phases via Singleton
+```yaml
+singletons:
+  GameState:
+    gamePhase: uint8        # enum: 0=waiting, 1=countdown, 2=playing, 3=gameover
+    phaseStartTick: uint32
+    roundNumber: uint8
+```

package/templates/pixi-react/docs/02-ecs-systems.md

@@ -0,0 +1,293 @@
+# ECS Systems
+
+## Anatomy of a System
+
+Systems are classes decorated with `@ECSSystem()` that implement `IECSSystem`. Dependencies are injected via constructor.
+
+```typescript
+import { ECSSystem, IECSSystem } from '@lagless/core';
+import { Transform2d, Velocity2d, MovingFilter } from '../code-gen/core.js';
+
+@ECSSystem()
+export class IntegrateSystem implements IECSSystem {
+  constructor(
+    private readonly _transform: Transform2d,
+    private readonly _velocity: Velocity2d,
+    private readonly _filter: MovingFilter,
+  ) {}
+
+  update(tick: number): void {
+    for (const entity of this._filter) {
+      this._transform.unsafe.positionX[entity] += this._velocity.unsafe.velocityX[entity];
+      this._transform.unsafe.positionY[entity] += this._velocity.unsafe.velocityY[entity];
+    }
+  }
+}
+```
+
+## DI Injectable Tokens
+
+Any of these types can be requested in a system's constructor:
+
+| Type | What You Get |
+|------|-------------|
+| `Transform2d`, `PlayerBody`, etc. | Component class — access entity data |
+| `PlayerFilter`, `MovingFilter`, etc. | Filter class — iterate matching entities |
+| `GameState`, etc. | Singleton — global data fields |
+| `PlayerResource` | Per-player data indexed by slot |
+| `EntitiesManager` | Create/remove entities, add/remove components |
+| `PRNG` | Deterministic random number generator |
+| `ECSConfig` | Simulation configuration (maxEntities, tickRate, etc.) |
+| `AbstractInputProvider` | Read RPCs via `collectTickRPCs()` |
+| `ScoreSignal`, etc. | Signal classes — emit rollback-aware events |
+
+## Data Access Patterns
+
+### Hot Path — Unsafe Typed Arrays (Fastest)
+
+Direct typed array access. No bounds checking. Use in system `update()` loops.
+
+```typescript
+// Read
+const x = this._transform.unsafe.positionX[entity];
+
+// Write
+this._transform.unsafe.positionX[entity] = 100;
+this._transform.unsafe.positionY[entity] = 200;
+```
+
+### Convenient — Cursor (Single Entity)
+
+Object-like access for setup/initialization code. Slower than unsafe.
+
+```typescript
+const cursor = this._transform.getCursor(entity);
+cursor.positionX = 100;
+cursor.positionY = 200;
+// cursor.positionX also readable
+```
+
+### Component Set (Bulk Init)
+
+Set multiple fields at once:
+
+```typescript
+this._transform.set(entity, {
+  positionX: 100,
+  positionY: 200,
+  prevPositionX: 100,  // ALWAYS set prev = current on spawn!
+  prevPositionY: 200,
+});
+```
+
+## Entity Lifecycle
+
+### Creating Entities
+
+```typescript
+const entity = this._entities.createEntity();
+this._entities.addComponent(entity, Transform2d);
+this._entities.addComponent(entity, PlayerBody);
+
+// Set initial data
+this._transform.set(entity, {
+  positionX: spawnX,
+  positionY: spawnY,
+  prevPositionX: spawnX,   // MUST match position to avoid interpolation jump
+  prevPositionY: spawnY,
+});
+this._playerBody.set(entity, { playerSlot: slot, radius: 20 });
+```
+
+### Removing Entities
+
+```typescript
+this._entities.removeEntity(entity);
+// Entity ID goes to recycling stack, will be reused
+```
+
+### Adding/Removing Components
+
+```typescript
+// Add component to existing entity
+this._entities.addComponent(entity, Frozen);  // tag component
+
+// Remove component
+this._entities.removeComponent(entity, Frozen);
+
+// Check if entity has component
+if (this._entities.hasComponent(entity, Frozen)) { ... }
+```
+
+### Component Masks
+
+Entity presence in filters is determined by component bitmasks. When you add/remove a component, the entity automatically enters/leaves matching filters.
+
+## Prefabs
+
+Prefabs provide a fluent API for entity creation with multiple components:
+
+```typescript
+import { Prefab } from '@lagless/core';
+
+// In a system:
+const entity = Prefab.create(this._entities)
+  .with(Transform2d, { positionX: 0, positionY: 0, prevPositionX: 0, prevPositionY: 0 })
+  .with(PlayerBody, { playerSlot: slot, radius: 20 })
+  .with(Velocity2d, { velocityX: 0, velocityY: 0 })
+  .build();
+```
+
+## Filter Iteration
+
+Filters are iterable — they yield entity IDs matching their include/exclude masks.
+
+```typescript
+// Basic iteration
+for (const entity of this._filter) {
+  const x = this._transform.unsafe.positionX[entity];
+  // ...
+}
+
+// Check filter length
+if (this._filter.length === 0) return;
+
+// Access underlying array (advanced)
+const entities = this._filter.entities; // number[]
+```
+
+**Filter data lives in the ArrayBuffer** — it's automatically restored on rollback.
+
+## PRNG (Deterministic Random)
+
+The PRNG state is stored in the ArrayBuffer, so it's restored on rollback. **Never use `Math.random()`.**
+
+```typescript
+@ECSSystem()
+export class SpawnSystem implements IECSSystem {
+  constructor(private readonly _prng: PRNG) {}
+
+  update(tick: number): void {
+    // Random float in [0, 1)
+    const f = this._prng.getFloat();
+
+    // Random integer in [from, to) — exclusive upper bound
+    const x = this._prng.getRandomInt(-500, 500);
+
+    // Random integer in [from, to] — inclusive upper bound
+    const y = this._prng.getRandomIntInclusive(1, 6);
+  }
+}
+```
+
+## Player Resources
+
+Per-player data indexed by slot (0 to maxPlayers-1). Stored in the ArrayBuffer.
+
+```typescript
+@ECSSystem()
+export class ScoreSystem implements IECSSystem {
+  constructor(private readonly _playerResource: PlayerResource) {}
+
+  update(tick: number): void {
+    // Read
+    const score = this._playerResource.score[slot];
+
+    // Write
+    this._playerResource.score[slot] += 100;
+
+    // Check connection
+    if (this._playerResource.connected[slot]) { ... }
+  }
+}
+```
+
+## ECSConfig
+
+Access simulation configuration:
+
+```typescript
+@ECSSystem()
+export class MySystem implements IECSSystem {
+  constructor(private readonly _config: ECSConfig) {}
+
+  update(tick: number): void {
+    const maxE = this._config.maxEntities;    // default 1024
+    const maxP = this._config.maxPlayers;     // default 4
+    const dt = this._config.frameLength;       // seconds per tick (e.g., 1/20)
+    const rate = this._config.tickRate;        // ticks per second (e.g., 20)
+  }
+}
+```
+
+## System Registration
+
+Systems must be registered in the systems array in `systems/index.ts`. **Order matters** — systems execute sequentially in array order every tick.
+
+```typescript
+import { IECSSystemClass } from '@lagless/core';
+import { SavePrevTransformSystem } from './save-prev-transform.system.js';
+import { PlayerConnectionSystem } from './player-connection.system.js';
+import { ApplyMoveInputSystem } from './apply-move-input.system.js';
+import { IntegrateSystem } from './integrate.system.js';
+import { BoundarySystem } from './boundary.system.js';
+import { PlayerLeaveSystem } from './player-leave.system.js';
+import { HashVerificationSystem } from './hash-verification.system.js';
+
+export const systems: IECSSystemClass[] = [
+  SavePrevTransformSystem,     // 1. Store prev positions for interpolation
+  PlayerConnectionSystem,      // 2. Handle join/leave events
+  ApplyMoveInputSystem,        // 3. Read player inputs
+  IntegrateSystem,             // 4. Apply velocities
+  BoundarySystem,              // 5. Enforce boundaries
+  PlayerLeaveSystem,           // 6. Cleanup disconnected entities
+  HashVerificationSystem,      // 7. ALWAYS LAST — divergence detection
+];
+```
+
+## Complete System Example
+
+A system that reads move inputs, sanitizes them, and applies velocity:
+
+```typescript
+import { ECSSystem, IECSSystem, AbstractInputProvider, ECSConfig } from '@lagless/core';
+import { MathOps } from '@lagless/math';
+import { Transform2d, Velocity2d, PlayerBody, PlayerFilter, MoveInput } from '../code-gen/core.js';
+
+const finite = (v: number): number => Number.isFinite(v) ? v : 0;
+
+@ECSSystem()
+export class ApplyMoveInputSystem implements IECSSystem {
+  constructor(
+    private readonly _input: AbstractInputProvider,
+    private readonly _transform: Transform2d,
+    private readonly _velocity: Velocity2d,
+    private readonly _playerBody: PlayerBody,
+    private readonly _filter: PlayerFilter,
+    private readonly _config: ECSConfig,
+  ) {}
+
+  update(tick: number): void {
+    const rpcs = this._input.collectTickRPCs(tick, MoveInput);
+    for (const rpc of rpcs) {
+      const slot = rpc.meta.playerSlot;
+
+      // ALWAYS sanitize RPC data
+      let dirX = finite(rpc.data.directionX);
+      let dirY = finite(rpc.data.directionY);
+      dirX = MathOps.clamp(dirX, -1, 1);
+      dirY = MathOps.clamp(dirY, -1, 1);
+
+      // Find entity for this player slot
+      for (const entity of this._filter) {
+        if (this._playerBody.unsafe.playerSlot[entity] !== slot) continue;
+
+        const speed = 200 * this._config.frameLength;
+        this._velocity.unsafe.velocityX[entity] = dirX * speed;
+        this._velocity.unsafe.velocityY[entity] = dirY * speed;
+        break;
+      }
+    }
+  }
+}
+```