@auraindustry/aurajs 0.1.3 → 0.1.5

package/README.md

@@ -4,6 +4,13 @@
 
 Write games in JavaScript and build native binaries for macOS, Linux, and Windows.
 
+Current mobile build truth:
+
+- `aura build --target android|ios|mobile` stages mobile package roots in v1
+- `build/android/android-build-manifest.json` and `build/ios/ios-build-manifest.json` are the target-owned truth surfaces
+- `aura run` remains desktop/web only; mobile targets hand off to the staged package lane
+- shared mobile capability conformance reason-codes desktop-only assumptions instead of implying parity
+
 ## Create A New Game
 
 ```bash

package/benchmarks/perf-thresholds.json

@@ -41,6 +41,15 @@
       "maxP99FrameTimeMs": 48,
       "maxStutterBurstCount": 12
     },
+    "native_2d_flagship_stress": {
+      "maxAvgFrameTimeMs": 36,
+      "maxJitterMs": 14,
+      "minFps": 18,
+      "maxP50FrameTimeMs": 36,
+      "maxP95FrameTimeMs": 52,
+      "maxP99FrameTimeMs": 64,
+      "maxStutterBurstCount": 16
+    },
     "ui_composition_surface_stress": {
       "maxAvgFrameTimeMs": 26,
       "maxJitterMs": 10,
@@ -98,6 +107,15 @@
         "maxP99FrameTimeMs": 56,
         "maxStutterBurstCount": 3
       },
+      "native_2d_flagship_stress": {
+        "maxAvgFrameTimeMs": 44,
+        "maxJitterMs": 16,
+        "minFps": 16,
+        "maxP50FrameTimeMs": 44,
+        "maxP95FrameTimeMs": 60,
+        "maxP99FrameTimeMs": 72,
+        "maxStutterBurstCount": 4
+      },
       "ui_composition_surface_stress": {
         "maxAvgFrameTimeMs": 34,
         "maxJitterMs": 12,
@@ -156,6 +174,15 @@
         "maxP99FrameTimeMs": 40,
         "maxStutterBurstCount": 10
       },
+      "native_2d_flagship_stress": {
+        "maxAvgFrameTimeMs": 32,
+        "maxJitterMs": 10,
+        "minFps": 20,
+        "maxP50FrameTimeMs": 32,
+        "maxP95FrameTimeMs": 44,
+        "maxP99FrameTimeMs": 52,
+        "maxStutterBurstCount": 14
+      },
       "ui_composition_surface_stress": {
         "maxAvgFrameTimeMs": 24,
         "maxJitterMs": 8,

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@auraindustry/aurajs",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Write games in JavaScript, build native binaries.",
   "type": "module",
   "exports": {
     "./cutscene": "./src/cutscene.mjs",
+    "./helpers": "./src/helpers/index.mjs",
+    "./helpers/2d": "./src/helpers/2d/index.mjs",
+    "./helpers/starter-utils/*": "./src/helpers/starter-utils/*.js",
     "./scene-composition": "./src/scene-composition/index.mjs",
     "./prefabs": "./src/prefabs/index.mjs",
     "./shader-kits": "./src/shader-kits/index.mjs",
@@ -20,6 +23,8 @@
   },
   "files": [
     "src/",
+    "!src/mobile/ios/vendor/",
+    "!src/mobile/ios/vendor/**",
     "benchmarks/perf-thresholds.json",
     "templates/"
   ],

package/src/ai-guidance.mjs

@@ -0,0 +1,302 @@
+const SHARED_HELPER_PACKAGE_SPECIFIER = '@auraindustry/aurajs/helpers';
+const SHARED_HELPER_PACKAGE_SPECIFIER_2D = '@auraindustry/aurajs/helpers/2d';
+
+const MODULE_CATALOG = Object.freeze({
+  'world-compositor-2d': {
+    id: 'world-compositor-2d',
+    title: 'Layered world compositor',
+    starterModulePath: 'src/starter-utils/world-compositor-2d.js',
+    sharedPackageSpecifier: SHARED_HELPER_PACKAGE_SPECIFIER_2D,
+    importNames: ['createWorldCompositor2D', 'ensureWorldCompositorTargets2D', 'runWorldCompositor2D'],
+    useWhen: 'weather, lighting, fog, or any other multi-pass world FX',
+  },
+  'tilemap-nav-2d': {
+    id: 'tilemap-nav-2d',
+    title: 'Tilemap navigation and occupancy',
+    starterModulePath: 'src/starter-utils/tilemap-nav-2d.js',
+    sharedPackageSpecifier: SHARED_HELPER_PACKAGE_SPECIFIER_2D,
+    importNames: ['createTilemapNav2D', 'rebuildTilemapNav2D', 'findTilemapPath2D', 'resolveTilemapStep2D'],
+    useWhen: 'AI movement, lane routing, and mutable occupancy on grid worlds',
+  },
+  'tilemap-world-2d': {
+    id: 'tilemap-world-2d',
+    title: 'Tilemap world loading and queries',
+    starterModulePath: 'src/starter-utils/tilemap-world-2d.js',
+    sharedPackageSpecifier: SHARED_HELPER_PACKAGE_SPECIFIER_2D,
+    importNames: ['createTilemapWorld2D', 'ensureTilemapWorldLoaded2D', 'queryTilemapWorldPoint2D', 'moveActorThroughTilemapWorld2D'],
+    useWhen: '2D worlds driven by tilemap objects, blockers, and spawn points',
+  },
+  'wave-director': {
+    id: 'wave-director',
+    title: 'Wave and pacing director',
+    starterModulePath: 'src/starter-utils/wave-director.js',
+    sharedPackageSpecifier: SHARED_HELPER_PACKAGE_SPECIFIER_2D,
+    importNames: ['createWaveDirector', 'activeWave', 'stepWaveDirector'],
+    useWhen: 'escalating spawn pressure, round structure, or timed encounters',
+  },
+  'enemy-archetypes-2d': {
+    id: 'enemy-archetypes-2d',
+    title: 'Enemy archetype catalog',
+    starterModulePath: 'src/starter-utils/enemy-archetypes-2d.js',
+    sharedPackageSpecifier: SHARED_HELPER_PACKAGE_SPECIFIER_2D,
+    importNames: ['listEnemyArchetypeIds2D', 'getEnemyArchetype2D', 'pickEnemyArchetypeForWave2D', 'spawnEnemy2D'],
+    useWhen: 'authoring reusable enemy definitions instead of scene-local enemy branches',
+  },
+  'combat-runtime-2d': {
+    id: 'combat-runtime-2d',
+    title: 'Combat runtime helpers',
+    starterModulePath: 'src/starter-utils/combat-runtime-2d.js',
+    sharedPackageSpecifier: SHARED_HELPER_PACKAGE_SPECIFIER_2D,
+    importNames: ['applyShieldedDamage2D', 'createEncounterPressure2D', 'recordEncounterKill2D', 'advanceBossPhase2D'],
+    useWhen: 'damage, shield logic, encounter pressure, or boss phase transitions',
+  },
+  'combat-feedback-2d': {
+    id: 'combat-feedback-2d',
+    title: 'Combat feedback and hit FX',
+    starterModulePath: 'src/starter-utils/combat-feedback-2d.js',
+    sharedPackageSpecifier: SHARED_HELPER_PACKAGE_SPECIFIER_2D,
+    importNames: ['createFloatingTextLayer2D', 'spawnFloatingText2D', 'createHitSparkLayer2D', 'spawnHitSpark2D'],
+    useWhen: 'damage popups, sparks, flashes, and other readable combat feedback',
+  },
+  'dialogue-2d': {
+    id: 'dialogue-2d',
+    title: 'Dialogue state helpers',
+    starterModulePath: 'src/starter-utils/dialogue-2d.js',
+    sharedPackageSpecifier: SHARED_HELPER_PACKAGE_SPECIFIER_2D,
+    importNames: ['createDialogueState2D', 'registerDialogueConversation2D', 'startDialogueConversation2D', 'getDialogueView2D'],
+    useWhen: 'branching dialogue, NPC interaction state, or conversation HUDs',
+  },
+  'journal-2d': {
+    id: 'journal-2d',
+    title: 'Journal and objective log',
+    starterModulePath: 'src/starter-utils/journal-2d.js',
+    sharedPackageSpecifier: SHARED_HELPER_PACKAGE_SPECIFIER_2D,
+    importNames: ['createJournal2D', 'upsertJournalEntry2D', 'setJournalEntryStatus2D', 'getJournalView2D'],
+    useWhen: 'quest logs, codex views, or collectible notes',
+  },
+  'inventory-2d': {
+    id: 'inventory-2d',
+    title: 'Inventory helpers',
+    starterModulePath: 'src/starter-utils/inventory-2d.js',
+    sharedPackageSpecifier: SHARED_HELPER_PACKAGE_SPECIFIER_2D,
+    importNames: ['createInventory2D', 'addInventoryItem2D', 'setInventoryItemEquipped2D', 'getInventoryView2D'],
+    useWhen: 'loadouts, pickups, or retained player inventory state',
+  },
+  'adventure-objectives': {
+    id: 'adventure-objectives',
+    title: 'Adventure objective helpers',
+    starterModulePath: 'src/starter-utils/adventure-objectives.js',
+    sharedPackageSpecifier: SHARED_HELPER_PACKAGE_SPECIFIER_2D,
+    importNames: ['createAdventureObjectives', 'objectivesComplete', 'collectAdventureObjectives2D'],
+    useWhen: 'objective tracking, relic hunts, or checkpoint-style adventure progression',
+  },
+});
+
+const FEATURE_CATALOG = Object.freeze({
+  'native-2d-action-world': {
+    id: 'native-2d-action-world',
+    title: '2D world FX and traversal',
+    moduleIds: ['world-compositor-2d', 'tilemap-world-2d', 'tilemap-nav-2d'],
+    recommendedStarters: ['2d-shooter', '2d-survivor'],
+    examples: ['examples/sector-surge-2d/src/main.js'],
+  },
+  'native-2d-action-combat': {
+    id: 'native-2d-action-combat',
+    title: '2D action combat loop',
+    moduleIds: ['wave-director', 'enemy-archetypes-2d', 'combat-runtime-2d', 'combat-feedback-2d'],
+    recommendedStarters: ['2d-shooter', '2d-survivor'],
+    examples: ['examples/sector-surge-2d/src/main.js'],
+  },
+  'native-2d-adventure-systems': {
+    id: 'native-2d-adventure-systems',
+    title: '2D adventure state, dialogue, and journal systems',
+    moduleIds: ['dialogue-2d', 'journal-2d', 'inventory-2d', 'adventure-objectives'],
+    recommendedStarters: ['2d-adventure'],
+    examples: ['src/cli/templates/create/2d/scenes/gameplay.scene.js'],
+  },
+});
+
+const TEMPLATE_LANES = Object.freeze({
+  blank: {
+    laneId: 'bootstrap-authored-project',
+    starterKind: 'blank',
+    summary: 'Use the blank scaffold when you need full control over project shape and are willing to wire gameplay systems yourself.',
+    preferredPackageSpecifier: SHARED_HELPER_PACKAGE_SPECIFIER,
+    recommendedModules: [],
+    featureIds: [],
+    firstExamplePaths: ['src/runtime/project-registry.js'],
+  },
+  '2d-shooter': {
+    laneId: 'native-2d-action',
+    starterKind: 'starter-2d-action',
+    summary: 'This is the strongest starter-owned lane for fast AI-assisted action combat work.',
+    preferredPackageSpecifier: SHARED_HELPER_PACKAGE_SPECIFIER_2D,
+    recommendedModules: ['world-compositor-2d', 'tilemap-world-2d', 'tilemap-nav-2d', 'wave-director', 'enemy-archetypes-2d', 'combat-runtime-2d', 'combat-feedback-2d'],
+    featureIds: ['native-2d-action-world', 'native-2d-action-combat'],
+    firstExamplePaths: ['examples/sector-surge-2d/src/main.js'],
+  },
+  '2d-survivor': {
+    laneId: 'native-2d-action',
+    starterKind: 'starter-2d-action',
+    summary: 'This starter shares the same action-combat helper lane as the shooter template, biased toward swarm survival loops.',
+    preferredPackageSpecifier: SHARED_HELPER_PACKAGE_SPECIFIER_2D,
+    recommendedModules: ['world-compositor-2d', 'tilemap-world-2d', 'tilemap-nav-2d', 'wave-director', 'enemy-archetypes-2d', 'combat-runtime-2d', 'combat-feedback-2d'],
+    featureIds: ['native-2d-action-world', 'native-2d-action-combat'],
+    firstExamplePaths: ['examples/sector-surge-2d/src/main.js'],
+  },
+  '2d-adventure': {
+    laneId: 'native-2d-adventure',
+    starterKind: 'starter-2d-adventure',
+    summary: 'Use this lane for dialogue-heavy worlds, objective flow, inventory, and journal-driven progression.',
+    preferredPackageSpecifier: SHARED_HELPER_PACKAGE_SPECIFIER_2D,
+    recommendedModules: ['tilemap-world-2d', 'dialogue-2d', 'journal-2d', 'inventory-2d', 'adventure-objectives'],
+    featureIds: ['native-2d-adventure-systems'],
+    firstExamplePaths: ['src/cli/templates/create/2d/scenes/gameplay.scene.js'],
+  },
+  '3d-adventure': {
+    laneId: 'native-3d-adventure',
+    starterKind: 'starter-3d-adventure',
+    summary: 'This is the current paved 3D starter lane for lightweight authored scene flow and progression.',
+    preferredPackageSpecifier: SHARED_HELPER_PACKAGE_SPECIFIER,
+    recommendedModules: [],
+    featureIds: [],
+    firstExamplePaths: ['src/cli/templates/create/3d/scenes/gameplay.scene.js'],
+  },
+  '3d-platformer': {
+    laneId: 'native-3d-platformer',
+    starterKind: 'starter-3d-platformer',
+    summary: 'Use this lane when you need checkpoints, movement loops, and 3D traversal scaffolding.',
+    preferredPackageSpecifier: SHARED_HELPER_PACKAGE_SPECIFIER,
+    recommendedModules: [],
+    featureIds: [],
+    firstExamplePaths: ['src/cli/templates/create/3d/scenes/gameplay.scene.js'],
+  },
+  '3d-collectathon': {
+    laneId: 'native-3d-collectathon',
+    starterKind: 'starter-3d-collectathon',
+    summary: 'This starter is the paved road for lightweight 3D collectathon structure and checkpoint flow.',
+    preferredPackageSpecifier: SHARED_HELPER_PACKAGE_SPECIFIER,
+    recommendedModules: [],
+    featureIds: [],
+    firstExamplePaths: ['src/cli/templates/create/3d/scenes/gameplay.scene.js'],
+  },
+  'local-multiplayer': {
+    laneId: 'local-multiplayer',
+    starterKind: 'starter-local-multiplayer',
+    summary: 'This lane is optimized for same-machine room-code multiplayer structure instead of single-player action helpers.',
+    preferredPackageSpecifier: SHARED_HELPER_PACKAGE_SPECIFIER,
+    recommendedModules: [],
+    featureIds: [],
+    firstExamplePaths: ['src/cli/templates/create/local-multiplayer/scenes/gameplay.scene.js'],
+  },
+  'deckbuilder-2d': {
+    laneId: 'deckbuilder-2d',
+    starterKind: 'starter-deckbuilder-2d',
+    summary: 'This lane is the paved road for content-registry-driven 2D deckbuilder projects.',
+    preferredPackageSpecifier: SHARED_HELPER_PACKAGE_SPECIFIER_2D,
+    recommendedModules: [],
+    featureIds: [],
+    firstExamplePaths: ['src/cli/templates/create/deckbuilder-2d/scenes/gameplay.scene.js'],
+  },
+});
+
+export function describeProjectAiGuidance({ template, starterUtils }) {
+  const normalizedTemplate = String(template || '').trim() || 'blank';
+  const lane = TEMPLATE_LANES[normalizedTemplate] || TEMPLATE_LANES.blank;
+  const recommendedImportPath = starterUtils?.available === true
+    && typeof starterUtils?.recommendedImportPath === 'string'
+    && starterUtils.recommendedImportPath.trim().length > 0
+    ? starterUtils.recommendedImportPath.trim()
+    : null;
+
+  const recommendedModules = lane.recommendedModules
+    .map((moduleId) => MODULE_CATALOG[moduleId])
+    .filter(Boolean)
+    .map((entry) => ({
+      ...entry,
+      preferredImportSource: recommendedImportPath || entry.sharedPackageSpecifier || lane.preferredPackageSpecifier || null,
+      sourceMode: recommendedImportPath ? 'starter-utils' : 'package',
+    }));
+
+  const featureMap = lane.featureIds
+    .map((featureId) => FEATURE_CATALOG[featureId])
+    .filter(Boolean)
+    .map((feature) => ({
+      id: feature.id,
+      title: feature.title,
+      recommendedStarters: [...feature.recommendedStarters],
+      examples: [...feature.examples],
+      modules: feature.moduleIds
+        .map((moduleId) => MODULE_CATALOG[moduleId])
+        .filter(Boolean)
+        .map((entry) => ({
+          id: entry.id,
+          title: entry.title,
+          starterModulePath: entry.starterModulePath,
+          importNames: [...entry.importNames],
+        })),
+    }));
+
+  return {
+    laneId: lane.laneId,
+    starterKind: lane.starterKind,
+    summary: lane.summary,
+    recommendedImportPath,
+    preferredPackageSpecifier: lane.preferredPackageSpecifier || null,
+    recommendedModules,
+    featureMap,
+    firstExamplePaths: [...lane.firstExamplePaths],
+  };
+}
+
+export function normalizeAiGuidance(value) {
+  const safe = value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+  return {
+    laneId: typeof safe.laneId === 'string' && safe.laneId.trim().length > 0
+      ? safe.laneId.trim()
+      : 'bootstrap-authored-project',
+    starterKind: typeof safe.starterKind === 'string' && safe.starterKind.trim().length > 0
+      ? safe.starterKind.trim()
+      : 'blank',
+    summary: typeof safe.summary === 'string' && safe.summary.trim().length > 0
+      ? safe.summary.trim()
+      : '',
+    recommendedImportPath: typeof safe.recommendedImportPath === 'string' && safe.recommendedImportPath.trim().length > 0
+      ? safe.recommendedImportPath.trim()
+      : null,
+    preferredPackageSpecifier: typeof safe.preferredPackageSpecifier === 'string' && safe.preferredPackageSpecifier.trim().length > 0
+      ? safe.preferredPackageSpecifier.trim()
+      : null,
+    recommendedModules: Array.isArray(safe.recommendedModules)
+      ? safe.recommendedModules.map((entry) => ({
+        id: String(entry?.id || '').trim(),
+        title: typeof entry?.title === 'string' ? entry.title.trim() : '',
+        starterModulePath: typeof entry?.starterModulePath === 'string' ? entry.starterModulePath.trim() : null,
+        sharedPackageSpecifier: typeof entry?.sharedPackageSpecifier === 'string' ? entry.sharedPackageSpecifier.trim() : null,
+        preferredImportSource: typeof entry?.preferredImportSource === 'string' ? entry.preferredImportSource.trim() : null,
+        sourceMode: entry?.sourceMode === 'starter-utils' ? 'starter-utils' : 'package',
+        importNames: Array.isArray(entry?.importNames) ? entry.importNames.map((name) => String(name)) : [],
+        useWhen: typeof entry?.useWhen === 'string' ? entry.useWhen.trim() : '',
+      })).filter((entry) => entry.id.length > 0)
+      : [],
+    featureMap: Array.isArray(safe.featureMap)
+      ? safe.featureMap.map((entry) => ({
+        id: String(entry?.id || '').trim(),
+        title: typeof entry?.title === 'string' ? entry.title.trim() : '',
+        recommendedStarters: Array.isArray(entry?.recommendedStarters) ? entry.recommendedStarters.map((item) => String(item)) : [],
+        examples: Array.isArray(entry?.examples) ? entry.examples.map((item) => String(item)) : [],
+        modules: Array.isArray(entry?.modules)
+          ? entry.modules.map((moduleEntry) => ({
+            id: String(moduleEntry?.id || '').trim(),
+            title: typeof moduleEntry?.title === 'string' ? moduleEntry.title.trim() : '',
+            starterModulePath: typeof moduleEntry?.starterModulePath === 'string' ? moduleEntry.starterModulePath.trim() : null,
+            importNames: Array.isArray(moduleEntry?.importNames) ? moduleEntry.importNames.map((name) => String(name)) : [],
+          })).filter((moduleEntry) => moduleEntry.id.length > 0)
+          : [],
+      })).filter((entry) => entry.id.length > 0)
+      : [],
+    firstExamplePaths: Array.isArray(safe.firstExamplePaths)
+      ? safe.firstExamplePaths.map((entry) => String(entry)).filter(Boolean)
+      : [],
+  };
+}