@auraindustry/aurajs 0.0.7 → 0.1.0

package/src/scaffold/fs.mjs

@@ -0,0 +1,56 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export function writeGeneratedFile(filePath, content, { overwrite = false } = {}) {
+  mkdirSync(dirname(filePath), { recursive: true });
+  if (!overwrite && existsSync(filePath)) {
+    return;
+  }
+  writeFileSync(filePath, content, 'utf8');
+}
+
+export function assertDestinationIsEmpty(name, dest) {
+  if (!existsSync(dest)) {
+    return;
+  }
+
+  const entries = readdirSync(dest);
+  if (entries.length > 0) {
+    throw new Error(`Directory "${name}" already exists and is not empty.`);
+  }
+}
+
+export function copyTree(src, dest, replacements) {
+  mkdirSync(dest, { recursive: true });
+
+  for (const entry of readdirSync(src)) {
+    const srcPath = join(src, entry);
+    const destPath = join(dest, entry);
+    const stat = statSync(srcPath);
+
+    if (stat.isDirectory()) {
+      copyTree(srcPath, destPath, replacements);
+      continue;
+    }
+
+    let content = readFileSync(srcPath, 'utf8');
+    for (const [key, value] of Object.entries(replacements)) {
+      content = content.replaceAll(`{{${key}}}`, value);
+    }
+    writeFileSync(destPath, content, 'utf8');
+  }
+}
+
+export function listFiles(dir, prefix = '') {
+  const files = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    const rel = prefix ? `${prefix}/${entry}` : entry;
+    if (statSync(full).isDirectory()) {
+      files.push(...listFiles(full, rel));
+      continue;
+    }
+    files.push(rel);
+  }
+  return files;
+}

package/src/scaffold/layout.mjs

@@ -0,0 +1,318 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  buildStarterRegistryEntries,
+  createStarterProjectRegistry,
+  writeProjectRegistryFiles,
+} from '../project-registry.mjs';
+import {
+  PROJECT_MAIN_ENTRY_RELATIVE_PATH,
+  PROJECT_RUNTIME_APP_RELATIVE_PATH,
+  PROJECT_RUNTIME_APP_STATE_RELATIVE_PATH,
+  PROJECT_RUNTIME_CAPABILITIES_RELATIVE_PATH,
+  PROJECT_RUNTIME_INSPECTOR_RELATIVE_PATH,
+  PROJECT_RUNTIME_SCENE_FLOW_RELATIVE_PATH,
+  PROJECT_RUNTIME_SCREEN_SHELL_RELATIVE_PATH,
+  PROJECT_RUNTIME_UI_FORMS_RELATIVE_PATH,
+  PROJECT_RUNTIME_UI_SETTINGS_RELATIVE_PATH,
+  PROJECT_RUNTIME_UI_THEME_RELATIVE_PATH,
+  renderAppStateModule,
+  renderBlankRuntimeCapabilitiesModule,
+  renderProjectInspectorModule,
+  renderRegistryBackedMainEntry,
+  renderRegistryBackedRuntimeApp,
+  renderSceneFlowModule,
+  renderScreenShellModule,
+  renderUiFormsModule,
+  renderUiSettingsModule,
+  renderUiThemeModule,
+} from '../authored-runtime.mjs';
+import { renderContentMapDoc, renderGamePillarsDoc } from './project-docs.mjs';
+import { writeGeneratedFile } from './fs.mjs';
+const UNITY_LIKE_EMPTY_DIRS = [
+  'assets/audio',
+  'assets/fonts',
+  'assets/materials',
+  'assets/models',
+  'assets/shaders',
+  'assets/sprites',
+  'assets/textures',
+  'assets/tilesets',
+  'assets/ui',
+  'config/balance',
+  'content/localization',
+  'src/components',
+  'src/gameplay',
+  'src/shared',
+  'src/systems',
+  'tests/smoke',
+];
+
+export function writeStarterAssetPack({ dest, projectTitle, template, templateMetadata }) {
+  const starterDir = join(dest, 'assets', 'starter');
+  const plan = templateMetadata.starterAssetPlan;
+  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 or JS modules that stay easy to diff.
+- Store design intent in markdown notes so agents can edit safely.
+- Start with \`${plan.file}\` and \`dev-notes.md\` before creating more files.
+- Rename starter ids, rebalance values, and narrow scope as soon as your first playable loop is clear.
+`,
+    'utf8',
+  );
+
+  writeFileSync(
+    join(starterDir, 'dev-notes.md'),
+    `# First Pass Notes
+
+Template summary: ${templateMetadata.summary}
+
+## First playable target
+
+- What should the player accomplish in the first 60 seconds?
+- Which values in \`${plan.file}\` need to change first?
+- Which one of these scaffold edits matters most this week?
+
+## This week
+
+- Core loop hypothesis:
+- Success metric for this week:
+- Next three gameplay experiments:
+
+## Starter edit checklist
+
+- ${templateMetadata.firstEdits.join('\n- ')}
+`,
+    'utf8',
+  );
+
+  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',
+  );
+}
+
+export function writeUnityLikeProjectLayout({ dest, projectTitle, template, templateMetadata }) {
+  for (const dir of UNITY_LIKE_EMPTY_DIRS) {
+    mkdirSync(join(dest, dir), { recursive: true });
+    writeFileSync(join(dest, dir, '.gitkeep'), '', 'utf8');
+  }
+
+  const authoredDirs = ['config/gameplay', 'content/gameplay', 'content/registries', 'docs/design', 'prefabs', 'scenes', 'src/runtime', 'ui'];
+  for (const dir of authoredDirs) {
+    mkdirSync(join(dest, dir), { recursive: true });
+  }
+
+  const files = {
+    'config/gameplay/game.config.json': renderSharedGameplayConfig({ projectTitle, template }),
+    'docs/design/content-map.md': renderContentMapDoc({ template }),
+    'docs/design/game-pillars.md': renderGamePillarsDoc({ projectTitle, templateMetadata }),
+    'prefabs/player.prefab.js': renderPlayerPrefab({ template }),
+    'scenes/boot.scene.js': renderBootScene({ template }),
+    'scenes/gameplay.scene.js': renderGameplayScene({ template, templateMetadata }),
+    [PROJECT_MAIN_ENTRY_RELATIVE_PATH]: renderRegistryBackedMainEntry({
+      projectTitle,
+      starterLabel: describeStarterLabel(template),
+    }),
+    [PROJECT_RUNTIME_APP_RELATIVE_PATH]: renderRegistryBackedRuntimeApp({ template }),
+    [PROJECT_RUNTIME_APP_STATE_RELATIVE_PATH]: renderAppStateModule(),
+    [PROJECT_RUNTIME_SCENE_FLOW_RELATIVE_PATH]: renderSceneFlowModule(),
+    [PROJECT_RUNTIME_SCREEN_SHELL_RELATIVE_PATH]: renderScreenShellModule(),
+    [PROJECT_RUNTIME_INSPECTOR_RELATIVE_PATH]: renderProjectInspectorModule(),
+    [PROJECT_RUNTIME_UI_THEME_RELATIVE_PATH]: renderUiThemeModule(),
+    [PROJECT_RUNTIME_UI_SETTINGS_RELATIVE_PATH]: renderUiSettingsModule(),
+    [PROJECT_RUNTIME_UI_FORMS_RELATIVE_PATH]: renderUiFormsModule(),
+    'ui/hud.screen.js': renderHudScreen({ template }),
+  };
+  if (template === 'blank') {
+    files[PROJECT_RUNTIME_CAPABILITIES_RELATIVE_PATH] = renderBlankRuntimeCapabilitiesModule();
+  }
+
+  for (const [relativePath, content] of Object.entries(files)) {
+    writeGeneratedFile(join(dest, relativePath), content, {
+      overwrite: relativePath === PROJECT_MAIN_ENTRY_RELATIVE_PATH
+        || relativePath === PROJECT_RUNTIME_APP_RELATIVE_PATH
+        || relativePath === PROJECT_RUNTIME_APP_STATE_RELATIVE_PATH
+        || relativePath === PROJECT_RUNTIME_CAPABILITIES_RELATIVE_PATH
+        || relativePath === PROJECT_RUNTIME_SCENE_FLOW_RELATIVE_PATH
+        || relativePath === PROJECT_RUNTIME_SCREEN_SHELL_RELATIVE_PATH
+        || relativePath === PROJECT_RUNTIME_INSPECTOR_RELATIVE_PATH
+        || relativePath === PROJECT_RUNTIME_UI_THEME_RELATIVE_PATH
+        || relativePath === PROJECT_RUNTIME_UI_SETTINGS_RELATIVE_PATH
+        || relativePath === PROJECT_RUNTIME_UI_FORMS_RELATIVE_PATH,
+    });
+  }
+
+  const starterRegistry = createStarterProjectRegistry({
+    template,
+    projectTitle,
+    ...buildStarterRegistryEntries(template),
+  });
+  writeProjectRegistryFiles({
+    projectRoot: dest,
+    registry: starterRegistry,
+  });
+}
+
+function renderSharedGameplayConfig({ projectTitle, template }) {
+  return JSON.stringify(
+    {
+      schema: 'aurajs.game-config.v1',
+      projectTitle,
+      template,
+      startingSceneId: 'gameplay',
+      gameplaySceneId: 'gameplay',
+      hudScreenId: 'hud',
+      playerPrefabId: 'player',
+      notes: [
+        'Keep fast-tuning values here before they harden into runtime systems.',
+        'Put reusable authored nouns in content/ and keep live gameplay state in scenes/.',
+      ],
+    },
+    null,
+    2,
+  ) + '\n';
+}
+
+function describeStarterLabel(template) {
+  switch (template) {
+    case '2d-adventure':
+      return '2D adventure';
+    case '2d-shooter':
+      return '2D shooter';
+    case '2d-survivor':
+      return '2D survivor';
+    case '3d-adventure':
+      return '3D adventure';
+    case '3d-platformer':
+      return '3D platformer';
+    case '3d-collectathon':
+      return '3D collectathon';
+    case 'deckbuilder-2d':
+      return 'deckbuilder';
+    case 'blank':
+      return 'blank';
+    default:
+      return String(template || 'authored project').replace(/-/g, ' ');
+  }
+}
+
+function renderPlayerPrefab({ template }) {
+  const view = template.startsWith('3d')
+    ? { kind: 'actor3d', collider: { shape: 'box', size: { x: 0.9, y: 1.1, z: 0.9 } } }
+    : { kind: 'actor2d', collider: { shape: 'rect', size: { x: 34, y: 26 } } };
+
+  return `const playerPrefab = ${JSON.stringify(
+    {
+      id: 'player',
+      kind: 'prefab',
+      role: 'player',
+      view,
+      components: {
+        movementProfile: template.startsWith('3d') ? 'platformer' : 'arcade',
+      },
+      hooks: {},
+      notes: ['Convert this object into your real spawn/config contract as systems stabilize.'],
+    },
+    null,
+    2,
+  )};
+
+export function createPlayerPrefab() {
+  return playerPrefab;
+}
+
+export default playerPrefab;
+`;
+}
+
+function renderBootScene({ template }) {
+  return `export function createBootScene() {
+  return {
+    id: 'boot',
+    template: ${JSON.stringify(template)},
+    nextSceneId: 'gameplay',
+    notes: [
+      'Use this scene for splash, loading, title flow, and session handoff.',
+      'Keep long-lived boot orchestration here instead of bloating src/main.js.',
+      'Keep save or checkpoint resume handoff in src/runtime and appState instead of ad hoc globals.',
+    ],
+  };
+}
+`;
+}
+
+function renderGameplayScene({ template, templateMetadata }) {
+  return `export function createGameplayScene(context = {}) {
+  const sceneState = {
+    frame: 0,
+  };
+  return {
+    id: 'gameplay',
+    template: ${JSON.stringify(template)},
+    summary: ${JSON.stringify(templateMetadata.summary)},
+    playerPrefabId: 'player',
+    hudScreenId: 'hud',
+    dataFiles: ['config/gameplay/game.config.json'],
+    setup() {
+      context.appState = context.appState || {};
+      context.appState.session = context.appState.session || {};
+      context.appState.session.lastSceneId = 'gameplay';
+      sceneState.frame = 0;
+    },
+    update() {
+      sceneState.frame += 1;
+    },
+    getState() {
+      return {
+        sceneState,
+      };
+    },
+    notes: [
+      'Keep scene-local mutable state here instead of promoting it into appState too early.',
+      'Use appState for shared session data, config/ for tunables, and content/ for authored nouns.',
+      'If this scene must survive save or restart continuity, keep sceneState JSON-safe and expose it through getState().',
+    ],
+  };
+}
+`;
+}
+
+function renderHudScreen({ template }) {
+  return `const hudScreen = {
+  id: 'hud',
+  kind: 'ui-screen',
+  template: ${JSON.stringify(template)},
+  anchors: [
+    { id: 'status', corner: 'top-left' },
+    { id: 'objectives', corner: 'top-right' },
+  ],
+  notes: ['Keep HUD ownership here even if some draw calls still route through runtime helpers.'],
+};
+
+export function createHudScreen() {
+  return hudScreen;
+}
+
+export default hudScreen;
+`;
+}