@lagless/create 0.0.46 → 0.0.50

package/dist/index.js

@@ -170,6 +170,10 @@ program.name('create-lagless').description('Scaffold a new Lagless multiplayer g
         const f = path.join(docsDir, '08-physics3d.md');
         if (fs.existsSync(f)) fs.rmSync(f);
     }
+    if (simulationType !== 'physics2d') {
+        const f = path.join(docsDir, '11-2d-map-generation.md');
+        if (fs.existsSync(f)) fs.rmSync(f);
+    }
     // Clone lagless framework source for AI reference
     const sourcesDir = path.join(docsDir, 'sources');
     fs.mkdirSync(sourcesDir, {

package/dist/index.js.map

@@ -1 +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 { execSync } from 'node:child_process';\nimport { fileURLToPath } from 'node:url';\nimport { select } from '@inquirer/prompts';\n\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = path.dirname(__filename);\n\n// Read version from package.json once (single source of truth)\nconst _pkgJsonPath = path.resolve(__dirname, '..', 'package.json');\nlet _packageVersion = '0.0.0';\ntry {\n  const _pkg = JSON.parse(fs.readFileSync(_pkgJsonPath, 'utf-8'));\n  _packageVersion = _pkg.version || _packageVersion;\n} catch {\n  // fallback\n}\n\ntype SimulationType = 'raw' | 'physics2d' | 'physics3d';\n\ninterface CreateOptions {\n  preset: string;\n  port: string;\n  serverPort: string;\n  simulationType?: SimulationType;\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  const devPath = path.resolve(__dirname, '..', 'templates');\n  if (fs.existsSync(devPath)) return devPath;\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\nasync function promptSimulationType(): Promise<SimulationType> {\n  return select<SimulationType>({\n    message: 'Select simulation type:',\n    choices: [\n      { value: 'raw', name: 'Raw ECS', description: 'Manual velocity/position management, no physics engine' },\n      { value: 'physics2d', name: 'Physics 2D (Rapier)', description: 'Rapier 2D rigid body physics with auto-managed transforms' },\n      { value: 'physics3d', name: 'Physics 3D (Rapier)', description: 'Rapier 3D rigid body physics with top-down 2D rendering' },\n    ],\n  });\n}\n\nprogram\n  .name('create-lagless')\n  .description('Scaffold a new Lagless multiplayer game project')\n  .version(_packageVersion)\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', '4203')\n  .option('--server-port <port>', 'Backend server port', '3400')\n  .option('--simulation-type <type>', 'Simulation type: raw, physics2d, or physics3d')\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    // Determine simulation type — from CLI flag or interactive prompt\n    let simulationType: SimulationType;\n    if (options.simulationType) {\n      const valid: SimulationType[] = ['raw', 'physics2d', 'physics3d'];\n      if (!valid.includes(options.simulationType as SimulationType)) {\n        console.error(`Error: Invalid simulation type \"${options.simulationType}\". Valid: ${valid.join(', ')}`);\n        process.exit(1);\n      }\n      simulationType = options.simulationType as SimulationType;\n    } else {\n      simulationType = await promptSimulationType();\n    }\n\n    const laglessVersion = _packageVersion;\n\n    const vars: Record<string, string> = {\n      projectName: pascalName,\n      packageName,\n      frontendPort: options.port,\n      serverPort: options.serverPort,\n      laglessVersion,\n      simulationType,\n    };\n\n    console.log(`\\nCreating Lagless project \"${packageName}\"...`);\n    console.log(`  Preset: ${options.preset}`);\n    console.log(`  Simulation: ${simulationType}`);\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      const content = fs.readFileSync(templateFile, 'utf-8');\n\n      // Only process 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\n        // Skip writing empty/whitespace-only files (conditional template exclusion)\n        if (rendered.trim().length === 0) {\n          continue;\n        }\n\n        if (!fs.existsSync(outputDir)) {\n          fs.mkdirSync(outputDir, { recursive: true });\n        }\n        fs.writeFileSync(finalPath, rendered, 'utf-8');\n      } else {\n        // Binary or unknown — copy as-is\n        if (!fs.existsSync(outputDir)) {\n          fs.mkdirSync(outputDir, { recursive: true });\n        }\n        fs.copyFileSync(templateFile, outputPath);\n      }\n    }\n\n    // Remove physics docs that don't match the selected simulationType\n    const docsDir = path.join(targetDir, 'docs');\n    if (simulationType !== 'physics2d') {\n      const f = path.join(docsDir, '08-physics2d.md');\n      if (fs.existsSync(f)) fs.rmSync(f);\n    }\n    if (simulationType !== 'physics3d') {\n      const f = path.join(docsDir, '08-physics3d.md');\n      if (fs.existsSync(f)) fs.rmSync(f);\n    }\n\n    // Clone lagless framework source for AI reference\n    const sourcesDir = path.join(docsDir, 'sources');\n    fs.mkdirSync(sourcesDir, { recursive: true });\n    console.log('Cloning lagless framework source for AI reference...');\n    try {\n      execSync(`git clone --depth 1 https://github.com/GbGr/lagless.git \"${path.join(sourcesDir, 'lagless')}\"`, {\n        stdio: 'inherit',\n      });\n      // Remove .git to save space\n      fs.rmSync(path.join(sourcesDir, 'lagless', '.git'), { recursive: true, force: true });\n    } catch {\n      console.warn('Warning: Could not clone lagless source. AI reference will be unavailable.');\n      console.warn('You can manually clone later: git clone --depth 1 https://github.com/GbGr/lagless.git docs/sources/lagless');\n    }\n\n    // Install dependencies\n    console.log('\\nInstalling dependencies...');\n    try {\n      execSync('pnpm install', { cwd: targetDir, stdio: 'inherit' });\n    } catch {\n      console.error('Warning: pnpm install failed. Run it manually after creation.');\n    }\n\n    // Run ECS codegen to generate code from schema\n    console.log('\\nGenerating ECS code from schema...');\n    try {\n      execSync('pnpm codegen', { cwd: targetDir, stdio: 'inherit' });\n    } catch {\n      console.error('Warning: codegen failed. Run \"pnpm codegen\" manually after creation.');\n    }\n\n    console.log('\\nProject created successfully!\\n');\n    console.log('To start developing:');\n    console.log(`  cd ${packageName}`);\n    console.log('  pnpm dev               # Start backend + frontend + dev-player\\n');\n    console.log('Or run individually:');\n    console.log('  pnpm dev:backend       # Game server (Bun, watches for changes)');\n    console.log('  pnpm dev:frontend      # Frontend (Vite HMR)');\n    console.log('  pnpm dev:player        # Dev-player (multiplayer testing, port 4210)\\n');\n    console.log('To regenerate ECS code after schema changes:');\n    console.log('  pnpm codegen\\n');\n  });\n\nprogram.parse();\n"],"names":["program","fs","path","ejs","execSync","fileURLToPath","select","__filename","url","__dirname","dirname","_pkgJsonPath","resolve","_packageVersion","_pkg","JSON","parse","readFileSync","version","toPascalCase","kebab","split","map","s","charAt","toUpperCase","slice","join","getTemplatesDir","devPath","existsSync","distPath","Error","walkDir","dir","results","entry","readdirSync","withFileTypes","full","name","isDirectory","push","processPath","filePath","vars","result","replace","packageName","projectName","promptSimulationType","message","choices","value","description","argument","option","action","projectArg","options","targetDir","process","cwd","basename","toLowerCase","pascalName","console","error","exit","templatesDir","presetDir","preset","simulationType","valid","includes","laglessVersion","frontendPort","port","serverPort","log","templateFiles","templateFile","relativePath","relative","outputRelative","outputPath","outputDir","content","ext","extname","textExts","rendered","render","filename","finalPath","trim","length","mkdirSync","recursive","writeFileSync","copyFileSync","docsDir","f","rmSync","sourcesDir","stdio","force","warn"],"rangeMappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;","mappings":"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"}
+{"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 { execSync } from 'node:child_process';\nimport { fileURLToPath } from 'node:url';\nimport { select } from '@inquirer/prompts';\n\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = path.dirname(__filename);\n\n// Read version from package.json once (single source of truth)\nconst _pkgJsonPath = path.resolve(__dirname, '..', 'package.json');\nlet _packageVersion = '0.0.0';\ntry {\n  const _pkg = JSON.parse(fs.readFileSync(_pkgJsonPath, 'utf-8'));\n  _packageVersion = _pkg.version || _packageVersion;\n} catch {\n  // fallback\n}\n\ntype SimulationType = 'raw' | 'physics2d' | 'physics3d';\n\ninterface CreateOptions {\n  preset: string;\n  port: string;\n  serverPort: string;\n  simulationType?: SimulationType;\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  const devPath = path.resolve(__dirname, '..', 'templates');\n  if (fs.existsSync(devPath)) return devPath;\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\nasync function promptSimulationType(): Promise<SimulationType> {\n  return select<SimulationType>({\n    message: 'Select simulation type:',\n    choices: [\n      { value: 'raw', name: 'Raw ECS', description: 'Manual velocity/position management, no physics engine' },\n      { value: 'physics2d', name: 'Physics 2D (Rapier)', description: 'Rapier 2D rigid body physics with auto-managed transforms' },\n      { value: 'physics3d', name: 'Physics 3D (Rapier)', description: 'Rapier 3D rigid body physics with top-down 2D rendering' },\n    ],\n  });\n}\n\nprogram\n  .name('create-lagless')\n  .description('Scaffold a new Lagless multiplayer game project')\n  .version(_packageVersion)\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', '4203')\n  .option('--server-port <port>', 'Backend server port', '3400')\n  .option('--simulation-type <type>', 'Simulation type: raw, physics2d, or physics3d')\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    // Determine simulation type — from CLI flag or interactive prompt\n    let simulationType: SimulationType;\n    if (options.simulationType) {\n      const valid: SimulationType[] = ['raw', 'physics2d', 'physics3d'];\n      if (!valid.includes(options.simulationType as SimulationType)) {\n        console.error(`Error: Invalid simulation type \"${options.simulationType}\". Valid: ${valid.join(', ')}`);\n        process.exit(1);\n      }\n      simulationType = options.simulationType as SimulationType;\n    } else {\n      simulationType = await promptSimulationType();\n    }\n\n    const laglessVersion = _packageVersion;\n\n    const vars: Record<string, string> = {\n      projectName: pascalName,\n      packageName,\n      frontendPort: options.port,\n      serverPort: options.serverPort,\n      laglessVersion,\n      simulationType,\n    };\n\n    console.log(`\\nCreating Lagless project \"${packageName}\"...`);\n    console.log(`  Preset: ${options.preset}`);\n    console.log(`  Simulation: ${simulationType}`);\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      const content = fs.readFileSync(templateFile, 'utf-8');\n\n      // Only process 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\n        // Skip writing empty/whitespace-only files (conditional template exclusion)\n        if (rendered.trim().length === 0) {\n          continue;\n        }\n\n        if (!fs.existsSync(outputDir)) {\n          fs.mkdirSync(outputDir, { recursive: true });\n        }\n        fs.writeFileSync(finalPath, rendered, 'utf-8');\n      } else {\n        // Binary or unknown — copy as-is\n        if (!fs.existsSync(outputDir)) {\n          fs.mkdirSync(outputDir, { recursive: true });\n        }\n        fs.copyFileSync(templateFile, outputPath);\n      }\n    }\n\n    // Remove physics docs that don't match the selected simulationType\n    const docsDir = path.join(targetDir, 'docs');\n    if (simulationType !== 'physics2d') {\n      const f = path.join(docsDir, '08-physics2d.md');\n      if (fs.existsSync(f)) fs.rmSync(f);\n    }\n    if (simulationType !== 'physics3d') {\n      const f = path.join(docsDir, '08-physics3d.md');\n      if (fs.existsSync(f)) fs.rmSync(f);\n    }\n    if (simulationType !== 'physics2d') {\n      const f = path.join(docsDir, '11-2d-map-generation.md');\n      if (fs.existsSync(f)) fs.rmSync(f);\n    }\n\n    // Clone lagless framework source for AI reference\n    const sourcesDir = path.join(docsDir, 'sources');\n    fs.mkdirSync(sourcesDir, { recursive: true });\n    console.log('Cloning lagless framework source for AI reference...');\n    try {\n      execSync(`git clone --depth 1 https://github.com/GbGr/lagless.git \"${path.join(sourcesDir, 'lagless')}\"`, {\n        stdio: 'inherit',\n      });\n      // Remove .git to save space\n      fs.rmSync(path.join(sourcesDir, 'lagless', '.git'), { recursive: true, force: true });\n    } catch {\n      console.warn('Warning: Could not clone lagless source. AI reference will be unavailable.');\n      console.warn('You can manually clone later: git clone --depth 1 https://github.com/GbGr/lagless.git docs/sources/lagless');\n    }\n\n    // Install dependencies\n    console.log('\\nInstalling dependencies...');\n    try {\n      execSync('pnpm install', { cwd: targetDir, stdio: 'inherit' });\n    } catch {\n      console.error('Warning: pnpm install failed. Run it manually after creation.');\n    }\n\n    // Run ECS codegen to generate code from schema\n    console.log('\\nGenerating ECS code from schema...');\n    try {\n      execSync('pnpm codegen', { cwd: targetDir, stdio: 'inherit' });\n    } catch {\n      console.error('Warning: codegen failed. Run \"pnpm codegen\" manually after creation.');\n    }\n\n    console.log('\\nProject created successfully!\\n');\n    console.log('To start developing:');\n    console.log(`  cd ${packageName}`);\n    console.log('  pnpm dev               # Start backend + frontend + dev-player\\n');\n    console.log('Or run individually:');\n    console.log('  pnpm dev:backend       # Game server (Bun, watches for changes)');\n    console.log('  pnpm dev:frontend      # Frontend (Vite HMR)');\n    console.log('  pnpm dev:player        # Dev-player (multiplayer testing, port 4210)\\n');\n    console.log('To regenerate ECS code after schema changes:');\n    console.log('  pnpm codegen\\n');\n  });\n\nprogram.parse();\n"],"names":["program","fs","path","ejs","execSync","fileURLToPath","select","__filename","url","__dirname","dirname","_pkgJsonPath","resolve","_packageVersion","_pkg","JSON","parse","readFileSync","version","toPascalCase","kebab","split","map","s","charAt","toUpperCase","slice","join","getTemplatesDir","devPath","existsSync","distPath","Error","walkDir","dir","results","entry","readdirSync","withFileTypes","full","name","isDirectory","push","processPath","filePath","vars","result","replace","packageName","projectName","promptSimulationType","message","choices","value","description","argument","option","action","projectArg","options","targetDir","process","cwd","basename","toLowerCase","pascalName","console","error","exit","templatesDir","presetDir","preset","simulationType","valid","includes","laglessVersion","frontendPort","port","serverPort","log","templateFiles","templateFile","relativePath","relative","outputRelative","outputPath","outputDir","content","ext","extname","textExts","rendered","render","filename","finalPath","trim","length","mkdirSync","recursive","writeFileSync","copyFileSync","docsDir","f","rmSync","sourcesDir","stdio","force","warn"],"rangeMappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;","mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lagless/create",
-  "version": "0.0.46",
+  "version": "0.0.50",
   "license": "CC-BY-NC-4.0",
   "repository": {
     "type": "git",

package/templates/pixi-react/CLAUDE.md

@@ -240,6 +240,9 @@ Systems run in array order every tick. Canonical ordering:
 <% } else if (simulationType === 'physics3d') { -%>
 | [docs/08-physics3d.md](docs/08-physics3d.md) | Rapier 3D integration, character controller, animation |
 <% } -%>
+<% if (simulationType === 'physics2d') { -%>
+| [docs/11-2d-map-generation.md](docs/11-2d-map-generation.md) | Procedural 2D map generation, terrain rendering, object placement |
+<% } -%>
 | [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 |

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

@@ -20,7 +20,7 @@
 <% if (simulationType === 'physics2d') { -%>
     "@lagless/physics2d": "^<%= laglessVersion %>",
     "@lagless/physics-shared": "^<%= laglessVersion %>",
-    "@dimforge/rapier2d-deterministic-compat": "^0.19.0",
+    "@lagless/rapier2d-deterministic-compat": "^0.19.0",
 <% } else if (simulationType === 'physics3d') { -%>
     "@lagless/physics3d": "^<%= laglessVersion %>",
     "@lagless/physics-shared": "^<%= laglessVersion %>",

package/templates/pixi-react/__packageName__-frontend/src/app/components/debug-panel.tsx

@@ -1,7 +1,6 @@
 import { FC } from 'react';
 import { useRunner } from '../game-view/runner-provider';
 import { DebugPanel as SharedDebugPanel } from '@lagless/react';
-import { PlayerResource, DivergenceSignal } from '<%= packageName %>-simulation';
 
 export const DebugPanel: FC = () => {
   const runner = useRunner();
@@ -9,10 +8,6 @@ export const DebugPanel: FC = () => {
   return (
     <SharedDebugPanel
       runner={runner}
-      hashVerification={{
-        playerResourceClass: PlayerResource,
-        divergenceSignalClass: DivergenceSignal,
-      }}
     />
   );
 };

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

@@ -2,13 +2,11 @@ import {
   <%= projectName %>Runner,
   <%= projectName %>Systems,
   <%= projectName %>Signals,
-  DivergenceSignal,
   MoveInput,
   PlayerJoined,
-  ReportHash,
   <%= projectName %>Arena,
 } from '<%= packageName %>-simulation';
-import { createContext, FC, ReactNode, useContext, useEffect, useState } from 'react';
+import { createContext, FC, ReactNode, useContext, useEffect, useRef, useState } from 'react';
 import { useTick } from '@pixi/react';
 import { useNavigate } from 'react-router-dom';
 import { ProviderStore } from '../hooks/use-start-match';
@@ -16,7 +14,7 @@ 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';
+import { useDevBridge, useDiagnosticsControl } from '@lagless/react';
 <% if (simulationType === 'physics2d') { -%>
 import { PhysicsWorldManager2d, type RapierModule2d } from '@lagless/physics2d';
 <% } else if (simulationType === 'physics3d') { -%>
@@ -41,6 +39,9 @@ export const RunnerProvider: FC<RunnerProviderProps> = ({ children }) => {
   const [runner, setRunner] = useState<<%= projectName %>Runner>(null!);
   const [v, setV] = useState(0);
   const navigate = useNavigate();
+  const diagnosticsEnabled = useDiagnosticsControl();
+  const hashReporterRef = useRef<ReturnType<typeof createHashReporter> | null>(null);
+  const connectionRef = useRef<RelayConnection | null>(null);
 
   useEffect(() => {
     return ProviderStore.onProvider(() => {
@@ -75,7 +76,7 @@ export const RunnerProvider: FC<RunnerProviderProps> = ({ children }) => {
 <% if (simulationType === 'physics2d') { -%>
       // Load Rapier 2D WASM
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      const RAPIER = (await import('@dimforge/rapier2d-deterministic-compat')).default as any;
+      const RAPIER = (await import('@lagless/rapier2d-deterministic-compat')).default as any;
       await RAPIER.init();
       const rapier = RAPIER as unknown as RapierModule2d;
       if (disposed) { inputProvider.dispose(); return; }
@@ -105,11 +106,13 @@ export const RunnerProvider: FC<RunnerProviderProps> = ({ children }) => {
               onPong: (data) => inputProvider.handlePong(data),
               onStateRequest: (requestId) => inputProvider.handleStateRequest(requestId),
               onStateResponse: (data) => inputProvider.handleStateResponse(data),
+              onHashMismatch: (data) => hashReporterRef.current?.reportMismatch(data),
               onConnected: () => console.log('[Relay] Connected'),
               onDisconnected: () => console.log('[Relay] Disconnected'),
             },
           );
 
+          connectionRef.current = _connection;
           inputProvider.setConnection(_connection);
           _connection.connect();
 
@@ -137,12 +140,6 @@ export const RunnerProvider: FC<RunnerProviderProps> = ({ children }) => {
 <% } -%>
       }
 
-      // Set up keyboard input drainer with hash reporting
-      const reportHash = createHashReporter(_runner, {
-        reportInterval: <%= projectName %>Arena.hashReportInterval,
-        reportHashRpc: ReportHash,
-      });
-
       inputProvider.drainInputs((addRPC) => {
         let dx = 0;
         let dy = 0;
@@ -158,11 +155,8 @@ export const RunnerProvider: FC<RunnerProviderProps> = ({ children }) => {
           }
           addRPC(MoveInput, { directionX: dx, directionY: dy });
         }
-
-        reportHash(addRPC);
       });
 
-      _runner.Simulation.enableHashTracking(<%= projectName %>Arena.hashReportInterval);
       _runner.start();
 
       if (inputProvider instanceof RelayInputProvider) {
@@ -186,11 +180,6 @@ export const RunnerProvider: FC<RunnerProviderProps> = ({ children }) => {
         inputProvider.addRemoteRpc(joinRpc);
       }
 
-      const divergenceSignal = _runner.DIContainer.resolve(DivergenceSignal);
-      divergenceSignal.Predicted.subscribe((e) => {
-        console.warn(`[DIVERGENCE] Players ${e.data.slotA} vs ${e.data.slotB}: hash ${e.data.hashA} != ${e.data.hashB} at tick ${e.data.atTick}`);
-      });
-
       setRunner(_runner);
     })();
 
@@ -198,12 +187,36 @@ export const RunnerProvider: FC<RunnerProviderProps> = ({ children }) => {
       disposed = true;
       window.removeEventListener('keydown', onKeyDown);
       window.removeEventListener('keyup', onKeyUp);
+      connectionRef.current = null;
       _connection?.disconnect();
       _runner?.dispose();
     };
   }, [v, navigate]);
 
-  useDevBridge(runner, { hashTrackingInterval: <%= projectName %>Arena.hashReportInterval });
+  // Diagnostics lifecycle: enable/disable hash tracking and hash reporter based on toggle
+  useEffect(() => {
+    if (!runner || !diagnosticsEnabled) {
+      runner?.Simulation.disableHashTracking();
+      hashReporterRef.current?.dispose();
+      hashReporterRef.current = null;
+      return;
+    }
+    runner.Simulation.enableHashTracking(<%= projectName %>Arena.hashReportInterval);
+    const reporter = createHashReporter(runner, {
+      reportInterval: <%= projectName %>Arena.hashReportInterval,
+      send: (data) => connectionRef.current?.sendHashReport(data),
+    });
+    reporter.subscribeDivergence((data) => {
+      console.warn(`[DIVERGENCE] Players ${data.slotA} vs ${data.slotB}: hash ${data.hashA} != ${data.hashB} at tick ${data.atTick}`);
+    });
+    hashReporterRef.current = reporter;
+    return () => {
+      reporter.dispose();
+      hashReporterRef.current = null;
+    };
+  }, [runner, diagnosticsEnabled]);
+
+  useDevBridge(runner, { hashTrackingInterval: <%= projectName %>Arena.hashReportInterval, diagnosticsEnabled });
 
   return !runner ? null : <RunnerContext.Provider value={runner}>{children}</RunnerContext.Provider>;
 };

package/templates/pixi-react/__packageName__-simulation/src/lib/schema/ecs.yaml

@@ -24,9 +24,6 @@ playerResources:
     id: uint8[16]
     entity: uint32
     connected: uint8
-    lastReportedHash: uint32
-    lastReportedHashTick: uint32
-    hashMismatchCount: uint16
 
 inputs:
   PlayerJoined:
@@ -38,9 +35,6 @@ inputs:
   MoveInput:
     directionX: float32
     directionY: float32
-  ReportHash:
-    hash: uint32
-    atTick: uint32
 
 filters:
   PlayerFilter:
@@ -69,9 +63,6 @@ playerResources:
     id: uint8[16]
     entity: uint32
     connected: uint8
-    lastReportedHash: uint32
-    lastReportedHashTick: uint32
-    hashMismatchCount: uint16
 
 inputs:
   PlayerJoined:
@@ -83,9 +74,6 @@ inputs:
   MoveInput:
     directionX: float32
     directionY: float32
-  ReportHash:
-    hash: uint32
-    atTick: uint32
 
 filters:
   PlayerFilter:
@@ -112,9 +100,6 @@ playerResources:
     id: uint8[16]
     entity: uint32
     connected: uint8
-    lastReportedHash: uint32
-    lastReportedHashTick: uint32
-    hashMismatchCount: uint16
 
 inputs:
   PlayerJoined:
@@ -126,9 +111,6 @@ inputs:
   MoveInput:
     directionX: float32
     directionY: float32
-  ReportHash:
-    hash: uint32
-    atTick: uint32
 
 filters:
   PlayerFilter:

package/templates/pixi-react/__packageName__-simulation/src/lib/signals/index.ts

@@ -1,5 +1,3 @@
-import { ISignalConstructor, DivergenceSignal } from '@lagless/core';
+import { ISignalConstructor } from '@lagless/core';
 
-export { DivergenceSignal, type DivergenceData } from '@lagless/core';
-
-export const <%= projectName %>Signals: ISignalConstructor[] = [DivergenceSignal];
+export const <%= projectName %>Signals: ISignalConstructor[] = [];

package/templates/pixi-react/__packageName__-simulation/src/lib/systems/index.ts

@@ -10,7 +10,6 @@ import { BoundarySystem } from './boundary.system.js';
 <% } else { -%>
 import { PhysicsStepSystem } from './physics-step.system.js';
 <% } -%>
-import { HashVerificationSystem } from './hash-verification.system.js';
 
 export const <%= projectName %>Systems: IECSSystemConstructor[] = [
   SavePrevTransformSystem,
@@ -24,5 +23,4 @@ export const <%= projectName %>Systems: IECSSystemConstructor[] = [
 <% } else { -%>
   PhysicsStepSystem,
 <% } -%>
-  HashVerificationSystem,
 ];

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

@@ -360,3 +360,63 @@ export class ProjectileLifetimeSystem implements IECSSystem {
      this._arenaConfig.radius -= this._arenaConfig.shrinkRate;
    }
    ```
+<% if (simulationType === 'physics2d') { -%>
+
+## Add Procedural 2D Map
+
+1. **Install packages:**
+   ```bash
+   pnpm add @lagless/2d-map-generator @lagless/2d-map-renderer
+   ```
+
+2. **Define object types** in `simulation/src/lib/map-config/objects.ts`:
+   ```typescript
+   import type { MapObjectDef, MapObjectRegistry } from '@lagless/2d-map-generator';
+   import { RenderLayer, ShapeType, CANOPY_SENSOR_TAG } from '@lagless/2d-map-generator';
+
+   export enum ObjectType { Tree = 0 }
+
+   const TREE: MapObjectDef = {
+     typeId: ObjectType.Tree,
+     colliders: [
+       { shape: { type: ShapeType.Circle, radius: 30 } },
+       { shape: { type: ShapeType.Circle, radius: 128 }, isSensor: true, tag: CANOPY_SENSOR_TAG },
+     ],
+     visuals: [
+       { texture: 'tree-trunk', layer: RenderLayer.Ground },
+       { texture: 'tree-foliage', layer: RenderLayer.Canopy },
+     ],
+     scaleRange: [0.1, 0.2],
+     includeSensorsInBounds: true,
+   };
+
+   export const OBJECT_REGISTRY: MapObjectRegistry = new Map([[0, TREE]]);
+   ```
+
+3. **Create generator factory** in `simulation/src/lib/map-config/create-map-generator.ts`:
+   ```typescript
+   import { MapGenerator, BiomeFeature, ShoreFeature, GrassFeature,
+     ObjectPlacementFeature, PlacementKind, TerrainZone, STANDARD_BIOME,
+   } from '@lagless/2d-map-generator';
+   import { OBJECT_REGISTRY, ObjectType } from './objects.js';
+
+   export function createMapGenerator(): MapGenerator {
+     return new MapGenerator({ baseWidth: 720, baseHeight: 720, scale: 1, extension: 80, gridSize: 16 })
+       .addFeature(new BiomeFeature(), STANDARD_BIOME)
+       .addFeature(new ShoreFeature(), { inset: 48, divisions: 12, variation: 4 })
+       .addFeature(new GrassFeature(), { inset: 18, variation: 3 })
+       .addFeature(new ObjectPlacementFeature(), {
+         registry: OBJECT_REGISTRY,
+         stages: [{ kind: PlacementKind.Density, typeId: ObjectType.Tree, density: 100, terrainZone: TerrainZone.Grass }],
+       });
+   }
+   ```
+
+4. **Extend runner** — generate map + create physics colliders in constructor, call `capturePreStartState()` after.
+
+5. **Render** — use `MapTerrainRenderer` and `MapObjectRenderer` from `@lagless/2d-map-renderer`.
+
+6. **Canopy transparency** — use `extractCanopyZones()` + `isInsideCanopyZone()` per frame.
+
+> Full details: [docs/11-2d-map-generation.md](11-2d-map-generation.md)
+<% } -%>

package/templates/pixi-react/docs/11-2d-map-generation.md

@@ -0,0 +1,707 @@
+# 2D Map Generation
+
+## Overview
+
+`@lagless/2d-map-generator` produces deterministic 2D maps from a seed using a feature pipeline. `@lagless/2d-map-renderer` renders those maps using Pixi.js. Together they provide procedural terrain, rivers, lakes, object placement, and rendering for top-down 2D games.
+
+**Key properties:**
+- **Deterministic** — same seed + same config = identical map on every client (uses `MathOps` trig, `ISeededRandom`)
+- **Feature-based** — compose terrain, water, objects via independent features with automatic dependency resolution
+- **Physics-integrated** — `createMapColliders()` converts placed objects into Rapier 2D rigid bodies
+- **Render-ready** — `MapTerrainRenderer` and `MapObjectRenderer` output Pixi.js containers
+
+## Installation
+
+```bash
+pnpm add @lagless/2d-map-generator @lagless/2d-map-renderer
+```
+
+Both packages are peer dependencies — they are NOT included by default. Add them when your game needs procedural map generation.
+
+## Architecture
+
+```
+MapGenerator
+  ├── addFeature(feature, config)   // register features
+  └── generate(random, collision)   // run all features in dependency order
+        │
+        ├── BiomeFeature        → BiomeOutput (color palette)
+        ├── ShoreFeature        → ShoreOutput (island shore polygon)
+        ├── GrassFeature        → GrassOutput (grass area polygon)
+        ├── RiverFeature        → RiverOutput (river polygons)
+        ├── LakeFeature         → LakeOutput (lake polygons)
+        ├── BridgeFeature       → BridgeOutput (bridge placements)
+        ├── ObjectPlacementFeature → ObjectPlacementOutput (placed objects)
+        ├── GroundPatchFeature  → GroundPatchOutput (ground patches)
+        └── PlacesFeature       → PlacesOutput (named positions)
+```
+
+Features declare dependencies via `requires`. The generator resolves them with topological sort — no manual ordering needed. You only add the features your game needs.
+
+## Integration Flow
+
+The full integration spans three layers:
+
+```
+1. Simulation (runner constructor)
+   └── MapGenerator.generate() → IGeneratedMap
+   └── createMapColliders() → Rapier 2D physics bodies
+   └── capturePreStartState() → snapshot includes map colliders
+
+2. DI Bridge
+   └── MapData class registered via extraRegistrations
+   └── Systems access map data via DI constructor injection
+
+3. Client (React/Pixi.js)
+   └── MapTerrainRenderer.buildTerrain() → terrain container
+   └── MapObjectRenderer.build() → ground + canopy ParticleContainers
+   └── extractCanopyZones() + isInsideCanopyZone() → per-frame transparency
+```
+
+## Setting Up the Generator
+
+### Step 1: Define Object Types and Registry
+
+Create a file in your simulation package (e.g., `map-config/objects.ts`):
+
+```typescript
+import type { MapObjectDef, MapObjectRegistry } from '@lagless/2d-map-generator';
+import { RenderLayer, ShapeType, CANOPY_SENSOR_TAG } from '@lagless/2d-map-generator';
+
+export enum ObjectType { Tree = 0, Building = 1 }
+
+const TREE: MapObjectDef = {
+  typeId: ObjectType.Tree,
+  colliders: [
+    { shape: { type: ShapeType.Circle, radius: 30 } },
+    // Sensor for canopy transparency zone (view-only, skipped by createMapColliders)
+    { shape: { type: ShapeType.Circle, radius: 128 }, isSensor: true, tag: CANOPY_SENSOR_TAG },
+  ],
+  visuals: [
+    { texture: 'tree-trunk', layer: RenderLayer.Ground },
+    { texture: 'tree-foliage', layer: RenderLayer.Canopy },
+  ],
+  scaleRange: [0.1, 0.2],
+  // Include sensor radius in placement bounds (prevents canopy overlap)
+  includeSensorsInBounds: true,
+  // Optional: minimap display
+  mapDisplay: {
+    shapes: [
+      { collider: { type: ShapeType.Circle, radius: 30 }, color: 0x2d5a1e, scale: 1 },
+    ],
+  },
+};
+
+const BUILDING: MapObjectDef = {
+  typeId: ObjectType.Building,
+  colliders: [
+    { shape: { type: ShapeType.Cuboid, halfWidth: 30, halfHeight: 20 } },
+    { shape: { type: ShapeType.Cuboid, halfWidth: 30, halfHeight: 20 }, isSensor: true, tag: CANOPY_SENSOR_TAG },
+  ],
+  visuals: [
+    { texture: 'building-floor', layer: RenderLayer.Ground },
+    { texture: 'building-roof', layer: RenderLayer.Canopy },
+  ],
+  scaleRange: [1, 1],
+  groundPatches: [
+    {
+      offset: { x: 0, y: 0 },
+      halfExtents: { x: 32, y: 22 },
+      color: 0x8b4513,
+      roughness: 0.5,
+      offsetDist: 2,
+      order: 0,
+      useAsMapShape: false,
+    },
+  ],
+};
+
+export const OBJECT_REGISTRY: MapObjectRegistry = new Map<number, MapObjectDef>([
+  [ObjectType.Tree, TREE],
+  [ObjectType.Building, BUILDING],
+]);
+```
+
+### Step 2: Create Map Generator Factory
+
+Create `map-config/create-map-generator.ts`:
+
+```typescript
+import {
+  MapGenerator, BiomeFeature, ShoreFeature, GrassFeature,
+  RiverFeature, LakeFeature, ObjectPlacementFeature,
+  PlacementKind, TerrainZone, STANDARD_BIOME,
+} from '@lagless/2d-map-generator';
+import { OBJECT_REGISTRY, ObjectType } from './objects.js';
+
+export function createMapGenerator(): MapGenerator {
+  const generator = new MapGenerator({
+    baseWidth: 720,
+    baseHeight: 720,
+    scale: 1.0,
+    extension: 80,
+    gridSize: 16,
+  });
+
+  generator
+    .addFeature(new BiomeFeature(), STANDARD_BIOME)
+    .addFeature(new ShoreFeature(), { inset: 48, divisions: 12, variation: 4 })
+    .addFeature(new GrassFeature(), { inset: 18, variation: 3 })
+    .addFeature(new RiverFeature(), {
+      weights: [
+        { weight: 0.25, widths: [8, 4] },
+        { weight: 0.75, widths: [4] },
+      ],
+      subdivisionPasses: 5,
+      masks: [],
+    })
+    .addFeature(new LakeFeature(), {
+      lakes: [{ odds: 1.0, innerRad: 30, outerRad: 200, spawnBound: { pos: { x: 0.5, y: 0.5 }, rad: 300 } }],
+    })
+    .addFeature(new ObjectPlacementFeature(), {
+      registry: OBJECT_REGISTRY,
+      stages: [
+        { kind: PlacementKind.Density, typeId: ObjectType.Tree, density: 100, terrainZone: TerrainZone.Grass },
+        { kind: PlacementKind.Fixed, typeId: ObjectType.Building, count: 3, terrainZone: TerrainZone.Grass },
+      ],
+    });
+
+  return generator;
+}
+```
+
+### Step 3: Create MapData DI Token
+
+Create `map-data.ts` in your simulation:
+
+```typescript
+import type { IGeneratedMap, MapObjectRegistry } from '@lagless/2d-map-generator';
+
+export class MapData {
+  map!: IGeneratedMap;
+  registry!: MapObjectRegistry;
+}
+```
+
+### Step 4: Extend Runner with Map Generation
+
+Create a runner subclass that generates the map and creates physics colliders:
+
+```typescript
+import { AbstractInputProvider, ECSConfig, PRNG } from '@lagless/core';
+import { PhysicsConfig2d, PhysicsWorldManager2d, type RapierModule2d, RapierRigidBody2d } from '@lagless/physics2d';
+import {
+  SpatialGridCollisionProvider, ObjectPlacementFeature,
+  createMapColliders, CANOPY_SENSOR_TAG,
+} from '@lagless/2d-map-generator';
+import type { ObjectPlacementOutput, MapPhysicsProvider } from '@lagless/2d-map-generator';
+import { createMapGenerator } from './map-config/create-map-generator.js';
+import { OBJECT_REGISTRY } from './map-config/objects.js';
+import { MyGameRunner } from './schema/code-gen/MyGame.runner.js';
+import { MyGameSystems } from './systems/index.js';
+import { MyGameSignals } from './signals/index.js';
+import { MapData } from './map-data.js';
+
+function createPhysicsAdapter(wm: PhysicsWorldManager2d, rapier: RapierModule2d): MapPhysicsProvider {
+  return {
+    createFixedBody(x, y, rotation) {
+      const desc = rapier.RigidBodyDesc.fixed().setTranslation(x, y).setRotation(rotation);
+      return wm.createBodyFromDesc(desc);
+    },
+    createCircleCollider(body, radius, ox, oy, isSensor, _tag, collisionGroup) {
+      let desc = rapier.ColliderDesc.ball(radius).setTranslation(ox, oy).setSensor(isSensor);
+      if (collisionGroup != null) desc = desc.setCollisionGroups(collisionGroup);
+      wm.createColliderFromDesc(desc, body as RapierRigidBody2d);
+    },
+    createCuboidCollider(body, hw, hh, ox, oy, isSensor, _tag, collisionGroup) {
+      let desc = rapier.ColliderDesc.cuboid(hw, hh).setTranslation(ox, oy).setSensor(isSensor);
+      if (collisionGroup != null) desc = desc.setCollisionGroups(collisionGroup);
+      wm.createColliderFromDesc(desc, body as RapierRigidBody2d);
+    },
+  };
+}
+
+export class MyGameRunnerWithMap extends MyGameRunner {
+  constructor(
+    config: ECSConfig,
+    inputProvider: AbstractInputProvider,
+    rapier: RapierModule2d,
+    physicsConfig?: PhysicsConfig2d,
+  ) {
+    const mapData = new MapData();
+
+    super(
+      config, inputProvider,
+      MyGameSystems, MyGameSignals,
+      rapier, physicsConfig, undefined,
+      [[MapData, mapData]],  // Register MapData for DI
+    );
+
+    // Generate map using ECS PRNG (available after super)
+    const prng = this.DIContainer.resolve(PRNG);
+    const generator = createMapGenerator();
+    const collision = new SpatialGridCollisionProvider(1024, 1024, 64);
+    const map = generator.generate(prng, collision);
+    mapData.map = map;
+    mapData.registry = OBJECT_REGISTRY;
+
+    // Create physics colliders for placed objects
+    const placement = map.get<ObjectPlacementOutput>(ObjectPlacementFeature);
+    if (placement) {
+      const physics = createPhysicsAdapter(this.PhysicsWorldManager, rapier);
+      createMapColliders(physics, placement.objects, mapData.registry, {
+        skipTags: [CANOPY_SENSOR_TAG],
+      });
+    }
+
+    // CRITICAL: re-capture initial state AFTER creating static bodies
+    // Without this, rollback to tick 0 restores a world without map colliders
+    this.Simulation.capturePreStartState();
+  }
+}
+```
+
+**Key points:**
+- Map is generated in the runner constructor, BEFORE `start()` is called
+- Uses ECS `PRNG` for determinism — same seed (from `serverHello.seed` in multiplayer) = same map
+- `capturePreStartState()` MUST be called after creating static bodies — otherwise rollback loses them
+- `MapData` is registered via `extraRegistrations` so systems can access map data through DI
+- `skipTags: [CANOPY_SENSOR_TAG]` prevents creating physics bodies for view-only sensor colliders
+
+## MapGenerator Configuration
+
+```typescript
+const generator = new MapGenerator({
+  baseWidth: 720,    // map width before scaling (pixels)
+  baseHeight: 720,   // map height before scaling (pixels)
+  scale: 1.0,        // multiplier applied to base dimensions
+  extension: 80,     // extra border around the map (water area)
+  gridSize: 16,      // terrain grid cell size for rendering
+});
+```
+
+The actual map dimensions are `(baseWidth + 2 * extension) * scale` by `(baseHeight + 2 * extension) * scale`.
+
+## Object Definitions
+
+### MapObjectDef
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `typeId` | `number` | Unique identifier for this object type |
+| `colliders` | `MapColliderDef[]` | Physics collision shapes |
+| `visuals` | `MapVisualDef[]` | Texture references with render layer |
+| `scaleRange` | `[min, max]` | Random scale range applied during placement |
+| `orientations` | `number[]?` | Allowed rotation angles (default: `[0]`) |
+| `groundPatches` | `GroundPatchDef[]?` | Ground patches drawn under the object |
+| `mapDisplay` | `MapDisplayDef?` | Minimap display shapes |
+| `children` | `ChildObjectDef[]?` | Child objects spawned relative to parent |
+| `includeSensorsInBounds` | `boolean?` | Include sensor colliders in placement AABB (default: false) |
+
+### MapColliderDef
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `shape` | `MapCollisionShape` | `{ type: ShapeType.Circle, radius }` or `{ type: ShapeType.Cuboid, halfWidth, halfHeight }` |
+| `offsetX` | `number?` | Offset from object center |
+| `offsetY` | `number?` | Offset from object center |
+| `isSensor` | `boolean?` | Sensor collider (no physics response) |
+| `tag` | `number?` | Tag for filtering (e.g., `CANOPY_SENSOR_TAG`) |
+| `collisionGroup` | `number?` | Rapier collision group bitmask |
+
+### MapVisualDef
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `texture` | `string` | Texture key (resolved by `getTexture` callback in renderer) |
+| `layer` | `RenderLayer` | `RenderLayer.Ground` (under entities) or `RenderLayer.Canopy` (over entities) |
+| `offsetX/Y` | `number?` | Visual offset from object center |
+| `anchorX/Y` | `number?` | Sprite anchor (default: 0.5, 0.5) |
+
+## Placement Stages
+
+Stages define how and where objects are placed. All stages run during `ObjectPlacementFeature.generate()`.
+
+| Kind | Description | Key Fields |
+|------|-------------|------------|
+| `PlacementKind.Location` | Place at a specific position | `typeId`, `pos: {x, y}`, `rad`, `optional` |
+| `PlacementKind.Fixed` | Place exact count randomly | `typeId`, `count`, `important?`, `terrainZone?` |
+| `PlacementKind.Random` | Choose N types from a list | `spawns: number[]`, `choose`, `terrainZone?` |
+| `PlacementKind.Density` | Count proportional to map area | `typeId`, `density`, `terrainZone?` |
+
+### Examples
+
+```typescript
+stages: [
+  // Place 1 tree per 100 sq. units of grass area
+  { kind: PlacementKind.Density, typeId: 0, density: 100, terrainZone: TerrainZone.Grass },
+
+  // Place exactly 3 buildings on grass
+  { kind: PlacementKind.Fixed, typeId: 1, count: 3, terrainZone: TerrainZone.Grass },
+
+  // Place a spawn point at (100, 100) within 20px radius; skip if placement fails
+  { kind: PlacementKind.Location, typeId: 2, pos: { x: 100, y: 100 }, rad: 20, optional: true },
+
+  // Randomly pick 5 objects from types [0, 1, 2]
+  { kind: PlacementKind.Random, spawns: [0, 1, 2], choose: 5 },
+]
+```
+
+### Terrain Zones
+
+Restrict placement to specific terrain types:
+
+| Zone | Value | Description |
+|------|-------|-------------|
+| `TerrainZone.Grass` | 0 | Main land area |
+| `TerrainZone.Beach` | 1 | Shore/beach area |
+| `TerrainZone.RiverShore` | 2 | Riverbank |
+| `TerrainZone.River` | 3 | Inside river |
+| `TerrainZone.Lake` | 4 | Inside lake |
+| `TerrainZone.Bridge` | 5 | On a bridge |
+| `TerrainZone.WaterEdge` | 6 | Water edge |
+
+## Collision Providers
+
+Collision providers prevent object overlap during placement. Two options:
+
+```typescript
+import { SpatialGridCollisionProvider, RapierCollisionProvider } from '@lagless/2d-map-generator';
+
+// Fast grid-based provider (recommended for most cases)
+const collision = new SpatialGridCollisionProvider(mapWidth, mapHeight, cellSize);
+
+// Rapier-based provider (more accurate, slower — use when shapes need exact overlap testing)
+const collision = new RapierCollisionProvider(rapier);
+```
+
+## Terrain Query
+
+Classify world positions into terrain zones at runtime:
+
+```typescript
+import { TerrainQuery, TerrainZone } from '@lagless/2d-map-generator';
+import type { ShoreOutput, GrassOutput, RiverOutput, LakeOutput } from '@lagless/2d-map-generator';
+import { ShoreFeature, GrassFeature, RiverFeature, LakeFeature } from '@lagless/2d-map-generator';
+
+const terrain = new TerrainQuery({
+  shore: map.get<ShoreOutput>(ShoreFeature),
+  grass: map.get<GrassOutput>(GrassFeature),
+  river: map.get<RiverOutput>(RiverFeature),
+  lake: map.get<LakeOutput>(LakeFeature),
+});
+
+const zone = terrain.classify(playerX, playerY); // TerrainZone.Grass, .Beach, etc.
+```
+
+Useful for terrain-dependent game logic (speed modifiers, footstep sounds, spawn restrictions).
+
+## Physics Integration
+
+### MapPhysicsProvider Adapter
+
+`createMapColliders()` uses a `MapPhysicsProvider` adapter to create physics bodies. This decouples the generator from Rapier's API:
+
+```typescript
+import { createMapColliders, CANOPY_SENSOR_TAG } from '@lagless/2d-map-generator';
+import type { MapPhysicsProvider } from '@lagless/2d-map-generator';
+
+const physics: MapPhysicsProvider = {
+  createFixedBody(x, y, rotation) {
+    const desc = rapier.RigidBodyDesc.fixed().setTranslation(x, y).setRotation(rotation);
+    return worldManager.createBodyFromDesc(desc);
+  },
+  createCircleCollider(body, radius, ox, oy, isSensor, tag, collisionGroup) {
+    let desc = rapier.ColliderDesc.ball(radius).setTranslation(ox, oy).setSensor(isSensor);
+    if (collisionGroup != null) desc = desc.setCollisionGroups(collisionGroup);
+    worldManager.createColliderFromDesc(desc, body);
+  },
+  createCuboidCollider(body, hw, hh, ox, oy, isSensor, tag, collisionGroup) {
+    let desc = rapier.ColliderDesc.cuboid(hw, hh).setTranslation(ox, oy).setSensor(isSensor);
+    if (collisionGroup != null) desc = desc.setCollisionGroups(collisionGroup);
+    worldManager.createColliderFromDesc(desc, body);
+  },
+};
+
+// Create colliders, skipping canopy sensors (view-only)
+createMapColliders(physics, placement.objects, registry, {
+  skipTags: [CANOPY_SENSOR_TAG],
+});
+```
+
+### skipTags Option
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `skipTags` | `readonly number[]` | Skip colliders whose `tag` is in this list |
+
+Use `skipTags: [CANOPY_SENSOR_TAG]` to prevent creating physics bodies for canopy transparency sensors — they are view-only and don't need physics responses.
+
+### capturePreStartState (CRITICAL)
+
+Static map bodies must be created BEFORE calling `capturePreStartState()`:
+
+```typescript
+// 1. Generate map + create colliders (in runner constructor)
+// 2. Re-capture initial snapshot:
+this.Simulation.capturePreStartState();
+// 3. Start simulation:
+runner.start();
+```
+
+Without this, rollback to tick 0/1 restores a physics world without map colliders.
+
+## Rendering
+
+### MapTerrainRenderer
+
+Renders terrain layers (background, beach, grass, rivers, lakes, grid, ground patches):
+
+```typescript
+import { MapTerrainRenderer } from '@lagless/2d-map-renderer';
+
+const terrain = new MapTerrainRenderer();
+const terrainContainer = terrain.buildTerrain(map);
+viewport.addChildAt(terrainContainer, 0); // add at bottom of display list
+
+// Cleanup:
+terrain.destroy();
+```
+
+### MapObjectRenderer
+
+Renders placed objects as two `ParticleContainer` layers — ground (under entities) and canopy (over entities):
+
+```typescript
+import { MapObjectRenderer } from '@lagless/2d-map-renderer';
+import { ObjectPlacementFeature } from '@lagless/2d-map-generator';
+import type { ObjectPlacementOutput } from '@lagless/2d-map-generator';
+import { Assets, Texture } from 'pixi.js';
+
+const objectRenderer = new MapObjectRenderer({ dynamicCanopyAlpha: true });
+
+const placement = map.get<ObjectPlacementOutput>(ObjectPlacementFeature);
+if (placement) {
+  objectRenderer.build(
+    placement.objects,
+    registry,
+    (textureKey) => Assets.get<Texture>(textureKey) ?? Texture.EMPTY,
+  );
+
+  viewport.addChild(objectRenderer.ground);  // under entities
+  // ... add entity views here ...
+  viewport.addChild(objectRenderer.canopy);  // over entities
+}
+
+// Cleanup:
+objectRenderer.destroy();
+```
+
+**Display order:** terrain → `objectRenderer.ground` → entity sprites → `objectRenderer.canopy`
+
+### Canopy Transparency
+
+Canopy transparency is a **view-only** concern — it must NOT live in ECS or affect determinism. When a player is under a tree/building canopy, the canopy becomes transparent so the player remains visible.
+
+```typescript
+import { extractCanopyZones, isInsideCanopyZone } from '@lagless/2d-map-generator';
+import type { ObjectPlacementOutput } from '@lagless/2d-map-generator';
+
+// Pre-compute once (e.g., in useMemo):
+const placement = map.get<ObjectPlacementOutput>(ObjectPlacementFeature);
+const canopyZones = placement ? extractCanopyZones(placement.objects, registry) : [];
+
+// Per frame (e.g., in useTick):
+const px = playerX, py = playerY;
+for (const zone of canopyZones) {
+  const inside = isInsideCanopyZone(zone, px, py);
+  objectRenderer.setCanopyAlpha(zone.objectIndex, inside ? 0.3 : 1.0);
+}
+```
+
+**How it works:**
+1. `extractCanopyZones()` finds all sensor colliders tagged with `CANOPY_SENSOR_TAG` (default tag)
+2. Returns `CanopyZone[]` with pre-computed `radiusSq` (for circles) or `halfWidth/halfHeight` (for cuboids)
+3. `isInsideCanopyZone()` performs the appropriate distance check based on zone type
+4. `objectRenderer.setCanopyAlpha()` sets the alpha of the canopy particle at that index
+
+**Performance:** O(N) per frame with N objects — just a distance comparison per object, negligible cost.
+
+### MinimapRenderer
+
+Renders a simplified minimap:
+
+```typescript
+import { MinimapRenderer } from '@lagless/2d-map-renderer';
+import { ObjectPlacementFeature } from '@lagless/2d-map-generator';
+import type { ObjectPlacementOutput } from '@lagless/2d-map-generator';
+
+const minimap = new MinimapRenderer();
+const minimapContainer = minimap.buildMinimap(map, 200); // 200px size
+
+// Add object dots to minimap (uses mapDisplay shapes from object definitions)
+const placement = map.get<ObjectPlacementOutput>(ObjectPlacementFeature);
+if (placement) {
+  minimap.addObjectShapes(placement.objects, registry);
+}
+
+stage.addChild(minimapContainer);
+
+// Cleanup:
+minimap.destroy();
+```
+
+Objects only show on the minimap if their `MapObjectDef` has a `mapDisplay` property with shapes.
+
+## Accessing Feature Outputs
+
+```typescript
+import type { BiomeOutput, ShoreOutput, GrassOutput, RiverOutput, ObjectPlacementOutput } from '@lagless/2d-map-generator';
+import { BiomeFeature, ShoreFeature, GrassFeature, RiverFeature, ObjectPlacementFeature } from '@lagless/2d-map-generator';
+
+const map = generator.generate(random, collision);
+
+// Type-safe access via feature class:
+const biome = map.get<BiomeOutput>(BiomeFeature);       // color palette
+const shore = map.get<ShoreOutput>(ShoreFeature);       // island polygon
+const grass = map.get<GrassOutput>(GrassFeature);       // grass polygon + area
+const river = map.get<RiverOutput>(RiverFeature);       // river polygons
+const placement = map.get<ObjectPlacementOutput>(ObjectPlacementFeature); // placed objects
+```
+
+## Biome Colors
+
+Use `STANDARD_BIOME` for default colors, or define custom:
+
+```typescript
+import { STANDARD_BIOME } from '@lagless/2d-map-generator';
+
+// Standard biome (green grass, blue water, sandy beach):
+generator.addFeature(new BiomeFeature(), STANDARD_BIOME);
+
+// Custom biome:
+generator.addFeature(new BiomeFeature(), {
+  background: 0x80af49,
+  water: 0x3d85c6,
+  waterRipple: 0x3478b2,
+  beach: 0xcdb35b,
+  riverbank: 0x905e24,
+  grass: 0x80af49,
+  underground: 0x1b0d00,
+});
+```
+
+## Ground Patches
+
+Objects can define `groundPatches` — colored rectangles drawn under the object (e.g., building foundations, dirt patches):
+
+```typescript
+groundPatches: [
+  {
+    offset: { x: 0, y: 0 },        // offset from object center
+    halfExtents: { x: 12, y: 10 }, // half-size of the rectangle
+    color: 0x8b4513,                // fill color
+    roughness: 0.5,                 // edge roughness (0 = smooth)
+    offsetDist: 2,                  // random edge offset distance
+    order: 0,                       // 0 = under grid, 1 = over grid
+    useAsMapShape: false,           // whether to use as map boundary shape
+  },
+]
+```
+
+Add `GroundPatchFeature` to your generator to enable ground patches:
+
+```typescript
+import { GroundPatchFeature } from '@lagless/2d-map-generator';
+
+generator.addFeature(new GroundPatchFeature(), { registry: OBJECT_REGISTRY });
+```
+
+## Utilities
+
+### sortPlacedObjects
+
+Sorts placed objects by position (Y then X). Used internally by both `MapObjectRenderer.build()` and `extractCanopyZones()` to guarantee consistent object indices.
+
+```typescript
+import { sortPlacedObjects } from '@lagless/2d-map-generator';
+
+const sorted = sortPlacedObjects(placement.objects);
+// sorted[i] index matches MapObjectRenderer particle index and CanopyZone.objectIndex
+```
+
+### CANOPY_SENSOR_TAG
+
+Constant (`= 1`) used as a tag on sensor colliders to mark canopy transparency zones. Used by:
+- `extractCanopyZones()` — default tag parameter
+- `createMapColliders()` with `skipTags` — prevents creating physics bodies for canopy sensors
+
+## Determinism Notes
+
+All map generation is deterministic:
+- Uses `ISeededRandom` interface — the ECS `PRNG` satisfies this structurally
+- Trigonometry uses `MathOps` (WASM-backed, cross-platform identical)
+- Same seed + same config = identical map on every client
+- Map generation happens ONCE before simulation starts, not during ticks
+- In multiplayer, the seed comes from `serverHello.seed` — guaranteed identical for all clients
+
+## Enums Reference
+
+| Enum | Values |
+|------|--------|
+| `ShapeType` | `Circle = 0`, `Cuboid = 1` |
+| `PlacementKind` | `Location = 0`, `Fixed = 1`, `Random = 2`, `Density = 3` |
+| `RenderLayer` | `Ground = 0`, `Canopy = 1` |
+| `TerrainZone` | `Grass = 0`, `Beach = 1`, `RiverShore = 2`, `River = 3`, `Lake = 4`, `Bridge = 5`, `WaterEdge = 6` |
+
+## Full Client Example
+
+```typescript
+// In your game view component:
+import { FC, useEffect, useMemo, useRef } from 'react';
+import { useTick } from '@pixi/react';
+import { Assets, Texture } from 'pixi.js';
+import { MapTerrainRenderer, MapObjectRenderer } from '@lagless/2d-map-renderer';
+import { ObjectPlacementFeature, extractCanopyZones, isInsideCanopyZone } from '@lagless/2d-map-generator';
+import type { ObjectPlacementOutput } from '@lagless/2d-map-generator';
+
+export const MapView: FC<{ runner: MyGameRunner; viewport: Viewport }> = ({ runner, viewport }) => {
+  const mapData = useMemo(() => runner.DIContainer.resolve(MapData), [runner]);
+  const objectRendererRef = useRef<MapObjectRenderer | null>(null);
+
+  // Build terrain + objects once
+  useEffect(() => {
+    const terrain = new MapTerrainRenderer();
+    viewport.addChildAt(terrain.buildTerrain(mapData.map), 0);
+
+    const objRenderer = new MapObjectRenderer({ dynamicCanopyAlpha: true });
+    objectRendererRef.current = objRenderer;
+    const placement = mapData.map.get<ObjectPlacementOutput>(ObjectPlacementFeature);
+    if (placement) {
+      objRenderer.build(placement.objects, mapData.registry, (key) => Assets.get<Texture>(key) ?? Texture.EMPTY);
+      viewport.addChild(objRenderer.ground);
+      viewport.addChild(objRenderer.canopy);
+    }
+
+    return () => { terrain.destroy(); objRenderer.destroy(); };
+  }, [viewport, mapData]);
+
+  // Pre-compute canopy zones
+  const canopyZones = useMemo(() => {
+    const placement = mapData.map.get<ObjectPlacementOutput>(ObjectPlacementFeature);
+    return placement ? extractCanopyZones(placement.objects, mapData.registry) : [];
+  }, [mapData]);
+
+  // Per-frame canopy transparency
+  useTick(() => {
+    const objRenderer = objectRendererRef.current;
+    if (!objRenderer) return;
+    const px = playerX, py = playerY; // get from transform
+    for (const zone of canopyZones) {
+      objRenderer.setCanopyAlpha(zone.objectIndex, isInsideCanopyZone(zone, px, py) ? 0.3 : 1.0);
+    }
+  });
+
+  return null;
+};
+```

package/templates/pixi-react/__packageName__-simulation/src/lib/systems/hash-verification.system.ts

@@ -1,17 +0,0 @@
-import { ECSConfig, ECSSystem, InputProvider, PlayerResources, AbstractHashVerificationSystem, DivergenceSignal } from '@lagless/core';
-import { PlayerResource, ReportHash } from '../schema/code-gen/index.js';
-
-@ECSSystem()
-export class HashVerificationSystem extends AbstractHashVerificationSystem {
-  protected readonly _reportHashRpc = ReportHash;
-  protected readonly _playerResourceClass = PlayerResource;
-
-  constructor(
-    ecsConfig: ECSConfig,
-    inputProvider: InputProvider,
-    playerResources: PlayerResources,
-    divergenceSignal: DivergenceSignal,
-  ) {
-    super(ecsConfig, inputProvider, playerResources, divergenceSignal);
-  }
-}