@auraindustry/aurajs 0.0.6 → 0.1.0

package/templates/retro/platformer/src/main.js

@@ -0,0 +1,40 @@
+export const state = {
+  player: {
+    x: 24,
+    y: 32,
+    vy: 0,
+    onGround: true,
+  },
+  distance: 0,
+};
+
+export function setup() {}
+
+export function update(aura) {
+  if (aura.input.pressed('left')) state.player.x -= 1;
+  if (aura.input.pressed('right')) state.player.x += 1;
+  if (aura.input.justPressed('a') && state.player.onGround) {
+    state.player.vy = -3;
+    state.player.onGround = false;
+  }
+  if (!state.player.onGround) {
+    state.player.y += state.player.vy;
+    state.player.vy += 1;
+    if (state.player.y >= 32) {
+      state.player.y = 32;
+      state.player.vy = 0;
+      state.player.onGround = true;
+    }
+  }
+  if (aura.input.pressed('left') || aura.input.pressed('right')) state.distance += 1;
+}
+
+export function draw(aura) {
+  aura.tilemap.setTile('platforms', 0, 0, 'ground');
+  aura.tilemap.setTile('platforms', 1, 0, 'ground');
+  aura.tilemap.setTile('platforms', 2, 0, 'ground');
+  aura.tilemap.setTile('platforms', 3, 0, 'ground');
+  aura.sprite.draw('hero', state.player.x, state.player.y, { palette: 'dmg' });
+  aura.text.write(state.player.onGround ? 'GROUND' : 'AIR', 0, 0);
+  aura.text.write(`${state.distance}`, 0, 8);
+}

package/templates/retro/puzzle-grid/README.md

@@ -0,0 +1,10 @@
+# __AURA_RETRO_PROJECT_NAME__
+
+Target-safe Aura Retro starter for a one-screen grid puzzle.
+
+Commands:
+
+```bash
+aura retro explain --target gbc
+aura build --target gbc
+```

package/templates/retro/puzzle-grid/assets/retro/assets.json

@@ -0,0 +1,90 @@
+{
+  "palettes": [
+    {
+      "id": "dmg",
+      "colors": ["#081820", "#346856", "#88C070", "#E0F8D0"]
+    }
+  ],
+  "tiles": [
+    {
+      "id": "ground",
+      "palette": "dmg",
+      "width": 8,
+      "height": 8,
+      "pixels": [
+        "00011000",
+        "00122100",
+        "01233210",
+        "12333321",
+        "12333321",
+        "01233210",
+        "00122100",
+        "00011000"
+      ]
+    },
+    {
+      "id": "wall",
+      "palette": "dmg",
+      "width": 8,
+      "height": 8,
+      "pixels": [
+        "33333333",
+        "32222223",
+        "32111123",
+        "32133123",
+        "32133123",
+        "32111123",
+        "32222223",
+        "33333333"
+      ]
+    }
+  ],
+  "sprites": [
+    {
+      "id": "hero",
+      "palette": "dmg",
+      "width": 8,
+      "height": 8,
+      "pixels": [
+        "..1111..",
+        ".122221.",
+        "12333321",
+        "12300321",
+        "12333321",
+        ".122221.",
+        ".1.11.1.",
+        "1..11..1"
+      ]
+    },
+    {
+      "id": "marker",
+      "palette": "dmg",
+      "width": 8,
+      "height": 8,
+      "pixels": [
+        "........",
+        "...11...",
+        "..1221..",
+        ".123321.",
+        ".123321.",
+        "..1221..",
+        "...11...",
+        "........"
+      ]
+    }
+  ],
+  "fonts": [
+    {
+      "id": "hud",
+      "width": 4,
+      "height": 6,
+      "glyphs": {
+        "M": ["1..1", "1111", "1111", "1..1", "1..1", "1..1"],
+        "O": [".11.", "1..1", "1..1", "1..1", "1..1", ".11."],
+        "V": ["1..1", "1..1", "1..1", "1..1", ".11.", ".11."],
+        "E": ["1111", "1...", "111.", "1...", "1...", "1111"],
+        "S": [".111", "1...", ".11.", "...1", "...1", "111."]
+      }
+    }
+  ]
+}

package/templates/retro/puzzle-grid/aura.config.json

@@ -0,0 +1,7 @@
+{
+  "identity": {
+    "name": "__AURA_RETRO_PROJECT_NAME__",
+    "version": "0.1.0",
+    "executable": "__AURA_RETRO_PROJECT_SLUG__"
+  }
+}

package/templates/retro/puzzle-grid/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "__AURA_RETRO_PROJECT_SLUG__",
+  "version": "0.1.0",
+  "private": true
+}

package/templates/retro/puzzle-grid/src/main.js

@@ -0,0 +1,29 @@
+export const state = {
+  cursor: {
+    x: 1,
+    y: 1,
+  },
+  moves: 0,
+  solved: false,
+};
+
+export function setup() {}
+
+export function update(aura) {
+  if (aura.input.pressed('left')) state.cursor.x -= 1;
+  if (aura.input.pressed('right')) state.cursor.x += 1;
+  if (aura.input.pressed('up')) state.cursor.y -= 1;
+  if (aura.input.pressed('down')) state.cursor.y += 1;
+  if (aura.input.justPressed('a')) state.solved = !state.solved;
+  state.moves += 1;
+}
+
+export function draw(aura) {
+  aura.tilemap.setTile('board', 0, 0, 'wall');
+  aura.tilemap.setTile('board', 1, 0, 'ground');
+  aura.tilemap.setTile('board', 2, 0, 'wall');
+  aura.tilemap.setTile('board', 1, 1, state.solved ? 'wall' : 'ground');
+  aura.sprite.draw('marker', state.cursor.x * 8, state.cursor.y * 8, { palette: 'dmg' });
+  aura.text.write(state.solved ? 'SOLVED' : 'MOVES', 0, 0);
+  aura.text.write(`${state.moves}`, 0, 8);
+}

package/templates/retro/tactics-grid/README.md

@@ -0,0 +1,10 @@
+# __AURA_RETRO_PROJECT_NAME__
+
+Target-safe Aura Retro starter for a small turn-based tactics grid.
+
+Commands:
+
+```bash
+aura retro explain --target gbc
+aura build --target gbc
+```

package/templates/retro/tactics-grid/assets/retro/assets.json

@@ -0,0 +1,90 @@
+{
+  "palettes": [
+    {
+      "id": "dmg",
+      "colors": ["#081820", "#346856", "#88C070", "#E0F8D0"]
+    }
+  ],
+  "tiles": [
+    {
+      "id": "ground",
+      "palette": "dmg",
+      "width": 8,
+      "height": 8,
+      "pixels": [
+        "00011000",
+        "00122100",
+        "01233210",
+        "12333321",
+        "12333321",
+        "01233210",
+        "00122100",
+        "00011000"
+      ]
+    },
+    {
+      "id": "wall",
+      "palette": "dmg",
+      "width": 8,
+      "height": 8,
+      "pixels": [
+        "33333333",
+        "32222223",
+        "32111123",
+        "32133123",
+        "32133123",
+        "32111123",
+        "32222223",
+        "33333333"
+      ]
+    }
+  ],
+  "sprites": [
+    {
+      "id": "hero",
+      "palette": "dmg",
+      "width": 8,
+      "height": 8,
+      "pixels": [
+        "..1111..",
+        ".122221.",
+        "12333321",
+        "12300321",
+        "12333321",
+        ".122221.",
+        ".1.11.1.",
+        "1..11..1"
+      ]
+    },
+    {
+      "id": "marker",
+      "palette": "dmg",
+      "width": 8,
+      "height": 8,
+      "pixels": [
+        "........",
+        "...11...",
+        "..1221..",
+        ".123321.",
+        ".123321.",
+        "..1221..",
+        "...11...",
+        "........"
+      ]
+    }
+  ],
+  "fonts": [
+    {
+      "id": "hud",
+      "width": 4,
+      "height": 6,
+      "glyphs": {
+        "A": [".11.", "1..1", "1111", "1..1", "1..1", "1..1"],
+        "L": ["1...", "1...", "1...", "1...", "1...", "1111"],
+        "P": ["111.", "1..1", "111.", "1...", "1...", "1..."],
+        "T": ["1111", ".11.", ".11.", ".11.", ".11.", ".11."],
+        "U": ["1..1", "1..1", "1..1", "1..1", "1..1", ".11."]
+      }
+    }
+  ]
+}

package/templates/retro/tactics-grid/aura.config.json

@@ -0,0 +1,7 @@
+{
+  "identity": {
+    "name": "__AURA_RETRO_PROJECT_NAME__",
+    "version": "0.1.0",
+    "executable": "__AURA_RETRO_PROJECT_SLUG__"
+  }
+}

package/templates/retro/tactics-grid/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "__AURA_RETRO_PROJECT_SLUG__",
+  "version": "0.1.0",
+  "private": true
+}

package/templates/retro/tactics-grid/src/main.js

@@ -0,0 +1,35 @@
+export const state = {
+  selector: {
+    x: 2,
+    y: 1,
+  },
+  actionPoints: 2,
+  turn: 'ALLY',
+};
+
+export function setup(aura) {
+  aura.audio.playMusic('tactics-theme');
+}
+
+export function update(aura) {
+  if (aura.input.pressed('left')) state.selector.x -= 1;
+  if (aura.input.pressed('right')) state.selector.x += 1;
+  if (aura.input.pressed('up')) state.selector.y -= 1;
+  if (aura.input.pressed('down')) state.selector.y += 1;
+  if (aura.input.justPressed('a') && state.actionPoints > 0) state.actionPoints -= 1;
+  if (aura.input.justPressed('b')) {
+    state.turn = state.turn === 'ALLY' ? 'FOE' : 'ALLY';
+    state.actionPoints = 2;
+  }
+}
+
+export function draw(aura) {
+  aura.tilemap.setTile('field', 0, 0, 'ground');
+  aura.tilemap.setTile('field', 1, 0, 'wall');
+  aura.tilemap.setTile('field', 2, 0, 'ground');
+  aura.tilemap.setTile('field', 3, 0, 'wall');
+  aura.sprite.draw('hero', 8, 16, { palette: 'dmg' });
+  aura.sprite.draw('marker', state.selector.x * 8, state.selector.y * 8, { palette: 'dmg' });
+  aura.text.write(state.turn, 0, 0);
+  aura.text.write(`AP ${state.actionPoints}`, 0, 8);
+}

package/templates/retro/topdown-adventure/README.md

@@ -0,0 +1,10 @@
+# __AURA_RETRO_PROJECT_NAME__
+
+Target-safe Aura Retro starter for a small top-down exploration loop.
+
+Commands:
+
+```bash
+aura retro explain --target gbc
+aura build --target gbc
+```

package/templates/retro/topdown-adventure/assets/retro/assets.json

@@ -0,0 +1,95 @@
+{
+  "palettes": [
+    {
+      "id": "dmg",
+      "colors": ["#081820", "#346856", "#88C070", "#E0F8D0"]
+    }
+  ],
+  "tiles": [
+    {
+      "id": "ground",
+      "palette": "dmg",
+      "width": 8,
+      "height": 8,
+      "pixels": [
+        "00011000",
+        "00122100",
+        "01233210",
+        "12333321",
+        "12333321",
+        "01233210",
+        "00122100",
+        "00011000"
+      ]
+    },
+    {
+      "id": "wall",
+      "palette": "dmg",
+      "width": 8,
+      "height": 8,
+      "pixels": [
+        "33333333",
+        "32222223",
+        "32111123",
+        "32133123",
+        "32133123",
+        "32111123",
+        "32222223",
+        "33333333"
+      ]
+    }
+  ],
+  "sprites": [
+    {
+      "id": "hero",
+      "palette": "dmg",
+      "width": 8,
+      "height": 8,
+      "pixels": [
+        "..1111..",
+        ".122221.",
+        "12333321",
+        "12300321",
+        "12333321",
+        ".122221.",
+        ".1.11.1.",
+        "1..11..1"
+      ]
+    },
+    {
+      "id": "marker",
+      "palette": "dmg",
+      "width": 8,
+      "height": 8,
+      "pixels": [
+        "........",
+        "...11...",
+        "..1221..",
+        ".123321.",
+        ".123321.",
+        "..1221..",
+        "...11...",
+        "........"
+      ]
+    }
+  ],
+  "fonts": [
+    {
+      "id": "hud",
+      "width": 4,
+      "height": 6,
+      "glyphs": {
+        "A": [".11.", "1..1", "1111", "1..1", "1..1", "1..1"],
+        "E": ["1111", "1...", "111.", "1...", "1...", "1111"],
+        "G": [".111", "1...", "1.11", "1..1", "1..1", ".111"],
+        "H": ["1..1", "1..1", "1111", "1..1", "1..1", "1..1"],
+        "M": ["1..1", "1111", "1111", "1..1", "1..1", "1..1"],
+        "O": [".11.", "1..1", "1..1", "1..1", "1..1", ".11."],
+        "P": ["111.", "1..1", "111.", "1...", "1...", "1..."],
+        "R": ["111.", "1..1", "111.", "1.1.", "1..1", "1..1"],
+        "S": [".111", "1...", ".11.", "...1", "...1", "111."],
+        "T": ["1111", ".11.", ".11.", ".11.", ".11.", ".11."]
+      }
+    }
+  ]
+}

package/templates/retro/topdown-adventure/aura.config.json

@@ -0,0 +1,7 @@
+{
+  "identity": {
+    "name": "__AURA_RETRO_PROJECT_NAME__",
+    "version": "0.1.0",
+    "executable": "__AURA_RETRO_PROJECT_SLUG__"
+  }
+}

package/templates/retro/topdown-adventure/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "__AURA_RETRO_PROJECT_SLUG__",
+  "version": "0.1.0",
+  "private": true
+}

package/templates/retro/topdown-adventure/src/main.js

@@ -0,0 +1,29 @@
+export const state = {
+  player: {
+    x: 16,
+    y: 24,
+  },
+  steps: 0,
+};
+
+export function setup(aura) {
+  aura.save.write('room', 'meadow');
+}
+
+export function update(aura) {
+  if (aura.input.pressed('left')) state.player.x -= 1;
+  if (aura.input.pressed('right')) state.player.x += 1;
+  if (aura.input.pressed('up')) state.player.y -= 1;
+  if (aura.input.pressed('down')) state.player.y += 1;
+  state.steps += 1;
+}
+
+export function draw(aura) {
+  aura.tilemap.setTile('ground', 0, 0, 'ground');
+  aura.tilemap.setTile('ground', 1, 0, 'ground');
+  aura.tilemap.setTile('ground', 2, 0, 'ground');
+  aura.tilemap.setTile('ground', 0, 1, 'wall');
+  aura.sprite.draw('hero', state.player.x, state.player.y, { palette: 'dmg' });
+  aura.text.write('MEADOW', 0, 0);
+  aura.text.write(`STEPS ${state.steps}`, 0, 8);
+}

package/templates/skills/aurajs/SKILL.md

@@ -3,17 +3,42 @@
 Use this skill when building or modifying AuraJS games.
 
 ## Read First
-- `api-contract.md` (2D/core surface)
-- `api-contract-3d.md` (3D surface)
+- `docs/external/game-dev-api/start-here.md`
+- `docs/external/game-dev-api/creating-a-new-game.md`
+- `docs/external/game-dev-api/working-with-an-aurajs-project.md`
+- `docs/external/game-dev-api/examples-and-first-game-recipes.md`
+- `docs/external/game-dev-api/common-failures-and-fixes.md`
+
+Then choose the smallest exact-reference page that matches the task:
+
+- `docs/reference/runtime-and-2d-exact-reference.md`
+- `docs/reference/lifecycle-window-input-and-2d-camera-exact-reference.md`
+- `docs/reference/draw2d-assets-audio-storage-and-math-exact-reference.md`
+- `docs/reference/gameplay-systems-exact-reference.md`
+- `docs/reference/animation-scenes-state-tilemaps-and-ecs-exact-reference.md`
+- `docs/reference/3d-rendering-and-content-exact-reference.md`
+- `docs/reference/draw3d-camera-lighting-and-postfx-exact-reference.md`
+- `docs/reference/scene3d-mesh-material-gltf-and-avatar-exact-reference.md`
+- `docs/reference/world-simulation-and-multiplayer-exact-reference.md`
+- `docs/reference/physics3d-terrain-navmesh-character3d-and-compute-exact-reference.md`
+- `docs/reference/net-multiplayer-and-runtime-sessions-exact-reference.md`
+- `docs/reference/tooling-web-and-distribution-exact-reference.md`
+- `docs/reference/project-cli-publish-assets-and-web-exact-reference.md`
+
+Only after that should you open:
+
+- `api-contract.md` (canonical core surface)
+- `api-contract-3d.md` (canonical 3D surface)
 
 Do not load these files end-to-end by default.
 Use targeted reads: jump to the exact namespace/method you are touching, then apply that contract strictly.
 
 ## Contract Workflow
 1. Identify the APIs your change touches.
-2. Search the relevant contract file for those APIs.
-3. Read only those sections and follow signature + validation + error semantics.
-4. If examples conflict with contract docs, contract docs win.
+2. Start with the public start/project docs if the task is about scaffolding, layout, workflow, examples, troubleshooting, or publishing.
+3. Search the smallest exact-reference page that matches the subsystem.
+4. Read only the needed sections of the canonical contract and follow signature + validation + error semantics.
+5. If examples or older convenience docs conflict with contract docs, contract docs win.
 
 ## Build Loop
 1. Implement the smallest playable mechanic in `src/main.js`.
@@ -21,6 +46,31 @@ Use targeted reads: jump to the exact namespace/method you are touching, then ap
 3. Validate release behavior with `npm run play`.
 4. Publish with `npm run publish` when the package is ready.
 
+## Project Shape
+- `src/main.js`: thin project entry.
+- `src/runtime/project-registry.js`: source of truth for scenes, screens, prefabs, and config/content files.
+- `src/runtime/app-state.js`: shared mutable app/session state.
+- `src/runtime/scene-registry.js`: runtime adapter generated from the project registry.
+- `src/runtime/app.js`: lifecycle owner.
+- `src/runtime/scene-flow.js`, `screen-shell.js`, `project-inspector.js`: shared runtime helpers.
+- `scenes/*.scene.js`: authored scenes.
+- `ui/*.screen.js`: authored HUD, overlay, and modal screens.
+- `prefabs/*.prefab.js`: canonical prefab descriptors.
+- `config/**`: gameplay defaults and tunables.
+- `content/**`: authored game definitions and starter-owned registries.
+- `assets/**`: game assets.
+
+## Template Sources
+- Starters come from `src/cli/templates/create/<template>/` inside the AuraJS CLI package.
+- Shared runtime helpers come from `src/cli/templates/create/shared/src/runtime/`.
+- Shared starter utilities come from `src/cli/templates/create/shared/src/starter-utils/`.
+- Generated files come from `aura make`, which uses the packaged make templates and self-wires `scene`, `ui-screen`, and `prefab` entries into the project registry.
+
+## Make Surface
+- Core make kinds: `scene`, `ui-screen`, `prefab`, `data`, `system`, `component`, `material`, `shader`.
+- Some starters also add extra nouns through starter catalogs. The deckbuilder starter adds `card`, `enemy`, `relic`, and `encounter`.
+- Prefer `auramaxx make list --json` or `npx aura make list --json` inside the current project instead of assuming starter-specific nouns from generic help output.
+
 ## Engine Guardrails
 - Put initialization in `aura.setup`.
 - Put frame-step logic in `aura.update(dt)`.
@@ -36,5 +86,11 @@ Use targeted reads: jump to the exact namespace/method you are touching, then ap
 
 ## Suggested Project Structure
 - `src/main.js`: primary loop and gameplay systems.
+- `src/runtime/`: runtime shell and project manifest files.
+- `scenes/`: scene modules.
+- `ui/`: screen modules.
+- `prefabs/`: prefab descriptors.
+- `config/`: gameplay defaults and tunables.
+- `content/`: authored game definitions and registries.
 - `assets/`: sprites, audio, fonts.
 - `skills/`: agent workflows and contract references.