@auraindustry/aurajs 0.0.2 → 0.0.3

package/templates/create/shared/src/starter-utils/wave-director.js

@@ -0,0 +1,101 @@
+import { createIntervalSpawner, tickIntervalSpawner } from './core.js';
+
+export function createWaveDirector(options = {}) {
+  const waves = Array.isArray(options.waves) ? options.waves : [];
+  const loop = options.loop === true;
+  const initialDelay = Math.max(0, Number(options.initialDelay) || 0);
+  const betweenWaveDelay = Math.max(0, Number(options.betweenWaveDelay) || 0);
+
+  return {
+    waves,
+    loop,
+    initialDelay,
+    betweenWaveDelay,
+    delayRemaining: initialDelay,
+    waveIndex: 0,
+    waveElapsed: 0,
+    waveSpawned: 0,
+    activeSpawner: null,
+    completed: waves.length === 0,
+  };
+}
+
+export function activeWave(director) {
+  if (!director || director.completed) return null;
+  return director.waves[director.waveIndex] || null;
+}
+
+export function stepWaveDirector(director, dt, onSpawn = null) {
+  if (!director || director.completed) {
+    return { spawned: 0, waveIndex: -1, completed: true };
+  }
+
+  const frameDt = Math.max(0, Number(dt) || 0);
+  if (director.delayRemaining > 0) {
+    director.delayRemaining = Math.max(0, director.delayRemaining - frameDt);
+    return { spawned: 0, waveIndex: director.waveIndex, completed: director.completed };
+  }
+
+  const wave = activeWave(director);
+  if (!wave) {
+    director.completed = true;
+    return { spawned: 0, waveIndex: -1, completed: true };
+  }
+
+  if (!director.activeSpawner) {
+    const interval = Math.max(0.04, Number(wave.spawnEvery) || 0.8);
+    director.activeSpawner = createIntervalSpawner(interval, { startReady: true });
+    director.waveElapsed = 0;
+    director.waveSpawned = 0;
+  }
+
+  director.waveElapsed += frameDt;
+
+  const maxSpawns = Number.isFinite(Number(wave.maxSpawns))
+    ? Math.max(0, Math.floor(Number(wave.maxSpawns)))
+    : Number.POSITIVE_INFINITY;
+  const maxDuration = Number.isFinite(Number(wave.durationSeconds))
+    ? Math.max(0, Number(wave.durationSeconds))
+    : Number.POSITIVE_INFINITY;
+
+  let spawned = 0;
+  tickIntervalSpawner(director.activeSpawner, frameDt, () => {
+    if (director.waveSpawned >= maxSpawns) return;
+    director.waveSpawned += 1;
+    spawned += 1;
+    if (typeof onSpawn === 'function') {
+      onSpawn({
+        waveIndex: director.waveIndex,
+        wave,
+        spawnedInWave: director.waveSpawned,
+      });
+    }
+  });
+
+  const waveDone = (
+    director.waveSpawned >= maxSpawns
+    || director.waveElapsed >= maxDuration
+  );
+
+  if (waveDone) {
+    director.waveIndex += 1;
+    if (director.waveIndex >= director.waves.length) {
+      if (director.loop) {
+        director.waveIndex = 0;
+      } else {
+        director.completed = true;
+      }
+    }
+
+    director.delayRemaining = director.completed ? 0 : director.betweenWaveDelay;
+    director.waveElapsed = 0;
+    director.waveSpawned = 0;
+    director.activeSpawner = null;
+  }
+
+  return {
+    spawned,
+    waveIndex: director.completed ? -1 : director.waveIndex,
+    completed: director.completed,
+  };
+}

package/templates/skills/aurajs/SKILL.md

@@ -0,0 +1,40 @@
+# AuraJS Skill
+
+Use this skill when building or modifying AuraJS games.
+
+## Read First
+- `api-contract.md` (2D/core surface)
+- `api-contract-3d.md` (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.
+
+## 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.
+
+## 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.
+- `assets/`: sprites, audio, fonts.
+- `skills/`: agent workflows and contract references.

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

@@ -0,0 +1,7 @@
+# AuraJS API Contract (3D)
+
+Canonical source:
+- `../../docs/api-contract-3d-v2.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

@@ -0,0 +1,7 @@
+# AuraJS API Contract (Core)
+
+Canonical source:
+- `../../docs/api-contract-v1.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/starter/src/main.js

@@ -12,6 +12,53 @@ let movedOutsideBounds = false;
 const PLAYER_SPRITE_PATH = "player.png";
 const HUD_FONT_PATH = "fonts/ui.ttf";
 
+function hasMethod(obj, method) {
+  return Boolean(obj) && typeof obj[method] === "function";
+}
+
+function failWithReason(reasonCode, message) {
+  throw new Error(`[starter-template] ${message} [reason:${reasonCode}]`);
+}
+
+function assertRuntimeCapabilities() {
+  const missing = [];
+  if (!hasMethod(aura.input, "isKeyDown")) missing.push("aura.input.isKeyDown");
+  if (!hasMethod(aura.input, "isKeyPressed")) missing.push("aura.input.isKeyPressed");
+  if (!hasMethod(aura.input, "isKeyReleased")) missing.push("aura.input.isKeyReleased");
+  if (!hasMethod(aura.input, "isGamepadConnected")) missing.push("aura.input.isGamepadConnected");
+  if (!hasMethod(aura.window, "getSize")) missing.push("aura.window.getSize");
+  if (!hasMethod(aura.window, "getFPS")) missing.push("aura.window.getFPS");
+  if (!hasMethod(aura.draw2d, "clear")) missing.push("aura.draw2d.clear");
+  if (!hasMethod(aura.draw2d, "sprite")) missing.push("aura.draw2d.sprite");
+  if (!hasMethod(aura.draw2d, "pushTransform")) missing.push("aura.draw2d.pushTransform");
+  if (!hasMethod(aura.draw2d, "translate")) missing.push("aura.draw2d.translate");
+  if (!hasMethod(aura.draw2d, "rotate")) missing.push("aura.draw2d.rotate");
+  if (!hasMethod(aura.draw2d, "rect")) missing.push("aura.draw2d.rect");
+  if (!hasMethod(aura.draw2d, "popTransform")) missing.push("aura.draw2d.popTransform");
+  if (!hasMethod(aura.draw2d, "text")) missing.push("aura.draw2d.text");
+  if (!hasMethod(aura.draw2d, "measureText")) missing.push("aura.draw2d.measureText");
+  if (!hasMethod(aura.collision, "rectRect")) missing.push("aura.collision.rectRect");
+  if (!hasMethod(aura.assets, "exists")) missing.push("aura.assets.exists");
+  if (!hasMethod(aura.math, "clamp")) missing.push("aura.math.clamp");
+  if (typeof aura.rgb !== "function") missing.push("aura.rgb");
+  if (typeof aura.rgba !== "function") missing.push("aura.rgba");
+  if (!aura.Color || !aura.Color.WHITE) missing.push("aura.Color.WHITE");
+  if (!aura.Color || !aura.Color.YELLOW) missing.push("aura.Color.YELLOW");
+
+  if (missing.length > 0) {
+    failWithReason("missing_runtime_api", `runtime missing required APIs: ${missing.join(", ")}`);
+  }
+
+  const small = aura.draw2d.measureText("Probe", { size: 8 });
+  const large = aura.draw2d.measureText("Probe", { size: 24 });
+  if (!Number.isFinite(Number(small?.width)) || !Number.isFinite(Number(large?.width)) || Number(large.width) <= Number(small.width)) {
+    failWithReason(
+      "placeholder_runtime_behavior",
+      "draw2d.measureText appears to be placeholder behavior (size does not affect width).",
+    );
+  }
+}
+
 function keyDown(name) {
   if (aura.input && typeof aura.input.isKeyDown === "function") {
     return aura.input.isKeyDown(name);
@@ -105,6 +152,7 @@ function clearScreen(color) {
 }
 
 aura.setup = function () {
+  assertRuntimeCapabilities();
   console.log("{{PROJECT_NAME}} started");
   if (!hasAsset(PLAYER_SPRITE_PATH)) {
     console.log(`Tip: add assets/${PLAYER_SPRITE_PATH} to preview sprite draw2d options.`);