@lagless/create 0.0.38 → 0.0.39

package/LICENSE

@@ -0,0 +1,26 @@
+Creative Commons Attribution-NonCommercial 4.0 International
+
+Copyright (c) 2025 Lagless
+
+This work is licensed under the Creative Commons
+Attribution-NonCommercial 4.0 International License.
+
+You are free to:
+
+  Share — copy and redistribute the material in any medium or format
+  Adapt — remix, transform, and build upon the material
+
+Under the following terms:
+
+  Attribution — You must give appropriate credit, provide a link to
+  the license, and indicate if changes were made. You may do so in
+  any reasonable manner, but not in any way that suggests the licensor
+  endorses you or your use.
+
+  NonCommercial — You may not use the material for commercial purposes.
+
+  No additional restrictions — You may not apply legal terms or
+  technological measures that legally restrict others from doing
+  anything the license permits.
+
+Full license text: https://creativecommons.org/licenses/by-nc/4.0/legalcode

package/dist/index.js

@@ -3,18 +3,17 @@ import { program } from 'commander';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as ejs from 'ejs';
+import { execSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
+import { select } from '@inquirer/prompts';
 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');
@@ -39,7 +38,29 @@ function processPath(filePath, vars) {
     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)=>{
+async function promptSimulationType() {
+    return select({
+        message: 'Select simulation type:',
+        choices: [
+            {
+                value: 'raw',
+                name: 'Raw ECS',
+                description: 'Manual velocity/position management, no physics engine'
+            },
+            {
+                value: 'physics2d',
+                name: 'Physics 2D (Rapier)',
+                description: 'Rapier 2D rigid body physics with auto-managed transforms'
+            },
+            {
+                value: 'physics3d',
+                name: 'Physics 3D (Rapier)',
+                description: 'Rapier 3D rigid body physics with top-down 2D rendering'
+            }
+        ]
+    });
+}
+program.name('create-lagless').description('Scaffold a new Lagless multiplayer game project').version('0.0.38').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').option('--simulation-type <type>', 'Simulation type: raw, physics2d, or physics3d').action(async (projectArg, options)=>{
     const targetDir = path.resolve(process.cwd(), projectArg);
     const packageName = path.basename(targetDir).toLowerCase();
     const pascalName = toPascalCase(packageName);
@@ -53,9 +74,25 @@ program.name('create-lagless').description('Scaffold a new Lagless multiplayer g
         console.error(`Error: Preset "${options.preset}" not found. Available: ${fs.readdirSync(templatesDir).join(', ')}`);
         process.exit(1);
     }
+    // Determine simulation type — from CLI flag or interactive prompt
+    let simulationType;
+    if (options.simulationType) {
+        const valid = [
+            'raw',
+            'physics2d',
+            'physics3d'
+        ];
+        if (!valid.includes(options.simulationType)) {
+            console.error(`Error: Invalid simulation type "${options.simulationType}". Valid: ${valid.join(', ')}`);
+            process.exit(1);
+        }
+        simulationType = options.simulationType;
+    } else {
+        simulationType = await promptSimulationType();
+    }
     // Read package.json from this package to get current lagless version
     const pkgJsonPath = path.resolve(__dirname, '..', 'package.json');
-    let laglessVersion = '0.0.30';
+    let laglessVersion = '0.0.38';
     try {
         const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
         laglessVersion = pkg.version || laglessVersion;
@@ -67,10 +104,12 @@ program.name('create-lagless').description('Scaffold a new Lagless multiplayer g
         packageName,
         frontendPort: options.port,
         serverPort: options.serverPort,
-        laglessVersion
+        laglessVersion,
+        simulationType
     };
     console.log(`\nCreating Lagless project "${packageName}"...`);
     console.log(`  Preset: ${options.preset}`);
+    console.log(`  Simulation: ${simulationType}`);
     console.log(`  Frontend port: ${options.port}`);
     console.log(`  Server port: ${options.serverPort}`);
     console.log(`  Target: ${targetDir}\n`);
@@ -80,13 +119,8 @@ program.name('create-lagless').description('Scaffold a new Lagless multiplayer g
         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
+        // Only process text files that might contain EJS tags
         const ext = path.extname(templateFile);
         const textExts = [
             '.ts',
@@ -105,19 +139,65 @@ program.name('create-lagless').description('Scaffold a new Lagless multiplayer g
                 filename: templateFile
             });
             const finalPath = ext === '.ejs' ? outputPath.replace(/\.ejs$/, '') : outputPath;
+            // Skip writing empty/whitespace-only files (conditional template exclusion)
+            if (rendered.trim().length === 0) {
+                continue;
+            }
+            if (!fs.existsSync(outputDir)) {
+                fs.mkdirSync(outputDir, {
+                    recursive: true
+                });
+            }
             fs.writeFileSync(finalPath, rendered, 'utf-8');
         } else {
             // Binary or unknown — copy as-is
+            if (!fs.existsSync(outputDir)) {
+                fs.mkdirSync(outputDir, {
+                    recursive: true
+                });
+            }
             fs.copyFileSync(templateFile, outputPath);
         }
     }
-    console.log('Project created successfully!\n');
+    // Remove physics docs that don't match the selected simulationType
+    const docsDir = path.join(targetDir, 'docs');
+    if (simulationType !== 'physics2d') {
+        const f = path.join(docsDir, '08-physics2d.md');
+        if (fs.existsSync(f)) fs.rmSync(f);
+    }
+    if (simulationType !== 'physics3d') {
+        const f = path.join(docsDir, '08-physics3d.md');
+        if (fs.existsSync(f)) fs.rmSync(f);
+    }
+    // Clone lagless framework source for AI reference
+    const sourcesDir = path.join(docsDir, 'sources');
+    fs.mkdirSync(sourcesDir, {
+        recursive: true
+    });
+    console.log('Cloning lagless framework source for AI reference...');
+    try {
+        execSync(`git clone --depth 1 https://github.com/GbGr/lagless.git "${path.join(sourcesDir, 'lagless')}"`, {
+            stdio: 'inherit'
+        });
+        // Remove .git to save space
+        fs.rmSync(path.join(sourcesDir, 'lagless', '.git'), {
+            recursive: true,
+            force: true
+        });
+    } catch (e) {
+        console.warn('Warning: Could not clone lagless source. AI reference will be unavailable.');
+        console.warn('You can manually clone later: git clone --depth 1 https://github.com/GbGr/lagless.git docs/sources/lagless');
+    }
+    console.log('\nProject created successfully!\n');
     console.log('Next steps:');
     console.log(`  cd ${packageName}`);
     console.log('  pnpm install');
-    console.log('  pnpm codegen        # Generate ECS code from schema');
-    console.log('  pnpm dev:backend    # Start game server');
-    console.log('  pnpm dev:frontend   # Start frontend dev server\n');
+    console.log('  pnpm codegen           # Generate ECS code from schema');
+    console.log('  pnpm dev               # Start backend + frontend + dev-player\n');
+    console.log('Or run individually:');
+    console.log('  pnpm dev:backend       # Game server (Bun, watches for changes)');
+    console.log('  pnpm dev:frontend      # Frontend (Vite HMR)');
+    console.log('  pnpm dev:player        # Dev-player (multiplayer testing, port 4210)\n');
 });
 program.parse();
 

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 { 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 codegen        # Generate ECS code from schema');\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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"}
+{"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\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('0.0.38')\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  .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    // Read package.json from this package to get current lagless version\n    const pkgJsonPath = path.resolve(__dirname, '..', 'package.json');\n    let laglessVersion = '0.0.38';\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: 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    console.log('\\nProject created successfully!\\n');\n    console.log('Next steps:');\n    console.log(`  cd ${packageName}`);\n    console.log('  pnpm install');\n    console.log('  pnpm codegen           # Generate ECS code from schema');\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  });\n\nprogram.parse();\n"],"names":["program","fs","path","ejs","execSync","fileURLToPath","select","__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","promptSimulationType","message","choices","value","description","version","argument","option","action","projectArg","options","targetDir","process","cwd","basename","toLowerCase","pascalName","console","error","exit","templatesDir","presetDir","preset","simulationType","valid","includes","pkgJsonPath","laglessVersion","pkg","JSON","parse","readFileSync","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,7 +1,7 @@
 {
   "name": "@lagless/create",
-  "version": "0.0.38",
-  "license": "MIT",
+  "version": "0.0.39",
+  "license": "CC-BY-NC-4.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/GbGr/lagless",
@@ -45,9 +45,10 @@
     }
   },
   "dependencies": {
+    "@inquirer/prompts": "^8.3.0",
+    "@swc/helpers": "~0.5.11",
     "commander": "^14.0.1",
-    "ejs": "^3.1.10",
-    "@swc/helpers": "~0.5.11"
+    "ejs": "^3.1.10"
   },
   "devDependencies": {
     "@types/ejs": "^3.1.5"

package/templates/pixi-react/AGENTS.md

@@ -1,41 +1,71 @@
-# AGENTS.md — Multi-Agent Development Guide
+# AGENTS.md — Multi-Agent Guide for <%= projectName %>
 
 ## 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
+This is a Lagless multiplayer game with three packages:
+- **<%= packageName %>-simulation** — Deterministic ECS game logic (shared between all clients)
+- **<%= packageName %>-frontend** — React + Pixi.js rendering client
+- **<%= packageName %>-backend** — Bun relay server (no simulation)
 
 ## 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
+1. **Schema & Codegen** — Edit `ecs.yaml`, run `pnpm codegen`
+2. **System** — Write `@ECSSystem()` in simulation, add to systems array
+3. **View** — Add Pixi.js component in frontend `game-view/`
+4. **Input** — Wire drainInputs in `runner-provider.tsx` if feature needs player input
+5. **Test** — Verify determinism: open two tabs, play, check F3 hash table matches
 
 ### Debugging Determinism Issues
+1. **Reproduce** — Open dev-player (`pnpm dev:player`), run 2+ instances
+2. **Identify tick** — F3 debug panel shows hash divergence tick
+3. **Binary search** — Add hash checks between systems to narrow down which system diverges
+4. **Check rules** — Review `docs/03-determinism.md` for common violations
+5. **Common causes** — `Math.sin` instead of `MathOps.sin`, unsorted iteration, missing `prevPosition` init
+
+### Adding Multiplayer Features
+1. **Server events** — Add to `RoomHooks` in `game-hooks.ts`
+2. **Server RPCs** — Use `ctx.emitServerEvent()` for server-originated inputs
+3. **State transfer** — Handled automatically, but test with late-join scenario
+4. **Reconnect** — Test disconnect/reconnect via F3 debug panel buttons
+
+## File Ownership by Task Type
+
+| Task | Primary Files |
+|------|--------------|
+| New component/input | `ecs.yaml` → `pnpm codegen` |
+| Game logic | `*-simulation/src/lib/systems/*.system.ts` |
+| Entity rendering | `*-frontend/src/app/game-view/*.tsx` |
+| UI/screens | `*-frontend/src/app/screens/*.tsx` |
+| Player input | `*-frontend/src/app/game-view/runner-provider.tsx` |
+| Server hooks | `*-backend/src/game-hooks.ts` |
+| Server config | `*-backend/src/main.ts` |
+| Signals | `*-simulation/src/lib/signals/index.ts` |
 
-- 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
+## Verification Checklist
 
-### Testing Strategy
+### Before Submitting Any Change
+- [ ] `pnpm codegen` runs without errors (if schema changed)
+- [ ] Game starts: `pnpm dev` → no console errors
+- [ ] Single-player works: title screen → game → entities move correctly
+- [ ] Multiplayer works: two browser tabs, both see each other
+- [ ] Determinism holds: F3 panel → hash table → no red (divergence) entries
 
-- **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
+### For Physics Changes (<%= simulationType !== 'raw' ? 'APPLIES TO THIS PROJECT' : 'if applicable' %>)
+- [ ] Bodies created with correct BodyType
+- [ ] `updateSceneQueries()` called after snapshot restore
+- [ ] ColliderEntityMap rebuilt after state transfer
+- [ ] Collision layers configured correctly
 
-## Key Files
+## Key Constraints
+- **Never edit `code-gen/` files** — always edit `ecs.yaml` and run `pnpm codegen`
+- **Never use `Math.sin/cos/atan2/sqrt`** — use `MathOps.*` equivalents
+- **Never use `Math.random()`** — use `PRNG.getFloat()` or `PRNG.getRandomInt()`
+- **Always sanitize RPC inputs** — `Number.isFinite()` before `MathOps.clamp()`
+- **Always set prevPosition = position** when spawning entities with Transform2d
+- **Systems array order = execution order** — it's deterministic and matters
 
-| 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 |
+## Documentation Reference
+- `CLAUDE.md` — Primary instruction file with code patterns
+- `docs/` — Detailed documentation on all framework topics
+- `docs/sources/lagless/` — Full framework source code for deep reference