@auraindustry/aurajs 0.0.5 → 0.0.6

package/src/perf-benchmark.mjs

@@ -114,6 +114,109 @@ export const DEFAULT_PERF_SCENES = [
       };
     `,
   },
+  {
+    id: 'tilemap_particles_stress',
+    frames: 360,
+    source: `
+      let mapId = 0;
+      let elapsed = 0;
+      let canUseParticles = false;
+      const fallbackParticles = [];
+
+      aura.setup = function () {
+        const width = 32;
+        const height = 24;
+        const tileCount = width * height;
+        const ground = Array.from({ length: tileCount }, () => 1);
+        const decor = Array.from({ length: tileCount }, (_, index) => ((index + Math.floor(index / width)) % 3 === 0 ? 1 : 0));
+
+        mapId = aura.tilemap.import({
+          width,
+          height,
+          tilewidth: 16,
+          tileheight: 16,
+          layers: [
+            { name: 'ground', type: 'tilelayer', width, height, data: ground },
+            { name: 'decor', type: 'tilelayer', width, height, data: decor },
+          ],
+          tilesets: [
+            { firstgid: 1, image: 'player.png', tilewidth: 16, tileheight: 16, tilecount: 1, columns: 1 },
+          ],
+        });
+
+        canUseParticles = !!(
+          aura.particles
+          && typeof aura.particles.emit === 'function'
+          && typeof aura.particles.update === 'function'
+          && typeof aura.particles.draw === 'function'
+        );
+
+        for (let i = 0; i < 6; i += 1) {
+          const originX = 48 + (i * 32);
+          const originY = 72 + ((i % 3) * 36);
+          if (canUseParticles) {
+            aura.particles.emit({
+              x: originX,
+              y: originY,
+              count: 24,
+              life: 0.8,
+              size: 2,
+              speedMin: 12,
+              speedMax: 18,
+              direction: i * 0.35,
+              spread: 1.2,
+              loop: true,
+              rate: 40,
+            });
+            continue;
+          }
+
+          for (let j = 0; j < 24; j += 1) {
+            fallbackParticles.push({
+              originX,
+              originY,
+              phase: (i * 0.6) + (j * 0.21),
+              radius: 4 + ((j % 6) * 3),
+              speed: 0.8 + ((j % 5) * 0.14),
+            });
+          }
+        }
+      };
+
+      aura.update = function (dt) {
+        elapsed += dt;
+        if (canUseParticles) {
+          aura.particles.update(dt);
+        }
+      };
+
+      aura.draw = function () {
+        aura.draw2d.clear(4, 6, 10);
+
+        const camera = {
+          x: 64 + ((Math.sin(elapsed * 0.8) + 1) * 64),
+          y: 32 + ((Math.cos(elapsed * 0.6) + 1) * 40),
+          width: 320,
+          height: 192,
+        };
+
+        aura.tilemap.draw(mapId, { camera });
+
+        if (canUseParticles) {
+          aura.particles.draw({ maxParticles: 512 });
+          return;
+        }
+
+        for (let i = 0; i < fallbackParticles.length; i += 1) {
+          const particle = fallbackParticles[i];
+          const theta = (elapsed * particle.speed * 3.0) + particle.phase;
+          const x = particle.originX + Math.cos(theta) * particle.radius;
+          const y = particle.originY + Math.sin(theta * 1.3) * (particle.radius * 0.8);
+          aura.draw2d.circle(x, y, 2, aura.colors.white);
+        }
+      };
+    `,
+  },
 ];
 
 function mean(values) {

package/src/scaffold.mjs

@@ -8,7 +8,9 @@ const LEGACY_STARTER_TEMPLATE_DIR = resolve(CLI_SRC_DIR, '../templates/starter')
 
 const CREATE_TEMPLATE_DIRS = {
   '2d-shooter': resolve(CLI_SRC_DIR, '../templates/create/2d'),
+  '2d-survivor': resolve(CLI_SRC_DIR, '../templates/create/2d-survivor'),
   '3d-platformer': resolve(CLI_SRC_DIR, '../templates/create/3d'),
+  '3d-collectathon': resolve(CLI_SRC_DIR, '../templates/create/3d-collectathon'),
   blank: resolve(CLI_SRC_DIR, '../templates/create/blank'),
 };
 const CREATE_SHARED_TEMPLATE_DIR = resolve(CLI_SRC_DIR, '../templates/create/shared');
@@ -18,14 +20,27 @@ const CREATE_TEMPLATE_ALIASES = {
   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',
   '3d': '3d-platformer',
   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',
   blank: 'blank',
 };
+const CREATE_TEMPLATE_ALIAS_HINTS = ['2d', '3d', 'shooter', 'platformer', 'survivor', 'collectathon', 'blank'];
 
 const ROOT_SKILLS_DIR = resolve(CLI_SRC_DIR, '../../../skills');
 const PACKAGED_SKILLS_DIR = resolve(CLI_SRC_DIR, '../templates/skills');
@@ -95,10 +110,227 @@ child.on('close', (code) => {
 });
 `;
 
+const CREATE_TEMPLATE_METADATA = {
+  '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 src/main.js -> WAVE_CONFIG.',
+      'Add custom enemy variants in src/starter-utils/enemy-archetypes-2d.js.',
+      'Swap starter palette and HUD text in src/main.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 src/main.js -> spawnDirector + difficulty ramps.',
+      'Tune dash timings in src/main.js constants.',
+      'Extend enemy archetypes in src/starter-utils/enemy-archetypes-2d.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 },
+        ],
+      },
+    },
+  },
+  '3d-platformer': {
+    summary: '3D checkpoint platformer loop with moving platform helper primitives.',
+    controls: [
+      'Move: Arrow keys or WASD',
+      'Jump: Space',
+      'Restart: Enter (after goal)',
+    ],
+    firstEdits: [
+      'Adjust traversal beats in src/main.js -> STATIC_PLATFORMS and CHECKPOINTS.',
+      'Tune camera offsets in aura.update.',
+      'Swap material colors in aura.setup for your theme.',
+    ],
+    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.input.isKeyDown',
+      'aura.input.isKeyPressed',
+      '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 timer pressure and checkpoint fallback.',
+    controls: [
+      'Move: Arrow keys or WASD',
+      'Jump: Space',
+      'Restart: Enter (after clear/failure)',
+    ],
+    firstEdits: [
+      'Add world pieces in src/main.js -> WORLD_PLATFORMS + COLLECTIBLES.',
+      'Balance the timer and required collectible count in constants.',
+      'Customize checkpoint/goal feedback text in aura.draw.',
+    ],
+    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.input.isKeyDown',
+      'aura.input.isKeyPressed',
+      '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 },
+        ],
+      },
+    },
+  },
+  blank: {
+    summary: 'Minimal blank loop with runtime API checks for quick custom starts.',
+    controls: [
+      'No controls wired yet.',
+      'Add input + systems directly in src/main.js.',
+    ],
+    firstEdits: [
+      'Define your own game-state object and update loop in src/main.js.',
+      '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.',
+        ],
+      },
+    },
+  },
+};
+
 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;
@@ -126,7 +358,7 @@ export function scaffold(name, dest) {
  * @param {object} options - Scaffolding options.
  * @param {string} options.name - Project directory name (npm package defaults to @aurajs/<name>).
  * @param {string} options.dest - Absolute destination directory.
- * @param {string} [options.template='2d-shooter'] - Template key: 2d-shooter | 3d-platformer | blank.
+ * @param {string} [options.template='2d-shooter'] - Template key from listCreateTemplates().
  * @param {string} [options.version='0.1.0'] - Initial package version.
  * @param {string} [options.license='MIT'] - Initial package license.
  */
@@ -143,7 +375,7 @@ export function scaffoldGame(options) {
   const templateDir = CREATE_TEMPLATE_DIRS[normalizedTemplate];
   if (!templateDir || !existsSync(templateDir)) {
     throw new Error(
-      `Unknown template "${template}". Expected one of: ${listCreateTemplates().join(', ')} (aliases: 2d, 3d, shooter, platformer, blank).`,
+      `Unknown template "${template}". Expected one of: ${listCreateTemplates().join(', ')} (aliases: ${listCreateTemplateAliasHints().join(', ')}).`,
     );
   }
 
@@ -158,6 +390,7 @@ export function scaffoldGame(options) {
     PROJECT_VERSION: version,
     PROJECT_LICENSE: license,
   };
+  const templateMetadata = resolveTemplateMetadata(normalizedTemplate);
 
   copyTree(templateDir, dest, replacements);
   if (normalizedTemplate !== 'blank' && existsSync(CREATE_SHARED_TEMPLATE_DIR)) {
@@ -174,12 +407,35 @@ export function scaffoldGame(options) {
     version,
     license,
     binName,
-    template: normalizedTemplate,
+    templateMetadata,
   });
 
   writeFileSync(join(dest, 'package.json'), JSON.stringify(pkg, null, 2) + '\n', 'utf8');
   writeFileSync(join(dest, '.gitignore'), GITIGNORE_TEMPLATE, 'utf8');
   writeFileSync(join(dest, 'bin', 'play.js'), PLAY_BIN_TEMPLATE, { encoding: 'utf8', mode: 0o755 });
+  writeFileSync(
+    join(dest, 'README.md'),
+    renderProjectReadme({ name, projectTitle, template: normalizedTemplate, templateMetadata }),
+    'utf8',
+  );
+  writeFileSync(
+    join(dest, 'RUNBOOK.md'),
+    renderProjectRunbook({ name, projectTitle, template: normalizedTemplate, templateMetadata }),
+    'utf8',
+  );
+  writeFileSync(
+    join(dest, 'aura.capabilities.json'),
+    JSON.stringify(
+      buildCapabilitiesDeclaration({
+        template: normalizedTemplate,
+        templateMetadata,
+      }),
+      null,
+      2,
+    ) + '\n',
+    'utf8',
+  );
+  writeStarterAssetPack({ dest, projectTitle, template: normalizedTemplate, templateMetadata });
 
   const skillsSource = resolveSkillsSourceDir();
   if (skillsSource) {
@@ -242,17 +498,14 @@ function resolveSkillsSourceDir() {
   return null;
 }
 
-function buildPackageJson({ name, version, license, binName, template }) {
+function resolveTemplateMetadata(template) {
+  return CREATE_TEMPLATE_METADATA[template] || CREATE_TEMPLATE_METADATA.blank;
+}
+
+function buildPackageJson({ name, version, license, binName, templateMetadata }) {
   const packageSlug = sanitizePackageSlug(name);
   const packageName = `@aurajs/${packageSlug}`;
-  const keywords = ['aurajs', 'game'];
-  if (template.includes('3d')) {
-    keywords.push('3d');
-    keywords.push('platformer');
-  } else if (template.includes('2d')) {
-    keywords.push('2d');
-    keywords.push('shooter');
-  }
+  const keywords = ['aurajs', 'game', ...(templateMetadata?.keywords || [])];
 
   return {
     name: packageName,
@@ -262,7 +515,7 @@ function buildPackageJson({ name, version, license, binName, template }) {
     bin: {
       [binName]: './bin/play.js',
     },
-    files: ['bin/', 'src/', 'assets/', 'skills/', 'aura.config.json'],
+    files: ['bin/', 'src/', 'assets/', 'skills/', 'aura.config.json', 'aura.capabilities.json', 'README.md', 'RUNBOOK.md'],
     scripts: {
       dev: 'aura dev',
       build: 'aura build',
@@ -277,6 +530,153 @@ function buildPackageJson({ name, version, license, binName, template }) {
   };
 }
 
+function buildCapabilitiesDeclaration({ template, templateMetadata }) {
+  return {
+    schema: 'aurajs.create-capabilities.v1',
+    template,
+    summary: templateMetadata.summary,
+    requiredApis: [...templateMetadata.requiredApis],
+    optionalModules: {
+      physics: false,
+      network: true,
+      multiplayer: false,
+      steam: false,
+    },
+    notes: [
+      'Keep this file in sync with runtime API usage added in src/main.js.',
+      'Treat missing APIs as scaffold contract mismatches, not silent fallbacks.',
+    ],
+  };
+}
+
+function renderProjectReadme({ name, projectTitle, template, templateMetadata }) {
+  const controls = templateMetadata.controls.map((line) => `- ${line}`).join('\n');
+  const firstEdits = templateMetadata.firstEdits.map((line) => `1. ${line}`).join('\n');
+
+  return `# ${projectTitle}
+
+Scaffolded with \`aura create ${name} --template ${template}\`.
+
+## Quick Start
+
+\`\`\`bash
+npm install
+npm run dev
+\`\`\`
+
+Optional commands:
+
+\`\`\`bash
+npm run build
+npm run play
+npm run publish
+\`\`\`
+
+## Template Summary
+
+${templateMetadata.summary}
+
+## Controls
+
+${controls}
+
+## Project Map
+
+- \`src/main.js\` - gameplay loop and rendering.
+- \`src/starter-utils/\` - reusable helpers copied for non-blank templates.
+- \`assets/starter/\` - starter asset pack and editable design payloads.
+- \`aura.config.json\` - identity/window/build/modules.
+- \`aura.capabilities.json\` - canonical runtime API declaration for this scaffold.
+- \`RUNBOOK.md\` - first-hour implementation and triage checklist.
+
+## First Edits
+
+${firstEdits}
+`;
+}
+
+function renderProjectRunbook({ projectTitle, template, templateMetadata }) {
+  const firstEdits = templateMetadata.firstEdits.map((line) => `1. ${line}`).join('\n');
+  const requiredApis = templateMetadata.requiredApis.map((entry) => `- \`${entry}\``).join('\n');
+
+  return `# ${projectTitle} Runbook
+
+Template: \`${template}\`
+
+## First 30 Minutes
+
+1. Run \`npm install\` then \`npm run dev\` and confirm the starter loop is playable.
+1. Read \`src/main.js\` once end-to-end before editing prompts or logic.
+1. Review \`assets/starter/\` and replace placeholder payloads with game-specific values.
+
+## First-Hour Implementation Pass
+
+${firstEdits}
+
+## Capability Contract
+
+The scaffold assumes the runtime APIs below:
+
+${requiredApis}
+
+If any are unavailable at runtime, fail fast and capture the reason code before adding fallback behavior.
+
+## Build + Share
+
+1. \`npm run build\` to emit native/web artifacts.
+1. \`npm run play\` to package + execute with sibling assets.
+1. \`npm run publish\` once metadata and binaries are ready.
+`;
+}
+
+function writeStarterAssetPack({ dest, projectTitle, template, templateMetadata }) {
+  const starterDir = join(dest, 'assets', 'starter');
+  mkdirSync(starterDir, { recursive: true });
+
+  writeFileSync(
+    join(starterDir, 'README.md'),
+    `# ${projectTitle} Starter Assets
+
+Template: \`${template}\`
+
+Use this folder as the first source of truth for seed content:
+
+- Keep machine-readable balancing data in JSON files.
+- Store design intent in markdown notes so agents can edit safely.
+- Replace placeholders as soon as your core loop is stable.
+`,
+    'utf8',
+  );
+
+  writeFileSync(
+    join(starterDir, 'dev-notes.md'),
+    `# First Pass Notes
+
+- Core loop hypothesis:
+- Success metric for this week:
+- Next three gameplay experiments:
+`,
+    'utf8',
+  );
+
+  const plan = templateMetadata.starterAssetPlan;
+  writeFileSync(
+    join(starterDir, plan.file),
+    JSON.stringify(
+      {
+        schema: 'aurajs.starter-asset-plan.v1',
+        title: plan.title,
+        template,
+        steps: plan.steps,
+        payload: plan.payload,
+      },
+      null,
+      2,
+    ) + '\n',
+    'utf8',
+  );
+}
+
 function assertDestinationIsEmpty(name, dest) {
   if (existsSync(dest)) {
     const entries = readdirSync(dest);