@auraindustry/aurajs 0.0.6 → 0.1.0

package/src/scaffold/config.mjs

@@ -0,0 +1,1000 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const SCAFFOLD_DIR = dirname(fileURLToPath(import.meta.url));
+const CLI_SRC_DIR = resolve(SCAFFOLD_DIR, '..');
+const CLI_PACKAGE = JSON.parse(readFileSync(resolve(CLI_SRC_DIR, '../package.json'), 'utf8'));
+const CLI_PACKAGE_VERSION = CLI_PACKAGE.version;
+
+export const LEGACY_STARTER_TEMPLATE_DIR = resolve(CLI_SRC_DIR, '../templates/starter');
+
+export const CREATE_TEMPLATE_DIRS = {
+  '2d-adventure': resolve(CLI_SRC_DIR, '../templates/create/2d-adventure'),
+  '2d-shooter': resolve(CLI_SRC_DIR, '../templates/create/2d'),
+  '2d-survivor': resolve(CLI_SRC_DIR, '../templates/create/2d-survivor'),
+  'deckbuilder-2d': resolve(CLI_SRC_DIR, '../templates/create/deckbuilder-2d'),
+  '3d-adventure': resolve(CLI_SRC_DIR, '../templates/create/3d-adventure'),
+  '3d-platformer': resolve(CLI_SRC_DIR, '../templates/create/3d'),
+  '3d-collectathon': resolve(CLI_SRC_DIR, '../templates/create/3d-collectathon'),
+  'video-cutscene': resolve(CLI_SRC_DIR, '../templates/create/video-cutscene'),
+  blank: resolve(CLI_SRC_DIR, '../templates/create/blank'),
+  'local-multiplayer': resolve(CLI_SRC_DIR, '../templates/create/local-multiplayer'),
+  'retro-topdown-adventure': resolve(CLI_SRC_DIR, '../templates/retro/topdown-adventure'),
+  'retro-puzzle-grid': resolve(CLI_SRC_DIR, '../templates/retro/puzzle-grid'),
+  'retro-tactics-grid': resolve(CLI_SRC_DIR, '../templates/retro/tactics-grid'),
+  'retro-platformer': resolve(CLI_SRC_DIR, '../templates/retro/platformer'),
+};
+export const CREATE_SHARED_TEMPLATE_DIR = resolve(CLI_SRC_DIR, '../templates/create/shared');
+
+const CREATE_TEMPLATE_ALIASES = {
+  '2d': '2d-adventure',
+  '2d-adventure': '2d-adventure',
+  '2d adventure': '2d-adventure',
+  'adventure-2d': '2d-adventure',
+  adventure2d: '2d-adventure',
+  shooter: '2d-shooter',
+  '2d shooter': '2d-shooter',
+  '2d-shooter': '2d-shooter',
+  '2d-survivor': '2d-survivor',
+  survivor: '2d-survivor',
+  '2d survival': '2d-survivor',
+  '2d-survival': '2d-survivor',
+  topdown: '2d-survivor',
+  'top-down': '2d-survivor',
+  'deckbuilder': 'deckbuilder-2d',
+  deckbuilder: 'deckbuilder-2d',
+  'deckbuilder-2d': 'deckbuilder-2d',
+  'card battler': 'deckbuilder-2d',
+  slaylike: 'deckbuilder-2d',
+  '3d': '3d-adventure',
+  '3d-adventure': '3d-adventure',
+  '3d adventure': '3d-adventure',
+  'adventure-3d': '3d-adventure',
+  adventure3d: '3d-adventure',
+  platformer: '3d-platformer',
+  platformers: '3d-platformer',
+  '3d platformer': '3d-platformer',
+  '3d platformers': '3d-platformer',
+  '3d-platformer': '3d-platformer',
+  '3d-collectathon': '3d-collectathon',
+  collectathon: '3d-collectathon',
+  explorer: '3d-collectathon',
+  exploration: '3d-collectathon',
+  '3d collectathon': '3d-collectathon',
+  '3d explorer': '3d-collectathon',
+  video: 'video-cutscene',
+  'video-cutscene': 'video-cutscene',
+  cutscene: 'video-cutscene',
+  cinematic: 'video-cutscene',
+  'video cutscene': 'video-cutscene',
+  mp4: 'video-cutscene',
+  blank: 'blank',
+  empty: 'blank',
+  'local-multiplayer': 'local-multiplayer',
+  multiplayer: 'local-multiplayer',
+  'room-code': 'local-multiplayer',
+  room: 'local-multiplayer',
+  retro: 'retro-topdown-adventure',
+  gb: 'retro-topdown-adventure',
+  gbc: 'retro-topdown-adventure',
+  gba: 'retro-topdown-adventure',
+  'retro-topdown': 'retro-topdown-adventure',
+  'retro-topdown-adventure': 'retro-topdown-adventure',
+  'gb-topdown': 'retro-topdown-adventure',
+  'gbc-topdown': 'retro-topdown-adventure',
+  'gba-topdown': 'retro-topdown-adventure',
+  'retro-puzzle': 'retro-puzzle-grid',
+  'retro-puzzle-grid': 'retro-puzzle-grid',
+  'gb-puzzle': 'retro-puzzle-grid',
+  'gbc-puzzle': 'retro-puzzle-grid',
+  'gba-puzzle': 'retro-puzzle-grid',
+  'retro-tactics': 'retro-tactics-grid',
+  'retro-tactics-grid': 'retro-tactics-grid',
+  'gb-tactics': 'retro-tactics-grid',
+  'gbc-tactics': 'retro-tactics-grid',
+  'gba-tactics': 'retro-tactics-grid',
+  'retro-platformer': 'retro-platformer',
+  'gb-platformer': 'retro-platformer',
+  'gbc-platformer': 'retro-platformer',
+  'gba-platformer': 'retro-platformer',
+};
+const CREATE_TEMPLATE_ALIAS_HINTS = ['2d', '3d', 'shooter', 'survivor', 'deckbuilder', 'platformer', 'collectathon', 'video', 'cutscene', 'blank', 'empty', 'multiplayer', 'room-code', 'retro', 'gba', 'retro-platformer'];
+
+const ROOT_SKILLS_DIR = resolve(CLI_SRC_DIR, '../../../skills');
+const PACKAGED_SKILLS_DIR = resolve(CLI_SRC_DIR, '../templates/skills');
+const PLAY_BIN_TEMPLATE_PATH = resolve(CLI_SRC_DIR, '../templates/create-bin/play.js');
+
+export const GITIGNORE_TEMPLATE = `# Dependencies\nnode_modules/\n\n# Build output\nbuild/\n.aura/\n\n# Runtime logs\n.logs/\n*.log\nnpm-debug.log*\n\n# Local env\n.env\n.env.*\n`;
+export const PLAY_BIN_TEMPLATE = readFileSync(PLAY_BIN_TEMPLATE_PATH, 'utf8');
+const CREATE_TEMPLATE_METADATA = {
+  '2d-adventure': {
+    summary: 'Top-down exploration starter with relic collection, beacon activation, and authored room layout.',
+    controls: [
+      'Move: Arrow keys or WASD',
+      'Interact: E or Enter',
+      'Toggle controls hint: H',
+      'Restart: Enter (after route clear)',
+    ],
+    firstEdits: [
+      'Rewrite the room nouns in content/gameplay/world.js before adding more mechanics.',
+      'Tune movement feel and prompt reach in config/gameplay/adventure.config.js.',
+      'Replace beacon, relic, and gate presentation in prefabs/world.prefab.js and prefabs/relic.prefab.js.',
+    ],
+    keywords: ['2d', 'adventure', 'exploration'],
+    requiredApis: [
+      'aura.window.getFPS',
+      'aura.input.isKeyDown',
+      'aura.input.isKeyPressed',
+      'aura.draw2d.clear',
+      'aura.draw2d.rect',
+      'aura.draw2d.text',
+      'aura.draw2d.measureText',
+      'aura.rgb',
+      'aura.rgba',
+      'aura.Color.WHITE',
+    ],
+    starterAssetPlan: {
+      file: 'ruins-route.json',
+      title: '2D Adventure Route Notes',
+      steps: [
+        'Keep your first relic and beacon route readable here before you spread rules across more files.',
+        'Mirror any stable ids in content/gameplay/world.js once the route stops changing every day.',
+      ],
+      payload: {
+        relicRoute: [
+          { id: 'survey-lens', beat: 'north-room', x: 214, y: 190 },
+          { id: 'signal-reel', beat: 'water-crossing', x: 546, y: 152 },
+          { id: 'chorus-map', beat: 'east-court', x: 930, y: 352 },
+          { id: 'dawn-key', beat: 'south-exit', x: 792, y: 548 },
+        ],
+        beacons: [
+          { id: 'north-brazier', unlockRelics: 1 },
+          { id: 'east-brazier', unlockRelics: 3 },
+        ],
+      },
+    },
+    optionalModules: {
+      network: false,
+    },
+    configModules: {
+      network: false,
+    },
+    workflowTitle: '2D Adventure Authoring Loop',
+    workflowSteps: [
+      'Run `npm run dev` and finish one full route clear before editing structure.',
+      'Rename the room, relic, beacon, and gate nouns in content/gameplay/world.js to match your own game.',
+      'Only after the route reads well should you add more encounters, UI layers, or save rules.',
+    ],
+  },
+  '2d-shooter': {
+    summary: 'Arcade shooter baseline with waves, score, and lives loop.',
+    controls: [
+      'Move: Arrow keys or WASD',
+      'Fire: Space or Z',
+      'Restart: Enter (after game over)',
+    ],
+    firstEdits: [
+      'Tune encounter pacing in config/gameplay/shooter.config.js.',
+      'Adjust player and enemy behavior in prefabs/player.prefab.js and prefabs/enemies.prefab.js.',
+      'Swap starter palette and HUD text in ui/hud.screen.js.',
+    ],
+    keywords: ['2d', 'shooter', 'arcade'],
+    requiredApis: [
+      'aura.window.getSize',
+      'aura.window.getFPS',
+      'aura.input.isKeyDown',
+      'aura.input.isKeyPressed',
+      'aura.draw2d.clear',
+      'aura.draw2d.rect',
+      'aura.draw2d.text',
+      'aura.draw2d.measureText',
+      'aura.rgb',
+      'aura.rgba',
+      'aura.Color.WHITE',
+    ],
+    starterAssetPlan: {
+      file: 'wave-plan.json',
+      title: '2D Shooter Wave Plan',
+      steps: [
+        'Replace this JSON with your own wave progression and enemy mix.',
+        'Load this file in game logic after adding your preferred file-loading flow.',
+      ],
+      payload: {
+        waves: [
+          { id: 'intro', maxSpawns: 9, spawnEvery: 0.62, archetype: 'scout' },
+          { id: 'pressure', maxSpawns: 10, spawnEvery: 0.56, archetype: 'striker' },
+          { id: 'anchor', maxSpawns: 8, spawnEvery: 0.74, archetype: 'tank' },
+        ],
+      },
+    },
+  },
+  '2d-survivor': {
+    summary: 'Top-down auto-fire survival loop tuned for quick iteration.',
+    controls: [
+      'Move: Arrow keys or WASD',
+      'Dash: Shift',
+      'Restart: Enter (after game over)',
+    ],
+    firstEdits: [
+      'Adjust spawn pressure in config/gameplay/survivor.config.js.',
+      'Tune dash timings and player feel in prefabs/player.prefab.js.',
+      'Extend enemy archetypes in prefabs/enemies.prefab.js.',
+    ],
+    keywords: ['2d', 'survivor', 'topdown'],
+    requiredApis: [
+      'aura.window.getSize',
+      'aura.window.getFPS',
+      'aura.input.isKeyDown',
+      'aura.input.isKeyPressed',
+      'aura.draw2d.clear',
+      'aura.draw2d.rect',
+      'aura.draw2d.text',
+      'aura.draw2d.measureText',
+      'aura.rgb',
+      'aura.rgba',
+      'aura.Color.WHITE',
+    ],
+    starterAssetPlan: {
+      file: 'survivor-zones.json',
+      title: '2D Survivor Spawn Zones',
+      steps: [
+        'Use these zones to bias enemy spawns by map phase.',
+        'Add your own tags (boss, swarm, elite) and branch in update().',
+      ],
+      payload: {
+        zones: [
+          { id: 'north-lane', x: 0.5, y: 0.08, weight: 1.0 },
+          { id: 'east-lane', x: 0.92, y: 0.52, weight: 1.2 },
+          { id: 'south-lane', x: 0.5, y: 0.94, weight: 1.0 },
+          { id: 'west-lane', x: 0.08, y: 0.52, weight: 1.1 },
+        ],
+      },
+    },
+  },
+  'deckbuilder-2d': {
+    summary: 'Combat-first card battler starter with authored cards, enemy intents, relic seed data, and starter-owned content registries.',
+    controls: [
+      'Start battle: Space or Enter from boot scene',
+      'Play cards: 1-5',
+      'End turn: Enter or Space during combat',
+      'Restart battle: R',
+      'Return to boot: Esc',
+    ],
+    firstEdits: [
+      'Tune shared knobs in config/gameplay/deckbuilder.config.js and content nouns in content/cards/, content/enemies/, content/relics/, and content/encounters/.',
+      'Use `npx aura make card`, `enemy`, `relic`, and `encounter` to grow content families without hand-editing registry files.',
+      'Extend the combat presentation in scenes/gameplay.scene.js and ui/hud.screen.js only after the content nouns feel right.',
+    ],
+    keywords: ['deckbuilder', 'cards', 'combat', '2d'],
+    requiredApis: [
+      'aura.window.getSize',
+      'aura.input.isKeyPressed',
+      'aura.draw2d.rectFill',
+      'aura.draw2d.text',
+      'aura.rgb',
+      'aura.rgba',
+      'aura.Color.WHITE',
+    ],
+    starterAssetPlan: {
+      file: 'deckbuilder-art-pack.json',
+      title: 'Deckbuilder Starter Art Pack',
+      steps: [
+        'Replace placeholder cards and enemy panels only after the content nouns in content/ feel stable.',
+        'Keep one card frame, one arena backdrop, and one intent icon set as the first art milestone.',
+      ],
+      payload: {
+        cardFrames: ['starter-common', 'starter-skill'],
+        enemyPanels: ['training-automaton'],
+        iconSet: ['energy', 'block', 'draw', 'intent-attack', 'intent-block'],
+      },
+    },
+    optionalModules: {
+      network: false,
+      multiplayer: false,
+    },
+    configModules: {
+      network: false,
+    },
+    workflowTitle: 'Deckbuilder Authoring Loop',
+    workflowSteps: [
+      'Run `npm run dev` and play the starter battle before adding new systems.',
+      'Inspect the seeded content in `content/registries/` and `content/cards/`, then grow it with `npx aura make card|enemy|relic|encounter`.',
+      'Use `npx aura explain` or `npx aura check` when you want a truthful map of starter-owned registries and generated content.',
+    ],
+  },
+  '3d-adventure': {
+    summary: 'Third-person route starter with relic collection, beacon activation, pause flow, and authored checkpoint recovery.',
+    controls: [
+      'Move: Arrow keys or WASD',
+      'Run: Shift',
+      'Jump: Space',
+      'Interact: E or Enter',
+      'Pause: Esc',
+      'Restart: Enter (after route clear)',
+    ],
+    firstEdits: [
+      'Rewrite the route, relic, beacon, and arch nouns in content/gameplay/course.js before chasing polish.',
+      'Tune prompt radii and route pacing in config/gameplay/adventure.config.js.',
+      'Swap or retarget assets/models/starter-avatar.gltf and update the visual binding in prefabs/player.prefab.js.',
+    ],
+    keywords: ['3d', 'adventure', 'exploration'],
+    requiredApis: [
+      'aura.window.getSize',
+      'aura.mesh.createBox',
+      'aura.material.create',
+      'aura.light.ambient',
+      'aura.light.directional',
+      'aura.camera3d.perspective',
+      'aura.camera3d.setPosition',
+      'aura.camera3d.lookAt',
+      'aura.character3d.create',
+      'aura.character3d.move',
+      'aura.character3d.jump',
+      'aura.character3d.update',
+      'aura.character3d.getState',
+      'aura.character3d.setPosition',
+      'aura.character3d.addObstacle',
+      'aura.character3d.clearObstacles',
+      'aura.input.isKeyDown',
+      'aura.input.isKeyPressed',
+      'aura.scene3d.loadGltfScene',
+      'aura.scene3d.getImportedScene',
+      'aura.scene3d.playImportedAnimation',
+      'aura.scene3d.setLocalTransform',
+      'aura.scene3d.updateClips',
+      'aura.scene3d.submitRenderBindings',
+      'aura.draw3d.clear3d',
+      'aura.draw3d.drawMesh',
+      'aura.draw2d.rect',
+      'aura.draw2d.text',
+      'aura.draw2d.measureText',
+      'aura.rgb',
+      'aura.rgba',
+      'aura.Color.WHITE',
+    ],
+    starterAssetPlan: {
+      file: 'signal-route.json',
+      title: '3D Adventure Route Notes',
+      steps: [
+        'Plan the first checkpoint-to-arch route here before you spread it into more runtime files.',
+        'Track which relic or beacon beats are mandatory so restart and save work stays honest later.',
+      ],
+      payload: {
+        relicRoute: [
+          { id: 'anchor-relay', beat: 'lower-cliff', x: -3.8, y: 2.5, z: 3.0 },
+          { id: 'glass-map', beat: 'mid-span', x: 1.1, y: 3.4, z: 1.0 },
+          { id: 'pulse-key', beat: 'east-rise', x: 4.8, y: 4.3, z: -1.8 },
+          { id: 'sky-spindle', beat: 'summit', x: -1.2, y: 5.3, z: -3.6 },
+        ],
+        beacons: [
+          { id: 'cliff-beacon', unlockRelics: 2 },
+          { id: 'summit-beacon', unlockRelics: 4 },
+        ],
+      },
+    },
+    optionalModules: {
+      network: false,
+    },
+    configModules: {
+      network: false,
+    },
+    workflowTitle: '3D Adventure Authoring Loop',
+    workflowSteps: [
+      'Run `npm run dev` and clear the full relic-beacon-arch route before editing structure.',
+      'Rename the route nouns in content/gameplay/course.js and keep any new tuning in config/gameplay/adventure.config.js.',
+      'Only after the authored route feels right should you move into richer imported scenes, VFX, or cinematic beats.',
+    ],
+  },
+  '3d-platformer': {
+    summary: '3D checkpoint platformer loop with an imported animated starter avatar and moving platform primitives.',
+    controls: [
+      'Move: Arrow keys or WASD',
+      'Run: Shift',
+      'Jump: Space',
+      'Restart: Enter (after goal)',
+    ],
+    firstEdits: [
+      'Adjust traversal beats in content/gameplay/course.js.',
+      'Tune camera offsets, clip flow, and avatar input in prefabs/player.prefab.js and scenes/gameplay.scene.js.',
+      'Swap world materials or replace assets/models/starter-avatar.gltf with your own imported character.',
+    ],
+    keywords: ['3d', 'platformer', 'checkpoint'],
+    requiredApis: [
+      'aura.mesh.createBox',
+      'aura.material.create',
+      'aura.light.ambient',
+      'aura.light.directional',
+      'aura.camera3d.perspective',
+      'aura.camera3d.setPosition',
+      'aura.camera3d.lookAt',
+      'aura.character3d.create',
+      'aura.character3d.move',
+      'aura.character3d.jump',
+      'aura.character3d.update',
+      'aura.character3d.getState',
+      'aura.character3d.setPosition',
+      'aura.character3d.addObstacle',
+      'aura.character3d.clearObstacles',
+      'aura.input.isKeyDown',
+      'aura.input.isKeyPressed',
+      'aura.scene3d.loadGltfScene',
+      'aura.scene3d.getImportedScene',
+      'aura.scene3d.playImportedAnimation',
+      'aura.scene3d.setLocalTransform',
+      'aura.scene3d.updateClips',
+      'aura.scene3d.submitRenderBindings',
+      'aura.draw3d.clear3d',
+      'aura.draw3d.drawMesh',
+      'aura.draw2d.text',
+      'aura.draw2d.measureText',
+      'aura.rgb',
+      'aura.Color.WHITE',
+    ],
+    starterAssetPlan: {
+      file: 'checkpoint-route.json',
+      title: '3D Platformer Route Notes',
+      steps: [
+        'Use this path list to plan encounter/collectible placement between checkpoints.',
+        'Attach analytics ids if you track failed jump segments.',
+      ],
+      payload: {
+        path: [
+          { id: 'spawn', x: 0.0, y: 1.1, z: 5.5 },
+          { id: 'ridge-a', x: -3.2, y: 2.0, z: -2.4 },
+          { id: 'ridge-b', x: 1.4, y: 3.2, z: -0.8 },
+          { id: 'goal', x: 4.4, y: 4.8, z: -3.0 },
+        ],
+      },
+    },
+  },
+  '3d-collectathon': {
+    summary: '3D collection race starter with an imported animated avatar, timer pressure, and checkpoint fallback.',
+    controls: [
+      'Move: Arrow keys or WASD',
+      'Run: Shift',
+      'Jump: Space',
+      'Restart: Enter (after clear/failure)',
+    ],
+    firstEdits: [
+      'Add world pieces and route tuning in content/gameplay/course.js.',
+      'Balance collectible cadence, avatar pacing, and timer rules in scenes/gameplay.scene.js.',
+      'Replace assets/models/starter-avatar.gltf or retarget the clip map in prefabs/player.prefab.js.',
+    ],
+    keywords: ['3d', 'collectathon', 'exploration'],
+    requiredApis: [
+      'aura.mesh.createBox',
+      'aura.material.create',
+      'aura.light.ambient',
+      'aura.light.directional',
+      'aura.camera3d.perspective',
+      'aura.camera3d.setPosition',
+      'aura.camera3d.lookAt',
+      'aura.character3d.create',
+      'aura.character3d.move',
+      'aura.character3d.jump',
+      'aura.character3d.update',
+      'aura.character3d.getState',
+      'aura.character3d.setPosition',
+      'aura.character3d.addObstacle',
+      'aura.character3d.clearObstacles',
+      'aura.input.isKeyDown',
+      'aura.input.isKeyPressed',
+      'aura.scene3d.loadGltfScene',
+      'aura.scene3d.getImportedScene',
+      'aura.scene3d.playImportedAnimation',
+      'aura.scene3d.setLocalTransform',
+      'aura.scene3d.updateClips',
+      'aura.scene3d.submitRenderBindings',
+      'aura.draw3d.clear3d',
+      'aura.draw3d.drawMesh',
+      'aura.draw2d.text',
+      'aura.draw2d.measureText',
+      'aura.rgb',
+      'aura.Color.WHITE',
+    ],
+    starterAssetPlan: {
+      file: 'collectible-layout.json',
+      title: '3D Collectathon Layout Plan',
+      steps: [
+        'Extend this list with your final collectible and checkpoint route.',
+        'Optionally mirror ids in your quest/state system for save/load.',
+      ],
+      payload: {
+        collectibles: [
+          { id: 'orb-a', x: -2.8, y: 1.8, z: 2.2, value: 1 },
+          { id: 'orb-b', x: 2.4, y: 2.4, z: 0.4, value: 1 },
+          { id: 'orb-c', x: 4.6, y: 3.8, z: -2.8, value: 1 },
+        ],
+      },
+    },
+  },
+  'video-cutscene': {
+    summary: 'Cinematic cutscene starter with MP4 video playback, fade transitions, skip support, and scene flow between video and gameplay.',
+    controls: [
+      'Skip cutscene: Space or Enter',
+    ],
+    firstEdits: [
+      'Drop your .mp4 files in assets/video/ and update the path in scenes/cutscene.scene.js.',
+      'Replace the gameplay scene placeholder with your actual game loop.',
+      'Add more cutscene scenes for different story beats by duplicating cutscene.scene.js.',
+    ],
+    keywords: ['video', 'cutscene', 'cinematic', 'mp4'],
+    requiredApis: [
+      'aura.video.load',
+      'aura.video.play',
+      'aura.video.pause',
+      'aura.video.stop',
+      'aura.video.seek',
+      'aura.video.getTexture',
+      'aura.video.getInfo',
+      'aura.draw3d.billboard',
+      'aura.draw3d.clear3d',
+      'aura.draw3d.drawMesh',
+      'aura.mesh.createBox',
+      'aura.material.create',
+      'aura.camera3d.perspective',
+      'aura.camera3d.setPosition',
+      'aura.camera3d.lookAt',
+      'aura.light.ambient',
+      'aura.light.directional',
+      'aura.input.isKeyPressed',
+      'aura.window.getSize',
+      'aura.window.getFPS',
+      'aura.draw2d.clear',
+      'aura.draw2d.rect',
+      'aura.draw2d.text',
+      'aura.draw2d.measureText',
+      'aura.rgb',
+      'aura.rgba',
+      'aura.Color.WHITE',
+    ],
+    starterAssetPlan: {
+      file: 'cutscene-sequence.json',
+      title: 'Video Cutscene Sequence',
+      steps: [
+        'Plan your cutscene sequence here before spreading video paths across scene files.',
+        'Keep video files small (H.264 1080p recommended) for fast load times.',
+      ],
+      payload: {
+        sequence: [
+          { id: 'intro', videoPath: 'assets/video/intro.mp4', chapter: 0 },
+          { id: 'midpoint', videoPath: 'assets/video/midpoint.mp4', chapter: 1 },
+          { id: 'finale', videoPath: 'assets/video/finale.mp4', chapter: 2 },
+        ],
+      },
+    },
+    optionalModules: {
+      network: false,
+    },
+    configModules: {
+      network: false,
+    },
+    workflowTitle: 'Video Cutscene Authoring Loop',
+    workflowSteps: [
+      'Drop a test .mp4 in assets/video/ and run `npm run dev` to verify playback.',
+      'Tune fade speed and skip behavior in scenes/cutscene.scene.js.',
+      'Build your gameplay scene before adding more cutscene chapters.',
+    ],
+  },
+  blank: {
+    summary: 'Minimal blank loop with runtime API checks for quick custom starts.',
+    controls: [
+      'No controls wired yet.',
+      'Use scenes/ plus appState as your first structure instead of growing one big main.js file.',
+    ],
+    firstEdits: [
+      'Define cross-scene session state in src/runtime/app-state.js.',
+      'Keep live gameplay state inside scenes/ instead of global top-level variables.',
+      'Move defaults into config/ and authored nouns into content/ before systems grow.',
+      'Set modules and identity in aura.config.json.',
+      'Replace starter asset notes under assets/starter/.',
+    ],
+    keywords: ['blank', 'starter'],
+    requiredApis: [
+      'aura.draw2d.clear',
+      'aura.rgba',
+    ],
+    starterAssetPlan: {
+      file: 'starter-notes.json',
+      title: 'Blank Starter Notes',
+      steps: [
+        'Write your core loop goals before coding to keep agent prompts precise.',
+        'Track capability assumptions here as you expand runtime usage.',
+      ],
+      payload: {
+        goals: [
+          'Define camera and movement model.',
+          'Pick combat/progression loop.',
+          'Specify first milestone acceptance criteria.',
+        ],
+      },
+    },
+  },
+  'local-multiplayer': {
+    summary: 'Room-code multiplayer starter. `npm run dev` hosts, `npm run join -- CODE` joins, and `aura.config.json -> multiplayer` plus one relay host promotes the same flow to internet-backed hosting.',
+    controls: [
+      'Host movement: Arrow keys or WASD',
+      'Join movement: Arrow keys or WASD from a second terminal',
+      'Room-code flow: `npm run dev` hosts and `npm run join -- AURA2P` joins from a second terminal.',
+    ],
+    firstEdits: [
+      'Set room code, room name, relay defaults, and diagnostics in aura.config.json -> multiplayer.',
+      'Tune room timing, player bounds, and host fallback in config/gameplay/local-multiplayer.config.js.',
+      'Replace the spawn slots in content/gameplay/room-layout.js.',
+      'Extend the gameplay loop in scenes/gameplay.scene.js and ui/hud.screen.js before widening multiplayer scope.',
+    ],
+    keywords: ['multiplayer', 'local', 'native', 'room-code'],
+    requiredApis: [
+      'aura.input.isKeyDown',
+      'aura.draw2d.clear',
+      'aura.draw2d.rectFill',
+      'aura.draw2d.text',
+      'aura.rgb',
+      'aura.multiplayer.configure',
+      'aura.multiplayer.getAllPlayerInputs',
+      'aura.multiplayer.getAllState',
+      'aura.multiplayer.getPlayerCount',
+      'aura.multiplayer.getRoomInfo',
+      'aura.multiplayer.getState',
+      'aura.multiplayer.host',
+      'aura.multiplayer.isConnected',
+      'aura.multiplayer.onPlayerJoin',
+      'aura.multiplayer.onPlayerLeave',
+      'aura.multiplayer.sendInput',
+      'aura.multiplayer.setState',
+    ],
+    starterAssetPlan: {
+      file: 'room-layout.json',
+      title: 'Room-Code Multiplayer Room Layout',
+      steps: [
+        'Keep the default starter local-first: one room code and one authoritative host in the native dev loop.',
+        'For the fastest internet-backed upgrade, set aura.config.json -> multiplayer.relay to your relay host and keep the same room-code commands.',
+        'Use these spawn slots to rebalance the first room-code playtest before adding more systems.',
+      ],
+      payload: {
+        roomCode: 'AURA2P',
+        maxPlayers: 2,
+        spawnSlots: [
+          { id: 'host', x: 160, y: 240, label: 'host' },
+          { id: 'guest', x: 760, y: 240, label: 'guest' },
+        ],
+      },
+    },
+    includeSharedStarterUtils: true,
+    optionalModules: {
+      network: false,
+      multiplayer: true,
+    },
+    configModules: {
+      network: false,
+      multiplayer: true,
+    },
+    workflowTitle: 'Room-Code Multiplayer Loop',
+    workflowSteps: [
+      'Host the room in one terminal with `npm run dev`.',
+      'Join the room by code from a second terminal with `npm run join -- AURA2P`.',
+      'Keep the default loop local-first, or set aura.config.json -> multiplayer.relay for the fastest internet-backed room-code upgrade.',
+    ],
+  },
+  'retro-topdown-adventure': {
+    runtimeFamily: 'retro',
+    retroTemplateId: 'topdown-adventure',
+    summary: 'Retro-safe top-down exploration starter for the GB/GBC/GBA preview lane.',
+    controls: [
+      'Move: D-pad or arrow-style directional input',
+      'Build targets: `npm run build:gb`, `npm run build:gbc`, or `npm run build:gba`',
+    ],
+    firstEdits: [
+      'Replace the one-room route and hero nouns in src/main.js before widening scope.',
+      'Keep assets under assets/retro/assets.json inside the enforced target budgets.',
+      'Use `npm run retro:check` after each change so the validator stays your first feedback loop.',
+    ],
+    keywords: ['retro', 'gb', 'gbc', 'gba', 'topdown'],
+    requiredApis: [
+      'aura.input.pressed',
+      'aura.tilemap.setTile',
+      'aura.sprite.draw',
+      'aura.text.write',
+      'aura.save.write',
+    ],
+    optionalModules: {
+      network: false,
+      multiplayer: false,
+    },
+    configModules: {
+      network: false,
+      multiplayer: false,
+    },
+    workflowTitle: 'Retro Top-Down Loop',
+    workflowSteps: [
+      'Run `npm run retro:check` from the project root after each code or asset change.',
+      'Build the target you care about with `npm run build:gbc` or the stricter `npm run build:gb`.',
+      'Treat the generated ROM and preview artifacts as the ground truth, not desktop dev-session behavior.',
+    ],
+  },
+  'retro-puzzle-grid': {
+    runtimeFamily: 'retro',
+    retroTemplateId: 'puzzle-grid',
+    summary: 'Retro-safe one-screen puzzle starter for cartridge-style grid logic.',
+    controls: [
+      'Move cursor: D-pad or arrow-style directional input',
+      'Confirm/toggle: A button input',
+    ],
+    firstEdits: [
+      'Rewrite the board rule in src/main.js before adding extra verbs.',
+      'Keep tiles, sprites, and fonts small enough to pass the selected target profile.',
+      'Use `npm run retro:check` before every preview build.',
+    ],
+    keywords: ['retro', 'gb', 'gbc', 'gba', 'puzzle'],
+    requiredApis: [
+      'aura.input.pressed',
+      'aura.input.justPressed',
+      'aura.tilemap.setTile',
+      'aura.sprite.draw',
+      'aura.text.write',
+    ],
+    optionalModules: {
+      network: false,
+      multiplayer: false,
+    },
+    configModules: {
+      network: false,
+      multiplayer: false,
+    },
+    workflowTitle: 'Retro Puzzle Loop',
+    workflowSteps: [
+      'Validate with `npm run retro:check` before chasing polish.',
+      'Keep the board deterministic and one-screen until the target budgets feel obvious.',
+      'Use `npm run build:gbc` first, then rerun with `npm run build:gb` when you want the stricter profile.',
+    ],
+  },
+  'retro-tactics-grid': {
+    runtimeFamily: 'retro',
+    retroTemplateId: 'tactics-grid',
+    summary: 'Retro-safe turn-based tactics starter with tiny authored state and HUD output.',
+    controls: [
+      'Move selector: D-pad or arrow-style directional input',
+      'Act: A button input',
+      'End turn: B button input',
+    ],
+    firstEdits: [
+      'Replace the sample turn and AP rules in src/main.js with your own combat loop.',
+      'Keep unit presentation inside the retro sprite and tile budget instead of adding desktop systems.',
+      'Run `npm run retro:check` after each authored rules change.',
+    ],
+    keywords: ['retro', 'gb', 'gbc', 'gba', 'tactics'],
+    requiredApis: [
+      'aura.input.pressed',
+      'aura.input.justPressed',
+      'aura.tilemap.setTile',
+      'aura.sprite.draw',
+      'aura.text.write',
+      'aura.audio.playMusic',
+    ],
+    optionalModules: {
+      network: false,
+      multiplayer: false,
+    },
+    configModules: {
+      network: false,
+      multiplayer: false,
+    },
+    workflowTitle: 'Retro Tactics Loop',
+    workflowSteps: [
+      'Use `npm run retro:check` as the first pass for every authored rules edit.',
+      'Build `gbc` first, then rerun against `gb` to see which color-oriented assumptions fail.',
+      'Keep the template as a grid-and-sprite tactics shell, not a desktop simulation sandbox.',
+    ],
+  },
+  'retro-platformer': {
+    runtimeFamily: 'retro',
+    retroTemplateId: 'platformer',
+    summary: 'Retro-safe side-view platformer starter for GB/GBC/GBA preview builds.',
+    controls: [
+      'Move: D-pad or arrow-style directional input',
+      'Jump: A button input',
+    ],
+    firstEdits: [
+      'Tune jump feel and floor rules in src/main.js before expanding the level.',
+      'Stay inside retro-safe sprite, tile, and font counts while you iterate.',
+      'Use `npm run build:gbc` for the common path and `npm run build:gb` for the stricter mono profile.',
+    ],
+    keywords: ['retro', 'gb', 'gbc', 'gba', 'platformer'],
+    requiredApis: [
+      'aura.input.pressed',
+      'aura.input.justPressed',
+      'aura.tilemap.setTile',
+      'aura.sprite.draw',
+      'aura.text.write',
+    ],
+    optionalModules: {
+      network: false,
+      multiplayer: false,
+    },
+    configModules: {
+      network: false,
+      multiplayer: false,
+    },
+    workflowTitle: 'Retro Platformer Loop',
+    workflowSteps: [
+      'Run `npm run retro:check` first so the subset stays visible while you tune motion.',
+      'Build to `gbc` for the default ROM path, then compare with `gb` when you want the tighter profile.',
+      'Keep the starter as a simple movement-and-grounding loop instead of mixing in desktop runtime assumptions.',
+    ],
+  },
+};
+
+export function listCreateTemplates() {
+  return Object.keys(CREATE_TEMPLATE_DIRS);
+}
+
+export function listCreateTemplateAliasHints() {
+  return [...CREATE_TEMPLATE_ALIAS_HINTS];
+}
+
+export function normalizeCreateTemplate(template) {
+  const normalized = String(template || '').trim().toLowerCase();
+  return CREATE_TEMPLATE_ALIASES[normalized] || null;
+}
+
+
+export function sanitizeBinName(name) {
+  const normalized = String(name || '').trim();
+  const compact = normalized
+    .replace(/^@[^/]+\//, '')
+    .replace(/\s+/g, '-')
+    .replace(/[^a-zA-Z0-9._-]/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^[-._]+|[-._]+$/g, '')
+    .toLowerCase();
+
+  if (!compact) {
+    throw new Error(`Unable to derive executable name from project name "${name}".`);
+  }
+
+  return compact;
+}
+
+function sanitizePackageSlug(name) {
+  const normalized = String(name || '').trim();
+  const compact = normalized
+    .replace(/^@[^/]+\//, '')
+    .replace(/\s+/g, '-')
+    .replace(/[^a-zA-Z0-9._-]/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^[-._]+|[-._]+$/g, '')
+    .toLowerCase();
+
+  if (!compact) {
+    throw new Error(`Unable to derive package slug from project name "${name}".`);
+  }
+
+  return compact;
+}
+
+export function toDisplayTitle(name) {
+  const cleaned = String(name || '').replace(/^@[^/]+\//, '');
+  const words = cleaned.split(/[-_\s]+/).filter(Boolean);
+  if (words.length === 0) return String(name || '').trim() || 'AuraJS Game';
+  return words.map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(' ');
+}
+
+export function resolveSkillsSourceDir() {
+  if (existsSync(ROOT_SKILLS_DIR)) return ROOT_SKILLS_DIR;
+  if (existsSync(PACKAGED_SKILLS_DIR)) return PACKAGED_SKILLS_DIR;
+  return null;
+}
+
+export function resolveTemplateMetadata(template) {
+  return CREATE_TEMPLATE_METADATA[template] || CREATE_TEMPLATE_METADATA.blank;
+}
+
+export function shouldCopyCreateSharedTemplate(template, templateMetadata) {
+  if (templateMetadata?.runtimeFamily === 'retro') return false;
+  if (templateMetadata?.includeSharedStarterUtils === true) return true;
+  if (templateMetadata?.includeSharedStarterUtils === false) return false;
+  return template !== 'blank';
+}
+
+export function applyTemplateConfigOverrides({ dest, templateMetadata }) {
+  if (!templateMetadata?.configModules) return;
+  const configPath = join(dest, 'aura.config.json');
+  if (!existsSync(configPath)) return;
+
+  const config = JSON.parse(readFileSync(configPath, 'utf8'));
+  config.modules = {
+    ...(config.modules || {}),
+    ...templateMetadata.configModules,
+  };
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+}
+
+export function buildPackageJson({ name, version, license, binName, template, templateMetadata }) {
+  const packageSlug = sanitizePackageSlug(name);
+  const packageName = `@aurajs/${packageSlug}`;
+  const keywords = ['aurajs', 'game', ...(templateMetadata?.keywords || [])];
+  if (templateMetadata?.runtimeFamily === 'retro') {
+    return {
+      name: packageName,
+      version,
+      description: `${toDisplayTitle(name)} — Aura Retro starter`,
+      type: 'module',
+      files: ['src/', 'assets/', 'aura.config.json', 'aura.capabilities.json', 'README.md', 'RUNBOOK.md'],
+      scripts: {
+        'retro:check': 'aura retro check --target gbc',
+        'retro:explain': 'aura retro explain --target gbc',
+        build: 'aura build --target gbc',
+        'build:gb': 'aura build --target gb',
+        'build:gbc': 'aura build --target gbc',
+        'build:gba': 'aura build --target gba',
+      },
+      dependencies: {
+        '@auraindustry/aurajs': CLI_PACKAGE_VERSION,
+      },
+      publishConfig: {
+        access: 'public',
+      },
+      keywords,
+      license,
+    };
+  }
+  const files = ['bin/', 'src/', 'assets/', 'skills/', 'aura.config.json', 'aura.capabilities.json', 'README.md', 'RUNBOOK.md'];
+  files.splice(3, 0, 'config/', 'content/', 'docs/', 'prefabs/', 'scenes/', 'ui/');
+
+  const scripts = {
+    dev: 'node ./bin/play.js dev',
+    build: 'aura build',
+    play: 'node ./bin/play.js play',
+    publish: 'node ./bin/play.js publish',
+    session: 'node ./bin/play.js session',
+    state: 'node ./bin/play.js state',
+    inspect: 'node ./bin/play.js inspect',
+    action: 'node ./bin/play.js action',
+  };
+
+  if (templateMetadata?.optionalModules?.multiplayer === true) {
+    scripts.join = 'node ./bin/play.js join --launch-mode dev';
+  }
+
+  return {
+    name: packageName,
+    version,
+    description: `${toDisplayTitle(name)} — built with AuraJS`,
+    type: 'module',
+    bin: {
+      [binName]: './bin/play.js',
+    },
+    files,
+    scripts,
+    dependencies: {
+      '@auraindustry/aurajs': CLI_PACKAGE_VERSION,
+    },
+    publishConfig: {
+      access: 'public',
+    },
+    keywords,
+    license,
+  };
+}
+
+export function buildCapabilitiesDeclaration({ template, templateMetadata }) {
+  const optionalModules = {
+    physics: false,
+    network: true,
+    multiplayer: false,
+    steam: false,
+    ...(templateMetadata?.optionalModules || {}),
+  };
+
+  return {
+    schema: 'aurajs.create-capabilities.v1',
+    template,
+    summary: templateMetadata.summary,
+    requiredApis: [...templateMetadata.requiredApis],
+    optionalModules,
+    notes: [
+      'Keep this file in sync with runtime API usage added in src/main.js, src/runtime/, and authored scene files.',
+      'Treat missing APIs as scaffold contract mismatches, not silent fallbacks.',
+    ],
+  };
+}