@auraindustry/aurajs 0.1.3 → 0.1.5

package/templates/skills/auramaxx/starter-recipes.md

@@ -0,0 +1,104 @@
+# AuraMaxx Starter Recipes
+
+Use the current template id from `aura.capabilities.json` or `aura.config.json`
+to pick the right recipe.
+
+## 2d-adventure
+
+- Edit first:
+  - `content/gameplay/world.js`
+  - `config/gameplay/adventure.config.js`
+  - `scenes/gameplay.scene.js`
+  - `prefabs/world.prefab.js`
+  - `prefabs/relic.prefab.js`
+  - `ui/hud.screen.js`
+- Good first tasks:
+  - tighten movement and interaction feel
+  - rewrite room nouns, relic goals, dialogue, and route beats
+  - add one strong interaction before widening scope
+- Avoid:
+  - burying route data inside the scene
+  - replacing starter-utils with duplicated local helpers
+
+## 2d-shooter and 2d-survivor
+
+- Edit first:
+  - `config/gameplay/*.config.js`
+  - `scenes/gameplay.scene.js`
+  - `prefabs/player.prefab.js`
+  - enemy or projectile prefabs
+  - `ui/*.screen.js`
+- Good first tasks:
+  - pacing, spawn pressure, weapon feel, hit feedback, restart loop
+- Avoid:
+  - mixing balance constants into render code
+  - adding many enemy types before one wave feels good
+
+## deckbuilder-2d
+
+- Edit first:
+  - starter-owned `content/registries/*`
+  - `config/gameplay/*`
+  - combat scene files
+  - HUD and card presentation screens
+- Good first tasks:
+  - one coherent card set
+  - one enemy intent loop
+  - one relic or progression rule
+- Avoid:
+  - putting card data directly in scene logic
+
+## 3d-adventure, 3d-platformer, 3d-collectathon
+
+- Edit first:
+  - `content/gameplay/course.js`
+  - `config/gameplay/*.config.js`
+  - `scenes/gameplay.scene.js`
+  - `prefabs/world.prefab.js`
+  - `prefabs/player.prefab.js`
+  - `src/starter-utils/avatar-3d.js`
+  - `src/starter-utils/platformer-3d.js`
+- Good first tasks:
+  - movement feel, camera follow, checkpoints, collectibles, route readability
+- Avoid:
+  - hardcoding course layout in the scene
+  - treating imported models as the only source of gameplay truth
+
+## local-multiplayer
+
+- Edit first:
+  - `config/gameplay/local-multiplayer.config.js`
+  - `content/gameplay/room-layout.js`
+  - `scenes/gameplay.scene.js`
+  - `ui/hud.screen.js`
+- Good first tasks:
+  - one host/join room loop
+  - one shared objective
+  - one clear disconnect or retry path
+- Avoid:
+  - breaking the local-first host flow while chasing internet features
+  - assuming headless state or action flows work unless you verify them
+
+## blank
+
+- Edit first:
+  - `src/main.js`
+  - `scenes/gameplay.scene.js`
+  - `prefabs/player.prefab.js`
+  - `ui/hud.screen.js`
+  - `config/gameplay/game.config.json`
+- Good first tasks:
+  - one visible mechanic
+  - one HUD element
+  - one authored config value
+- Avoid:
+  - recreating the whole scaffold model from scratch
+
+## Cross-starter recipe
+
+For any starter:
+
+1. make one mechanic feel good
+2. make the goal readable in HUD or world feedback
+3. move stable data into `config/` or `content/`
+4. only then add more systems

package/templates/skills/auramaxx/validation-checklist.md

@@ -0,0 +1,49 @@
+# AuraMaxx Validation Checklist
+
+Pick the smallest set that matches the task.
+
+## Always
+
+- Run `auramaxx explain` after structure changes.
+- Run `auramaxx check` before and after edits.
+- If you add new scaffold nouns, run `auramaxx make list --json` first and use
+  `auramaxx make ...` where possible.
+
+## Gameplay slice
+
+- Run `npm run dev`.
+- Confirm:
+  - the game boots
+  - the first objective is readable
+  - controls match the intended loop
+  - HUD or world feedback reflects the new mechanic
+  - there are no obvious stuck states or soft-locks
+
+## State and action tooling
+
+- Run `npm run state -- export --compact` when the project claims state export.
+- Run `npm run action -- schema --compact` when the project claims action
+  tooling.
+- If these fail, record the exact reason instead of pretending the flow works.
+
+## Session and headless flows
+
+- Use `auramaxx session start --headless --name ci-loop --compact` only after
+  verifying the starter and runtime actually support that lane.
+- If the project is multiplayer or starter-heavy, verify headless flows
+  explicitly instead of assuming parity with visible `npm run dev`.
+
+## Publish and package surface
+
+- Run `auramaxx publish --dry-run` for package-surface and build validation.
+- Run `auramaxx external-assets generate --public-base-url <url>` only after the
+  build artifacts exist and the project actually needs self-hosted assets.
+
+## What to report
+
+When you finish, report:
+
+- which commands passed
+- which commands failed
+- whether failures are task regressions or pre-existing runtime gaps
+- what the player-visible outcome is

package/templates/skills/aurajs/SKILL.md

@@ -1,96 +0,0 @@
-# AuraJS Skill
-
-Use this skill when building or modifying AuraJS games.
-
-## Read First
-- `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. 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`.
-2. Run `npm run dev` for fast iteration.
-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)`.
-- Put rendering in `aura.draw`.
-- Keep rendering API calls in draw-only paths.
-- Use `aura.window.getSize()` for runtime layout.
-- Clamp player/world values to avoid drift.
-
-## Vibe Coding Defaults
-- Start with one loop and one strong interaction.
-- Add juice after core feel works: camera, hit feedback, audio, score.
-- Keep systems loosely coupled so AI agents can modify one mechanic at a time.
-
-## 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.

package/templates/skills/aurajs/api-contract-3d.md

@@ -1,7 +0,0 @@
-# AuraJS API Contract (3D)
-
-Canonical source:
-- `../../docs/api-contract-3d.md`
-
-Published snapshots copy that canonical contract into this file path.
-For agent work, use targeted section reads on the exact APIs you touch.

package/templates/skills/aurajs/api-contract.md

@@ -1,7 +0,0 @@
-# AuraJS API Contract (Core)
-
-Canonical source:
-- `../../docs/api-contract.md`
-
-Published snapshots copy that canonical contract into this file path.
-For agent work, use targeted section reads on the exact APIs you touch.