@lagless/create 0.0.33

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+import { program } from 'commander';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as ejs from 'ejs';
+import { fileURLToPath } from 'node:url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+function toPascalCase(kebab) {
+    return kebab.split('-').map((s)=>s.charAt(0).toUpperCase() + s.slice(1)).join('');
+}
+function getTemplatesDir() {
+    // In development (source), templates are sibling to src/
+    // In dist, templates are at package root (copied by files field)
+    const devPath = path.resolve(__dirname, '..', 'templates');
+    if (fs.existsSync(devPath)) return devPath;
+    // Fallback for npm install
+    const distPath = path.resolve(__dirname, '..', '..', 'templates');
+    if (fs.existsSync(distPath)) return distPath;
+    throw new Error('Templates directory not found');
+}
+function walkDir(dir) {
+    const results = [];
+    for (const entry of fs.readdirSync(dir, {
+        withFileTypes: true
+    })){
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            results.push(...walkDir(full));
+        } else {
+            results.push(full);
+        }
+    }
+    return results;
+}
+function processPath(filePath, vars) {
+    let result = filePath;
+    result = result.replace(/__packageName__/g, vars.packageName);
+    result = result.replace(/__ProjectName__/g, vars.projectName);
+    return result;
+}
+program.name('create-lagless').description('Scaffold a new Lagless multiplayer game project').version('0.0.30').argument('<project-name>', 'Project name in kebab-case (e.g., my-game)').option('--preset <preset>', 'Project preset', 'pixi-react').option('--port <port>', 'Frontend dev server port', '4200').option('--server-port <port>', 'Backend server port', '3333').action(async (projectArg, options)=>{
+    const targetDir = path.resolve(process.cwd(), projectArg);
+    const packageName = path.basename(targetDir).toLowerCase();
+    const pascalName = toPascalCase(packageName);
+    if (fs.existsSync(targetDir)) {
+        console.error(`Error: Directory "${targetDir}" already exists.`);
+        process.exit(1);
+    }
+    const templatesDir = getTemplatesDir();
+    const presetDir = path.join(templatesDir, options.preset);
+    if (!fs.existsSync(presetDir)) {
+        console.error(`Error: Preset "${options.preset}" not found. Available: ${fs.readdirSync(templatesDir).join(', ')}`);
+        process.exit(1);
+    }
+    // Read package.json from this package to get current lagless version
+    const pkgJsonPath = path.resolve(__dirname, '..', 'package.json');
+    let laglessVersion = '0.0.30';
+    try {
+        const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
+        laglessVersion = pkg.version || laglessVersion;
+    } catch (e) {
+    // fallback
+    }
+    const vars = {
+        projectName: pascalName,
+        packageName,
+        frontendPort: options.port,
+        serverPort: options.serverPort,
+        laglessVersion
+    };
+    console.log(`\nCreating Lagless project "${packageName}"...`);
+    console.log(`  Preset: ${options.preset}`);
+    console.log(`  Frontend port: ${options.port}`);
+    console.log(`  Server port: ${options.serverPort}`);
+    console.log(`  Target: ${targetDir}\n`);
+    const templateFiles = walkDir(presetDir);
+    for (const templateFile of templateFiles){
+        const relativePath = path.relative(presetDir, templateFile);
+        const outputRelative = processPath(relativePath, vars);
+        const outputPath = path.join(targetDir, outputRelative);
+        const outputDir = path.dirname(outputPath);
+        if (!fs.existsSync(outputDir)) {
+            fs.mkdirSync(outputDir, {
+                recursive: true
+            });
+        }
+        const content = fs.readFileSync(templateFile, 'utf-8');
+        // Only process .ejs files or text files that might contain EJS tags
+        const ext = path.extname(templateFile);
+        const textExts = [
+            '.ts',
+            '.tsx',
+            '.json',
+            '.yaml',
+            '.yml',
+            '.html',
+            '.css',
+            '.md',
+            '.toml',
+            '.gitignore'
+        ];
+        if (textExts.includes(ext) || ext === '.ejs') {
+            const rendered = ejs.render(content, vars, {
+                filename: templateFile
+            });
+            const finalPath = ext === '.ejs' ? outputPath.replace(/\.ejs$/, '') : outputPath;
+            fs.writeFileSync(finalPath, rendered, 'utf-8');
+        } else {
+            // Binary or unknown — copy as-is
+            fs.copyFileSync(templateFile, outputPath);
+        }
+    }
+    console.log('Project created successfully!\n');
+    console.log('Next steps:');
+    console.log(`  cd ${packageName}`);
+    console.log('  pnpm install');
+    console.log('  pnpm dev:backend    # Start game server');
+    console.log('  pnpm dev:frontend   # Start frontend dev server\n');
+});
+program.parse();
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { program } from 'commander';\nimport * as fs from 'node:fs';\nimport * as path from 'node:path';\nimport * as ejs from 'ejs';\nimport { fileURLToPath } from 'node:url';\n\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = path.dirname(__filename);\n\ninterface CreateOptions {\n  preset: string;\n  port: string;\n  serverPort: string;\n}\n\nfunction toPascalCase(kebab: string): string {\n  return kebab.split('-').map(s => s.charAt(0).toUpperCase() + s.slice(1)).join('');\n}\n\nfunction getTemplatesDir(): string {\n  // In development (source), templates are sibling to src/\n  // In dist, templates are at package root (copied by files field)\n  const devPath = path.resolve(__dirname, '..', 'templates');\n  if (fs.existsSync(devPath)) return devPath;\n  // Fallback for npm install\n  const distPath = path.resolve(__dirname, '..', '..', 'templates');\n  if (fs.existsSync(distPath)) return distPath;\n  throw new Error('Templates directory not found');\n}\n\nfunction walkDir(dir: string): string[] {\n  const results: string[] = [];\n  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {\n    const full = path.join(dir, entry.name);\n    if (entry.isDirectory()) {\n      results.push(...walkDir(full));\n    } else {\n      results.push(full);\n    }\n  }\n  return results;\n}\n\nfunction processPath(filePath: string, vars: Record<string, string>): string {\n  let result = filePath;\n  result = result.replace(/__packageName__/g, vars.packageName);\n  result = result.replace(/__ProjectName__/g, vars.projectName);\n  return result;\n}\n\nprogram\n  .name('create-lagless')\n  .description('Scaffold a new Lagless multiplayer game project')\n  .version('0.0.30')\n  .argument('<project-name>', 'Project name in kebab-case (e.g., my-game)')\n  .option('--preset <preset>', 'Project preset', 'pixi-react')\n  .option('--port <port>', 'Frontend dev server port', '4200')\n  .option('--server-port <port>', 'Backend server port', '3333')\n  .action(async (projectArg: string, options: CreateOptions) => {\n    const targetDir = path.resolve(process.cwd(), projectArg);\n    const packageName = path.basename(targetDir).toLowerCase();\n    const pascalName = toPascalCase(packageName);\n\n    if (fs.existsSync(targetDir)) {\n      console.error(`Error: Directory \"${targetDir}\" already exists.`);\n      process.exit(1);\n    }\n\n    const templatesDir = getTemplatesDir();\n    const presetDir = path.join(templatesDir, options.preset);\n\n    if (!fs.existsSync(presetDir)) {\n      console.error(`Error: Preset \"${options.preset}\" not found. Available: ${fs.readdirSync(templatesDir).join(', ')}`);\n      process.exit(1);\n    }\n\n    // Read package.json from this package to get current lagless version\n    const pkgJsonPath = path.resolve(__dirname, '..', 'package.json');\n    let laglessVersion = '0.0.30';\n    try {\n      const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));\n      laglessVersion = pkg.version || laglessVersion;\n    } catch {\n      // fallback\n    }\n\n    const vars = {\n      projectName: pascalName,\n      packageName,\n      frontendPort: options.port,\n      serverPort: options.serverPort,\n      laglessVersion,\n    };\n\n    console.log(`\\nCreating Lagless project \"${packageName}\"...`);\n    console.log(`  Preset: ${options.preset}`);\n    console.log(`  Frontend port: ${options.port}`);\n    console.log(`  Server port: ${options.serverPort}`);\n    console.log(`  Target: ${targetDir}\\n`);\n\n    const templateFiles = walkDir(presetDir);\n\n    for (const templateFile of templateFiles) {\n      const relativePath = path.relative(presetDir, templateFile);\n      const outputRelative = processPath(relativePath, vars);\n      const outputPath = path.join(targetDir, outputRelative);\n      const outputDir = path.dirname(outputPath);\n\n      if (!fs.existsSync(outputDir)) {\n        fs.mkdirSync(outputDir, { recursive: true });\n      }\n\n      const content = fs.readFileSync(templateFile, 'utf-8');\n\n      // Only process .ejs files or text files that might contain EJS tags\n      const ext = path.extname(templateFile);\n      const textExts = ['.ts', '.tsx', '.json', '.yaml', '.yml', '.html', '.css', '.md', '.toml', '.gitignore'];\n\n      if (textExts.includes(ext) || ext === '.ejs') {\n        const rendered = ejs.render(content, vars, { filename: templateFile });\n        const finalPath = ext === '.ejs' ? outputPath.replace(/\\.ejs$/, '') : outputPath;\n        fs.writeFileSync(finalPath, rendered, 'utf-8');\n      } else {\n        // Binary or unknown — copy as-is\n        fs.copyFileSync(templateFile, outputPath);\n      }\n    }\n\n    console.log('Project created successfully!\\n');\n    console.log('Next steps:');\n    console.log(`  cd ${packageName}`);\n    console.log('  pnpm install');\n    console.log('  pnpm dev:backend    # Start game server');\n    console.log('  pnpm dev:frontend   # Start frontend dev server\\n');\n  });\n\nprogram.parse();\n"],"names":["program","fs","path","ejs","fileURLToPath","__filename","url","__dirname","dirname","toPascalCase","kebab","split","map","s","charAt","toUpperCase","slice","join","getTemplatesDir","devPath","resolve","existsSync","distPath","Error","walkDir","dir","results","entry","readdirSync","withFileTypes","full","name","isDirectory","push","processPath","filePath","vars","result","replace","packageName","projectName","description","version","argument","option","action","projectArg","options","targetDir","process","cwd","basename","toLowerCase","pascalName","console","error","exit","templatesDir","presetDir","preset","pkgJsonPath","laglessVersion","pkg","JSON","parse","readFileSync","frontendPort","port","serverPort","log","templateFiles","templateFile","relativePath","relative","outputRelative","outputPath","outputDir","mkdirSync","recursive","content","ext","extname","textExts","includes","rendered","render","filename","finalPath","writeFileSync","copyFileSync"],"rangeMappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;","mappings":"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"}

package/dist/tsconfig.lib.tsbuildinfo

@@ -0,0 +1 @@
+{"version":"5.9.3"}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@lagless/create",
+  "version": "0.0.33",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ppauel/lagless",
+    "directory": "tools/create"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "create-lagless": "./dist/index.js"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "@lagless/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md"
+  ],
+  "nx": {
+    "sourceRoot": "tools/create/src",
+    "targets": {
+      "build": {
+        "executor": "@nx/js:swc",
+        "outputs": [
+          "{options.outputPath}"
+        ],
+        "options": {
+          "outputPath": "tools/create/dist",
+          "main": "tools/create/src/index.ts",
+          "tsConfig": "tools/create/tsconfig.lib.json",
+          "skipTypeCheck": true,
+          "stripLeadingPaths": true
+        }
+      }
+    }
+  },
+  "dependencies": {
+    "commander": "^14.0.1",
+    "ejs": "^3.1.10",
+    "@swc/helpers": "~0.5.11"
+  },
+  "devDependencies": {
+    "@types/ejs": "^3.1.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/templates/.nxignore

@@ -0,0 +1 @@
+*

package/templates/pixi-react/AGENTS.md

@@ -0,0 +1,41 @@
+# AGENTS.md — Multi-Agent Development Guide
+
+## Project Overview
+
+This is a Lagless multiplayer game with three workspace packages:
+- `<%= packageName %>-simulation` — deterministic ECS logic
+- `<%= packageName %>-frontend` — React + Pixi.js client
+- `<%= packageName %>-backend` — Bun relay server
+
+## Task Decomposition
+
+### Adding a New Game Feature
+
+1. **Schema**: Add components/inputs/filters to `ecs.yaml`, run `pnpm codegen`
+2. **Systems**: Implement game logic as ECS systems in the simulation package
+3. **Rendering**: Add Pixi.js views in the frontend using `filterView` + `FilterViews`
+4. **Server hooks**: Update `game-hooks.ts` if the feature needs server-side events
+
+### Debugging Determinism Issues
+
+- Open two browser tabs, both "Play Online"
+- Press F3 to show debug panel — check hash verification table
+- If hashes diverge: the system running between the two reported hashes has non-deterministic code
+- Common causes: using `Math.random()`, `Date.now()`, `Math.sin()` instead of `MathOps`, uninitialized memory
+
+### Testing Strategy
+
+- **Simulation tests**: Write vitest tests that create a runner, inject RPCs, advance ticks, assert state
+- **Determinism tests**: Run same inputs twice, compare final ArrayBuffer hashes
+- **Visual tests**: Use local play to verify rendering
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `*-simulation/src/lib/schema/ecs.yaml` | ECS data model definition |
+| `*-simulation/src/lib/systems/index.ts` | System execution order |
+| `*-simulation/src/lib/arena.ts` | Game constants |
+| `*-frontend/src/app/game-view/runner-provider.tsx` | Simulation initialization + input draining |
+| `*-frontend/src/app/game-view/game-scene.tsx` | Main Pixi.js scene composition |
+| `*-backend/src/game-hooks.ts` | Server room lifecycle hooks |

package/templates/pixi-react/CLAUDE.md

@@ -0,0 +1,79 @@
+# CLAUDE.md
+
+## 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.
+
+## Commands
+
+```bash
+# Install
+pnpm install
+
+# Start game server (Bun)
+pnpm dev:backend
+
+# Start frontend dev server (Vite)
+pnpm dev:frontend
+
+# Regenerate ECS code after schema changes
+pnpm codegen
+```
+
+## Architecture
+
+### Three Packages
+
+- **<%= 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)
+
+### ECS Memory Model
+
+All state lives in one contiguous ArrayBuffer with Structure-of-Arrays layout. Snapshot = `ArrayBuffer.slice(0)`. Rollback = `Uint8Array.set()` from snapshot.
+
+### Simulation Loop
+
+```
+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
+```
+
+### Input System
+
+RPCs are deterministically ordered by `(playerSlot, ordinal, seq)`. Local inputs are scheduled `currentTick + inputDelay` ticks ahead. Server relays inputs to all clients.
+
+### Key Conventions
+
+- **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)
+
+### Schema & Codegen
+
+ECS schema is defined in `<%= packageName %>-simulation/src/lib/schema/ecs.yaml`. Run `pnpm codegen` after changes.
+
+Supported field types: `uint8`, `uint16`, `uint32`, `int8`, `int16`, `int32`, `float32`, `float64`, `uint8[N]` (fixed arrays).
+
+### Adding Components/Systems
+
+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)
+
+### Multiplayer
+
+- 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)

package/templates/pixi-react/README.md

@@ -0,0 +1,151 @@
+# <%= projectName %>
+
+A multiplayer game built with [Lagless](https://github.com/ppauel/lagless) — a deterministic ECS framework for real-time multiplayer browser games.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) 20+
+- [pnpm](https://pnpm.io/) 9+
+- [Bun](https://bun.sh/) (for the game server)
+
+## Getting Started
+
+```bash
+pnpm install
+
+# Terminal 1 — Start the game server
+pnpm dev:backend
+
+# Terminal 2 — Start the frontend dev server
+pnpm dev:frontend
+```
+
+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).
+
+## Project Structure
+
+```
+<%= packageName %>/
+├── <%= packageName %>-simulation/    # Shared deterministic game logic (ECS)
+│   └── src/lib/
+│       ├── schema/ecs.yaml          # ECS schema definition
+│       ├── schema/code-gen/         # Generated code (don't edit manually)
+│       ├── systems/                 # ECS systems (game logic)
+│       ├── signals/                 # Rollback-aware events
+│       └── arena.ts                 # Game constants
+├── <%= packageName %>-frontend/      # React + Pixi.js game client
+│   └── src/app/
+│       ├── screens/                 # Title screen, game screen
+│       ├── hooks/                   # Match start hooks
+│       └── game-view/              # Pixi.js rendering
+└── <%= packageName %>-backend/       # Bun game server
+    └── src/
+        ├── main.ts                  # Server entry point
+        └── game-hooks.ts           # Room lifecycle hooks
+```
+
+## ECS Schema
+
+The game's data model is defined in `<%= packageName %>-simulation/src/lib/schema/ecs.yaml`. After modifying the schema, regenerate code:
+
+```bash
+pnpm codegen
+```
+
+### Schema Reference
+
+**Components** — Per-entity data stored in Structure-of-Arrays layout:
+```yaml
+components:
+  MyComponent:
+    fieldName: float32    # Supported: uint8, uint16, uint32, int8, int16, int32, float32, float64
+```
+
+**Singletons** — Global game state (single instance):
+```yaml
+singletons:
+  GameState:
+    gamePhase: uint8
+```
+
+**Player Resources** — Per-player data (indexed by player slot):
+```yaml
+playerResources:
+  PlayerResource:
+    score: uint32
+    id: uint8[16]        # Fixed-size arrays supported
+```
+
+**Inputs** — RPCs sent by clients and server:
+```yaml
+inputs:
+  MoveInput:
+    directionX: float32
+    directionY: float32
+```
+
+**Filters** — Cached entity queries:
+```yaml
+filters:
+  PlayerFilter:
+    include: [Transform2d, PlayerBody]
+    # exclude: [Dead]    # Optional
+```
+
+## Adding a New System
+
+1. Create `<%= packageName %>-simulation/src/lib/systems/my-system.system.ts`:
+
+```typescript
+import { ECSSystem, IECSSystem } from '@lagless/core';
+import { Transform2d, PlayerFilter } from '../schema/code-gen/index.js';
+
+@ECSSystem()
+export class MySystem implements IECSSystem {
+  constructor(
+    private readonly _PlayerFilter: PlayerFilter,
+    private readonly _Transform2d: Transform2d,
+  ) {}
+
+  public update(tick: number): void {
+    for (const entity of this._PlayerFilter) {
+      // Your logic here
+    }
+  }
+}
+```
+
+2. Add it to the systems array in `systems/index.ts` (order matters — systems run sequentially).
+
+## Key Conventions
+
+- **Determinism**: All simulation math must use `MathOps` for trig functions (WASM-backed). Never use `Math.sin/cos/atan2/sqrt` in systems.
+- **Interpolation**: Always set `prevPositionX/Y` equal to `positionX/Y` when spawning entities to avoid one-frame jumps.
+- **Vector math**: Use `Vector2.addToRef()`/`.addInPlace()` in hot paths to avoid allocations.
+- **Decorators**: `@abraham/reflection` must be imported before any decorated class (done in `main.tsx`).
+
+## Architecture
+
+- **Server never runs simulation** — it relays inputs between clients
+- **Clients are authoritative on determinism** — same inputs + same seed = identical state
+- **Rollback netcode** — local inputs are predicted, remote inputs trigger rollback when they arrive
+- **State transfer** — late-joining players receive a state snapshot from existing clients
+
+## @lagless Packages
+
+| Package | Description |
+|---------|-------------|
+| `@lagless/core` | ECS engine, simulation loop, input system, signals |
+| `@lagless/binary` | Memory tracking, typed array utilities |
+| `@lagless/math` | Deterministic math (WASM), Vector2 |
+| `@lagless/misc` | Logging, UUID, VisualSmoother2d |
+| `@lagless/net-wire` | Binary network protocol messages |
+| `@lagless/relay-client` | Client-side relay connection, RelayInputProvider |
+| `@lagless/relay-server` | Server-side relay room, RoomHooks |
+| `@lagless/relay-game-server` | Full game server with matchmaking |
+| `@lagless/matchmaking` | Matchmaking queue service |
+| `@lagless/react` | React debug panel, auth utilities |
+| `@lagless/pixi-react` | FilterViews, VFX container, virtual joystick |
+| `@lagless/codegen` | ECS code generation from YAML |

package/templates/pixi-react/__packageName__-backend/bunfig.toml

@@ -0,0 +1,4 @@
+# Bun configuration for game-server
+# @lagless/source condition resolves workspace packages to TypeScript source
+[resolve]
+conditions = ["@lagless/source"]

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

@@ -0,0 +1,19 @@
+{
+  "name": "<%= packageName %>-backend",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "bun --watch run src/main.ts",
+    "start": "bun run src/main.ts"
+  },
+  "dependencies": {
+    "<%= packageName %>-simulation": "workspace:*",
+    "@lagless/relay-game-server": "^<%= laglessVersion %>",
+    "@lagless/misc": "^<%= laglessVersion %>",
+    "reflect-metadata": "^0.2.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  }
+}

package/templates/pixi-react/__packageName__-backend/src/game-hooks.ts

@@ -0,0 +1,47 @@
+import type { RoomHooks, RoomContext, PlayerInfo } from '@lagless/relay-server';
+import { LeaveReason } from '@lagless/relay-server';
+import { createLogger, UUID } from '@lagless/misc';
+import { PlayerJoined, PlayerLeft } from '<%= packageName %>-simulation';
+
+const log = createLogger('<%= projectName %>Hooks');
+
+export const gameHooks: RoomHooks = {
+  onRoomCreated(ctx: RoomContext) {
+    log.info(`[${ctx.matchId}] Room created, ${ctx.getPlayers().length} players`);
+  },
+
+  onPlayerJoin(ctx: RoomContext, player: PlayerInfo) {
+    log.info(`[${ctx.matchId}] Player joined: slot=${player.slot} bot=${player.isBot} id=${player.playerId.slice(0, 8)}`);
+
+    ctx.emitServerEvent(PlayerJoined.id, {
+      playerId: player.isBot
+        ? UUID.generateMasked().asUint8()
+        : UUID.fromString(player.playerId).asUint8(),
+      slot: player.slot,
+    } satisfies PlayerJoined['schema']);
+  },
+
+  onPlayerReconnect(ctx: RoomContext, player: PlayerInfo) {
+    log.info(`[${ctx.matchId}] Player reconnected: slot=${player.slot} id=${player.playerId.slice(0, 8)}`);
+  },
+
+  onPlayerLeave(ctx: RoomContext, player: PlayerInfo, reason: LeaveReason) {
+    log.info(`[${ctx.matchId}] Player left: slot=${player.slot} reason=${LeaveReason[reason]}`);
+    ctx.emitServerEvent(PlayerLeft.id, {
+      slot: player.slot,
+      reason,
+    } satisfies PlayerLeft['schema']);
+  },
+
+  shouldAcceptLateJoin() {
+    return true;
+  },
+
+  shouldAcceptReconnect() {
+    return true;
+  },
+
+  onRoomDisposed(ctx: RoomContext) {
+    log.info(`[${ctx.matchId}] Room disposed`);
+  },
+};

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

@@ -0,0 +1,28 @@
+import 'reflect-metadata';
+import { RelayGameServer } from '@lagless/relay-game-server';
+import { <%= projectName %>InputRegistry } from '<%= packageName %>-simulation';
+import { gameHooks } from './game-hooks.js';
+
+const server = new RelayGameServer({
+  port: Number(process.env.PORT ?? <%= serverPort %>),
+  loggerName: '<%= projectName %>Server',
+  roomType: {
+    name: '<%= packageName %>',
+    config: {
+      maxPlayers: 4,
+      tickRateHz: 60,
+      maxFutureTicks: 20,
+      lateJoinEnabled: true,
+      reconnectTimeoutMs: 30_000,
+      stateTransferTimeoutMs: 5_000,
+    },
+    hooks: gameHooks,
+    inputRegistry: <%= projectName %>InputRegistry,
+  },
+  matchmaking: {
+    scope: '<%= packageName %>',
+    config: { minPlayersToStart: 1, maxPlayers: 4, waitTimeoutMs: 2_000 },
+  },
+});
+
+server.start();

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

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "types": ["bun-types"]
+  },
+  "include": ["src/**/*.ts"]
+}

package/templates/pixi-react/__packageName__-frontend/index.html

@@ -0,0 +1,23 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title><%= projectName %></title>
+    <base href="/" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <link rel="stylesheet" href="/src/styles.css" />
+    <style>
+      html, body {
+        margin: 0;
+        padding: 0;
+        background: #0a0a1a;
+        font-family: 'Courier New', Courier, monospace;
+        color: #e0e0e0;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>