@flare-engine/create 0.4.0

package/templates/shmup/src/logic.ts

@@ -0,0 +1,356 @@
+/**
+ * Shmup game logic — RN/Skia-free core.
+ *
+ * This module contains ZERO React or Skia imports so it can be unit-tested
+ * in a plain bun/node environment without mocking any native modules.
+ *
+ * Design decisions:
+ *   - Position objects are pooled (pre-allocated) so fireBullet/spawnEnemy
+ *     never create heap garbage in steady state.
+ *   - Velocity and Sprite are shared singleton references stored once on
+ *     each entity; mutating them would affect all entities of that type.
+ *   - Queries are registered once in createShmupState (World.query() is
+ *     permanent — never call it inside a frame update).
+ *   - hitBullets/hitEnemies scratch arrays are grow-only (length=0 reset
+ *     each call, never re-allocated once grown to peak frame size).
+ *   - world.step(dt) is NOT called here — the shell's onUpdate must call it
+ *     before stepShmup so movement and bounds-cull run first.
+ */
+import {
+  type CullBounds,
+  Position,
+  Velocity,
+  createBoundsCullSystem,
+  createMovementSystem,
+  defineComponent,
+} from '@flare-engine/ecs';
+import type { Query, World } from '@flare-engine/ecs';
+import type { SpriteData } from '@flare-engine/render';
+import { Sprite } from '@flare-engine/render';
+
+// ─── Tag components ──────────────────────────────────────────────────────────
+
+/** Marks an entity as a player bullet. */
+export const Bullet = defineComponent('Bullet');
+
+/** Marks an entity as an enemy. */
+export const Enemy = defineComponent('Enemy');
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+/** Bullet travel speed in px/s (upward). */
+export const BULLET_SPEED = 420;
+/** Enemy travel speed in px/s (downward). */
+export const ENEMY_SPEED = 80;
+/** Seconds between shots. */
+export const FIRE_INTERVAL = 0.12;
+/** Seconds between enemy spawns. */
+export const SPAWN_INTERVAL = 1.4;
+/** Maximum live bullets (bounds the pool size). */
+export const MAX_BULLETS = 64;
+/** Maximum live enemies (bounds the pool size). */
+export const MAX_ENEMIES = 16;
+
+/** AABB half-extents for collision detection (pixels). */
+export const BULLET_HW = 3;
+export const BULLET_HH = 6;
+export const ENEMY_HW = 12;
+export const ENEMY_HH = 12;
+
+/** Deterministic spawn X positions across a ~320 px wide screen. */
+const SPAWN_XS = [24, 72, 120, 168, 216, 264, 312] as const;
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+/** Mutable version of CullBounds so the shell can resize after layout. */
+export interface ShmupBounds {
+  minX: number;
+  minY: number;
+  maxX: number;
+  maxY: number;
+}
+
+/** Handle returned by setupShmup. */
+export interface ShmupSetup {
+  /** Live screen bounds for the cull system — mutate after layout. */
+  bounds: ShmupBounds;
+  /**
+   * Ref the shell MUST populate after createShmupState so the onCull
+   * callback can return Positions to the right pool.
+   */
+  stateRef: { current: ShmupState | null };
+}
+
+/** All mutable game state for one shmup session. */
+export interface ShmupState {
+  /** Pre-allocated Position free-list for bullets. */
+  bulletPool: Array<{ x: number; y: number }>;
+  /** Pre-allocated Position free-list for enemies. */
+  enemyPool: Array<{ x: number; y: number }>;
+  /** Shared velocity applied to every bullet entity. */
+  readonly bulletVel: { x: number; y: number };
+  /** Shared velocity applied to every enemy entity. */
+  readonly enemyVel: { x: number; y: number };
+  /** Shared SpriteData reference reused for every bullet entity. */
+  readonly bulletSprite: SpriteData;
+  /** Shared SpriteData reference reused for every enemy entity. */
+  readonly enemySprite: SpriteData;
+  /** Seconds elapsed since the last bullet was fired. */
+  fireTimer: number;
+  /** Seconds elapsed since the last enemy was spawned. */
+  spawnTimer: number;
+  /** Total enemies destroyed this session. */
+  score: number;
+  /** Permanent ECS query for (Position, Bullet) — created once, never inside onUpdate. */
+  readonly bulletQuery: Query;
+  /** Permanent ECS query for (Position, Enemy) — created once, never inside onUpdate. */
+  readonly enemyQuery: Query;
+  /** Incremented each spawn to cycle through SPAWN_XS deterministically. */
+  spawnCounter: number;
+  /** Scratch: bullet IDs involved in this frame's collisions — grow-only, reused. */
+  readonly hitBullets: number[];
+  /** Scratch: enemy IDs involved in this frame's collisions — grow-only, reused. */
+  readonly hitEnemies: number[];
+}
+
+// ─── Pure helpers ─────────────────────────────────────────────────────────────
+
+/**
+ * Returns true when two axis-aligned boxes overlap (inclusive edge-touch).
+ *
+ * Parameters are center positions and half-extents (px).
+ */
+export function aabbOverlap(
+  ax: number, ay: number, ahw: number, ahh: number,
+  bx: number, by: number, bhw: number, bhh: number,
+): boolean {
+  return Math.abs(ax - bx) <= ahw + bhw && Math.abs(ay - by) <= ahh + bhh;
+}
+
+// ─── Setup ────────────────────────────────────────────────────────────────────
+
+/**
+ * Register the movement and bounds-cull world systems, then return a handle
+ * so the shell can size the bounds to the viewport and wire up the state pool.
+ *
+ * Usage in onReady:
+ *   const { bounds, stateRef } = setupShmup(ctx.world);
+ *   // optionally: bounds.maxX = camera.viewportWidth; ...
+ *   const state = createShmupState(ctx.world, bulletSprite, enemySprite);
+ *   stateRef.current = state;     ← REQUIRED before the first frame runs
+ */
+export function setupShmup(world: World): ShmupSetup {
+  const moveSys = createMovementSystem(world);
+  world.addSystem(moveSys._worldFn, 0); // priority 0: integrate positions first
+
+  // Sensible defaults for a portrait phone; shell mutates after layout if needed.
+  const bounds: ShmupBounds = { minX: -32, minY: -64, maxX: 432, maxY: 900 };
+
+  // Forward reference so onCull can access pools even though state is created after setup.
+  const stateRef: { current: ShmupState | null } = { current: null };
+
+  const cullSys = createBoundsCullSystem(
+    world,
+    bounds as CullBounds,
+    (id, w) => {
+      const state = stateRef.current;
+      if (state === null) return;
+
+      // Return pooled Position before destroying; player has neither tag → skip.
+      if (w.has(id, Bullet)) {
+        const pos = w.get(id, Position);
+        if (pos !== undefined) state.bulletPool.push(pos);
+        w.destroy(id);
+      } else if (w.has(id, Enemy)) {
+        const pos = w.get(id, Position);
+        if (pos !== undefined) state.enemyPool.push(pos);
+        w.destroy(id);
+      }
+    },
+  );
+  world.addSystem(cullSys._worldFn, 2); // priority 2: cull after movement
+
+  return { bounds, stateRef };
+}
+
+// ─── State ────────────────────────────────────────────────────────────────────
+
+/**
+ * Allocate all mutable game state and register permanent ECS queries.
+ *
+ * Call ONCE in onReady, after setupShmup, then assign the result to
+ * stateRef.current so the cull callback can return pooled Positions.
+ */
+export function createShmupState(
+  world: World,
+  bulletSprite: SpriteData,
+  enemySprite: SpriteData,
+): ShmupState {
+  // Pre-allocate Position free-lists — no heap writes during play.
+  const bulletPool: Array<{ x: number; y: number }> = [];
+  for (let i = 0; i < MAX_BULLETS; i++) bulletPool.push({ x: 0, y: 0 });
+
+  const enemyPool: Array<{ x: number; y: number }> = [];
+  for (let i = 0; i < MAX_ENEMIES; i++) enemyPool.push({ x: 0, y: 0 });
+
+  return {
+    bulletPool,
+    enemyPool,
+    bulletVel: { x: 0, y: -BULLET_SPEED },
+    enemyVel: { x: 0, y: ENEMY_SPEED },
+    bulletSprite,
+    enemySprite,
+    fireTimer: 0,
+    spawnTimer: 0,
+    score: 0,
+    // Registered here and never re-created — World.query() is permanent.
+    bulletQuery: world.query(Position, Bullet),
+    enemyQuery: world.query(Position, Enemy),
+    spawnCounter: 0,
+    hitBullets: [],
+    hitEnemies: [],
+  };
+}
+
+// ─── Per-entity helpers ───────────────────────────────────────────────────────
+
+/**
+ * Fire one bullet from the pool at (x, y).
+ *
+ * Zero heap allocation: Position is taken from the pre-allocated bulletPool;
+ * Velocity and Sprite are stored as shared references (no copy).
+ * Silently skips when the pool is exhausted — no throw, no new allocation.
+ */
+export function fireBullet(
+  world: World,
+  state: ShmupState,
+  x: number,
+  y: number,
+  sprite: SpriteData,
+): void {
+  const pos = state.bulletPool.pop();
+  if (pos === undefined) return; // pool exhausted — skip silently
+
+  pos.x = x;
+  pos.y = y;
+  const id = world.spawn();
+  world.add(id, Position, pos);
+  world.add(id, Velocity, state.bulletVel); // shared ref — no copy
+  world.add(id, Sprite, sprite);            // shared ref — no copy
+  world.add(id, Bullet);
+}
+
+/**
+ * Spawn one enemy from the pool at (x, -16) moving downward.
+ *
+ * Zero heap allocation: same discipline as fireBullet.
+ */
+export function spawnEnemy(
+  world: World,
+  state: ShmupState,
+  x: number,
+  sprite: SpriteData,
+): void {
+  const pos = state.enemyPool.pop();
+  if (pos === undefined) return; // pool exhausted — skip silently
+
+  pos.x = x;
+  pos.y = -16; // spawn above the visible area
+  const id = world.spawn();
+  world.add(id, Position, pos);
+  world.add(id, Velocity, state.enemyVel); // shared ref
+  world.add(id, Sprite, sprite);           // shared ref
+  world.add(id, Enemy);
+}
+
+// ─── Frame update ─────────────────────────────────────────────────────────────
+
+/**
+ * Advance game logic for one frame.
+ *
+ * Fires bullets and spawns enemies on timers, detects bullet-enemy AABB
+ * collisions, destroys hits, returns pooled Positions, and returns the
+ * number of new kills.
+ *
+ * No per-frame object literals or `new` expressions in this module.
+ * (Iterating an engine Query allocates a short-lived iterator on Hermes —
+ *  an engine detail, not template garbage.)
+ * Other hot-path facts:
+ *   - hitBullets/hitEnemies reset via `.length = 0` (no free/alloc)
+ *   - Pool push reuses pre-allocated array capacity
+ *
+ * Calling order per onUpdate frame (shell responsibility):
+ *   1. Move player in-place from joystick input
+ *   2. ctx.world.step(dt)   ← run movement + bounds-cull systems
+ *   3. stepShmup(...)        ← fire, spawn, detect collisions
+ */
+export function stepShmup(
+  world: World,
+  state: ShmupState,
+  dt: number,
+  playerX: number,
+  playerY: number,
+): number {
+  // ── Fire bullets ────────────────────────────────────────────────────────────
+  state.fireTimer += dt;
+  while (state.fireTimer >= FIRE_INTERVAL) {
+    state.fireTimer -= FIRE_INTERVAL;
+    fireBullet(world, state, playerX, playerY - 16, state.bulletSprite);
+  }
+
+  // ── Spawn enemies (deterministic x, NOT Math.random) ────────────────────────
+  state.spawnTimer += dt;
+  if (state.spawnTimer >= SPAWN_INTERVAL) {
+    state.spawnTimer -= SPAWN_INTERVAL;
+    const spawnX = SPAWN_XS[state.spawnCounter % SPAWN_XS.length] ?? SPAWN_XS[0]!;
+    state.spawnCounter++;
+    spawnEnemy(world, state, spawnX, state.enemySprite);
+  }
+
+  // ── Collect bullet-enemy collision pairs ────────────────────────────────────
+  // Reset scratch arrays without freeing — grow-only, zero steady-state alloc.
+  state.hitBullets.length = 0;
+  state.hitEnemies.length = 0;
+
+  // Indexed walk over the live id arrays: `for...of` over a Query allocates an
+  // iterator per loop (and, on Hermes, a result object per entity), and this
+  // nest would pay that once per bullet per frame.
+  const bulletIds = state.bulletQuery.entities;
+  const enemyIds = state.enemyQuery.entities;
+  for (let b = 0; b < bulletIds.length; b++) {
+    const bId = bulletIds[b]!;
+    const bPos = world.get(bId, Position);
+    if (bPos === undefined) continue;
+    for (let e = 0; e < enemyIds.length; e++) {
+      const eId = enemyIds[e]!;
+      const ePos = world.get(eId, Position);
+      if (ePos === undefined) continue;
+      if (aabbOverlap(bPos.x, bPos.y, BULLET_HW, BULLET_HH, ePos.x, ePos.y, ENEMY_HW, ENEMY_HH)) {
+        state.hitBullets.push(bId);
+        state.hitEnemies.push(eId);
+        break; // one bullet can only hit one enemy per frame
+      }
+    }
+  }
+
+  // ── Destroy hits AFTER the query loops (no mid-iteration splice) ────────────
+  let kills = 0;
+  for (let i = 0; i < state.hitBullets.length; i++) {
+    const bId = state.hitBullets[i]!;
+    const eId = state.hitEnemies[i]!;
+    if (world.exists(bId)) {
+      const bPos = world.get(bId, Position);
+      if (bPos !== undefined) state.bulletPool.push(bPos);
+      world.destroy(bId);
+    }
+    if (world.exists(eId)) {
+      const ePos = world.get(eId, Position);
+      if (ePos !== undefined) state.enemyPool.push(ePos);
+      world.destroy(eId);
+      kills++;
+    }
+  }
+
+  state.score += kills;
+  return kills;
+}

package/templates/shmup/tests/logic.test.ts

@@ -0,0 +1,235 @@
+/**
+ * Headless tests for the shmup logic module.
+ *
+ * No Skia, no React Native — just a real World and the pure game logic.
+ * This is the "old shmup leaked Positions / new shmup pools them" proof.
+ *
+ * World.query() registers permanent queries — do NOT call _resetComponentIds()
+ * here; component IDs are module-level and stable across the whole test run.
+ */
+import { describe, expect, test } from 'bun:test';
+import { Position, World } from '@flare-engine/ecs';
+import type { SpriteData } from '@flare-engine/render';
+import {
+  BULLET_HH,
+  BULLET_HW,
+  BULLET_SPEED,
+  ENEMY_HH,
+  ENEMY_HW,
+  MAX_BULLETS,
+  MAX_ENEMIES,
+  aabbOverlap,
+  createShmupState,
+  fireBullet,
+  setupShmup,
+  spawnEnemy,
+  stepShmup,
+} from '../src/logic';
+
+// Fake SpriteData — logic.ts stores the reference but never accesses fields.
+const FAKE_SPRITE = {} as unknown as SpriteData;
+
+// ─── aabbOverlap ─────────────────────────────────────────────────────────────
+
+describe('aabbOverlap', () => {
+  test('true when boxes overlap', () => {
+    // A: center (0,0) hw=5 hh=5; B: center (3,3) hw=5 hh=5 — clearly overlapping
+    expect(aabbOverlap(0, 0, 5, 5, 3, 3, 5, 5)).toBe(true);
+  });
+
+  test('false when boxes are clearly separated', () => {
+    // A: center (0,0) hw=5; B: center (20,0) hw=5 — gap of 10
+    expect(aabbOverlap(0, 0, 5, 5, 20, 0, 5, 5)).toBe(false);
+  });
+
+  test('true on edge-touch (inclusive boundary)', () => {
+    // A right edge at 0+5=5; B left edge at 10-5=5 → touching, inclusive → true
+    expect(aabbOverlap(0, 0, 5, 5, 10, 0, 5, 5)).toBe(true);
+  });
+
+  test('false just outside touch boundary', () => {
+    // x-distance = 11, sum of hw = 10 → separated
+    expect(aabbOverlap(0, 0, 5, 5, 11, 0, 5, 5)).toBe(false);
+  });
+});
+
+// ─── AABB constants sanity ────────────────────────────────────────────────────
+
+describe('AABB constants', () => {
+  test('BULLET_HW / BULLET_HH are positive', () => {
+    expect(BULLET_HW).toBeGreaterThan(0);
+    expect(BULLET_HH).toBeGreaterThan(0);
+  });
+
+  test('ENEMY_HW / ENEMY_HH are positive', () => {
+    expect(ENEMY_HW).toBeGreaterThan(0);
+    expect(ENEMY_HH).toBeGreaterThan(0);
+  });
+
+  test('bullet and enemy at same center overlap', () => {
+    expect(aabbOverlap(0, 0, BULLET_HW, BULLET_HH, 0, 0, ENEMY_HW, ENEMY_HH)).toBe(true);
+  });
+
+  test('BULLET_SPEED is positive', () => {
+    expect(BULLET_SPEED).toBeGreaterThan(0);
+  });
+});
+
+// ─── fireBullet pool behaviour ────────────────────────────────────────────────
+
+describe('fireBullet', () => {
+  test('bullet query count rises after firing', () => {
+    const world = new World();
+    const { stateRef } = setupShmup(world);
+    const state = createShmupState(world, FAKE_SPRITE, FAKE_SPRITE);
+    stateRef.current = state;
+
+    fireBullet(world, state, 100, 400, FAKE_SPRITE);
+    fireBullet(world, state, 100, 400, FAKE_SPRITE);
+    fireBullet(world, state, 100, 400, FAKE_SPRITE);
+
+    let count = 0;
+    for (const _ of state.bulletQuery) count++;
+    expect(count).toBe(3);
+  });
+
+  test('bullets culled at top bound — query empties, pool fully returned (no leak)', () => {
+    // This is the fail-old / pass-new proof: the old shmup never returned
+    // Positions to a pool; the new one does so in the cull callback.
+    const world = new World();
+    const { bounds, stateRef } = setupShmup(world);
+    const state = createShmupState(world, FAKE_SPRITE, FAKE_SPRITE);
+    stateRef.current = state;
+
+    // Cull anything above y = 0 (bullets travel upward).
+    bounds.minY = 0;
+    bounds.maxY = 1000;
+    bounds.minX = -1000;
+    bounds.maxX = 1000;
+
+    // Fire 4 bullets from y = 10.
+    // BULLET_SPEED px/s upward; dt = 0.1 → dy = -42 → new y = -32 < minY = 0 → culled.
+    for (let i = 0; i < 4; i++) fireBullet(world, state, 100, 10, FAKE_SPRITE);
+
+    let countBefore = 0;
+    for (const _ of state.bulletQuery) countBefore++;
+    expect(countBefore).toBe(4);
+    expect(state.bulletPool.length).toBe(MAX_BULLETS - 4);
+
+    // world.step runs: movement (priority 0) → cull (priority 2).
+    world.step(0.1);
+
+    let countAfter = 0;
+    for (const _ of state.bulletQuery) countAfter++;
+    expect(countAfter).toBe(0); // all culled
+
+    // All Positions must be back in the pool — zero leak.
+    expect(state.bulletPool.length).toBe(MAX_BULLETS);
+  });
+
+  test('pool exhaustion silently skips — no throw, count stays at cap', () => {
+    const world = new World();
+    const { stateRef } = setupShmup(world);
+    const state = createShmupState(world, FAKE_SPRITE, FAKE_SPRITE);
+    stateRef.current = state;
+
+    for (let i = 0; i < MAX_BULLETS; i++) fireBullet(world, state, 100, 400, FAKE_SPRITE);
+    expect(state.bulletPool.length).toBe(0);
+
+    // Extra fires must silently no-op — no throw, no new entities.
+    expect(() => {
+      fireBullet(world, state, 100, 400, FAKE_SPRITE);
+      fireBullet(world, state, 100, 400, FAKE_SPRITE);
+    }).not.toThrow();
+
+    let count = 0;
+    for (const _ of state.bulletQuery) count++;
+    expect(count).toBe(MAX_BULLETS); // unchanged
+  });
+});
+
+// ─── spawnEnemy pool behaviour ────────────────────────────────────────────────
+
+describe('spawnEnemy', () => {
+  test('enemy pool exhaustion silently skips', () => {
+    const world = new World();
+    const { stateRef } = setupShmup(world);
+    const state = createShmupState(world, FAKE_SPRITE, FAKE_SPRITE);
+    stateRef.current = state;
+
+    for (let i = 0; i < MAX_ENEMIES; i++) spawnEnemy(world, state, 100, FAKE_SPRITE);
+    expect(state.enemyPool.length).toBe(0);
+
+    expect(() => spawnEnemy(world, state, 100, FAKE_SPRITE)).not.toThrow();
+
+    let count = 0;
+    for (const _ of state.enemyQuery) count++;
+    expect(count).toBe(MAX_ENEMIES);
+  });
+});
+
+// ─── Collision and score ──────────────────────────────────────────────────────
+
+describe('stepShmup collision', () => {
+  test('bullet-enemy overlap destroys both, increments score, returns pools', () => {
+    const world = new World();
+    const { bounds, stateRef } = setupShmup(world);
+    // Wide bounds so nothing is culled during this test.
+    bounds.minX = -9999; bounds.maxX = 9999;
+    bounds.minY = -9999; bounds.maxY = 9999;
+
+    const state = createShmupState(world, FAKE_SPRITE, FAKE_SPRITE);
+    stateRef.current = state;
+
+    // Spawn a bullet and an enemy.
+    fireBullet(world, state, 100, 100, FAKE_SPRITE);
+    spawnEnemy(world, state, 100, FAKE_SPRITE); // enemy starts at y=-16
+
+    // Move the enemy to the bullet's y so they overlap.
+    // world.get with the live Position ComponentDef (same module-cache entry).
+    let enemyId: number | undefined;
+    for (const id of state.enemyQuery) { enemyId = id; break; }
+    expect(enemyId).not.toBeUndefined();
+
+    const ePos = world.get(enemyId!, Position);
+    expect(ePos).not.toBeUndefined();
+    ePos!.y = 100; // bullet is at (100, 100); now enemy is too
+
+    // With dt = 0.001: fireTimer stays below FIRE_INTERVAL, spawnTimer stays
+    // below SPAWN_INTERVAL → only collision detection runs.
+    const kills = stepShmup(world, state, 0.001, 0, 900);
+
+    expect(kills).toBe(1);
+    expect(state.score).toBe(1);
+
+    // Both entities destroyed.
+    let bCount = 0;
+    for (const _ of state.bulletQuery) bCount++;
+    expect(bCount).toBe(0);
+
+    let eCount = 0;
+    for (const _ of state.enemyQuery) eCount++;
+    expect(eCount).toBe(0);
+
+    // Positions returned to pools — zero leak.
+    expect(state.bulletPool.length).toBe(MAX_BULLETS);
+    expect(state.enemyPool.length).toBe(MAX_ENEMIES);
+  });
+
+  test('non-overlapping bullet and enemy produce zero kills', () => {
+    const world = new World();
+    const { bounds, stateRef } = setupShmup(world);
+    bounds.minX = -9999; bounds.maxX = 9999;
+    bounds.minY = -9999; bounds.maxY = 9999;
+
+    const state = createShmupState(world, FAKE_SPRITE, FAKE_SPRITE);
+    stateRef.current = state;
+
+    fireBullet(world, state, 100, 100, FAKE_SPRITE);
+    spawnEnemy(world, state, 300, FAKE_SPRITE); // far away in x
+
+    const kills = stepShmup(world, state, 0.001, 0, 900);
+    expect(kills).toBe(0);
+    expect(state.score).toBe(0);
+  });
+});

package/templates/shmup/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "jsx": "react-native",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noUncheckedIndexedAccess": true
+  },
+  "include": ["src", "index.ts", "index.web.ts"]
+}

package/templates/topdown/README.md

@@ -0,0 +1,79 @@
+# {{APP_NAME}}
+
+A Flare engine app scaffolded from the `{{TEMPLATE_ID}}` template.
+
+## Develop
+
+```bash
+bun install
+bun run android   # or: bun run ios
+```
+
+`@shopify/react-native-skia` is a **native** module, so this template needs a
+dev build — it cannot run in Expo Go. `bun run start` then pressing `a`/`i`
+opens Expo Go and red-screens with a missing-native-module error. `bun run
+android` builds and installs a dev client instead; after that first build,
+`bun run start` attaches to it normally.
+
+The first Android build takes a few minutes and needs the Android SDK plus a
+JDK. Two things that will otherwise cost you an afternoon:
+
+- **Build from a short path.** Skia's CMake step generates paths ~120
+  characters longer than your project directory, and Windows still fails at 260
+  (`CreateProcess error=2`). `C:\src\my-app` is fine; a deep temp path is not.
+- **Do not remove `trustedDependencies` from `package.json`.** Bun blocks
+  install scripts it does not trust, and Skia's `postinstall` is what unpacks
+  its prebuilt binaries. Without it the install still succeeds and the Android
+  build fails minutes later with `Could not find libskia.a`.
+
+## Run in a browser
+
+```bash
+bun run web
+```
+
+The `web` script copies CanvasKit's wasm binary into `public/` before starting
+Metro, because Skia on web is CanvasKit and it has to be served alongside the
+bundle. Starting the dev server any other way — `bun run start` then pressing
+`w` — skips that copy and the canvas stays blank.
+
+The binary is ~8 MB and is `.gitignore`d: it is a copy of
+`canvaskit-wasm/bin/full/canvaskit.wasm`, reproduced by the script on demand.
+It must be the `full` build; the smaller default build is ABI-incompatible with
+the loader.
+
+## What this template demonstrates
+
+A top-down starter built around one scene: a 4x8 house on an open field,
+with rocks and an openable door.
+
+- `src/map.ts` — edit `MAP_ART` (ASCII art: `#` wall, `.` grass, `R` rock, `D` door) to reshape the map.
+- Collision: `@flare-engine/physics` `buildSolidGrid` + `moveAndSlideInto` over wall, rock, and closed-door tiles; axis-separated slide so diagonal inputs slide along walls instead of stopping.
+- **The door**: walking into it while closed opens it — `map.ts`'s `openDoor` flips its cell in the `SolidGrid.solid` array and swaps its tile GID so the render picks up the open frame, both plain zero-alloc index writes into arrays the engine already owns. That is a tile whose solidity changes at runtime, not just its colour; `isBlockedAABB`/`moveAndSlideInto` treat the door exactly like a wall until it's opened.
+- Camera: `camera.follow` tracks the player; zoom is set to 2×.
+- A `VirtualJoystick` drives analog movement — all 8 directions and diagonals work.
+
+## Layout
+
+- `src/App.tsx` — root component; mounts `<GameView>` and configures the Flare game loop.
+- `src/map.ts` — ASCII-art map, Tiled JSON builder, and `loadMap()`.
+- `index.ts` — Expo entry that registers `App` as the root component (native).
+- `index.web.ts` — web entry; awaits `LoadSkiaWeb()` **before** importing `App`.
+  `package.json`'s `main` is extensionless so Metro resolves the right entry per
+  platform. The split is required: RN-Skia's web module reads `global.CanvasKit`
+  when it is first imported, so importing `App` any earlier leaves Skia hollow.
+- `scripts/copy-canvaskit.mjs` — copies the CanvasKit wasm into `public/` for the
+  web build.
+- `app.json` — Expo configuration.
+
+## Tests
+
+```bash
+bun test
+```
+
+Runs `tests/tilemap.test.ts` — validates the map parse, collider extraction, solid-grid query, and that the closed door blocks while the open door and wall/rock collision are unaffected by opening it.
+
+## Docs
+
+- [Flare engine](https://github.com/grzott/flare-engine)

package/templates/topdown/app.json

@@ -0,0 +1,10 @@
+{
+  "expo": {
+    "name": "{{APP_NAME}}",
+    "slug": "{{APP_NAME}}",
+    "version": "0.1.0",
+    "orientation": "portrait",
+    "platforms": ["android", "ios", "web"],
+    "newArchEnabled": true
+  }
+}