@flare-engine/create 0.4.0

package/templates/blank/metro.config.js

@@ -0,0 +1,3 @@
+const { getDefaultConfig } = require("expo/metro-config");
+
+module.exports = getDefaultConfig(__dirname);

package/templates/blank/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "{{APP_NAME}}",
+  "version": "0.1.0",
+  "private": true,
+  "main": "index",
+  "scripts": {
+    "start": "expo start",
+    "android": "expo run:android",
+    "ios": "expo run:ios",
+    "web": "node scripts/copy-canvaskit.mjs && expo start --web"
+  },
+  "dependencies": {
+    "@expo/metro-runtime": "~57.0.0",
+    "@flare-engine/engine": "{{FLARE_VERSION}}",
+    "@flare-engine/react": "{{FLARE_VERSION}}",
+    "@shopify/react-native-skia": "2.6.0",
+    "canvaskit-wasm": "0.41.0",
+    "expo": "~57.0.0",
+    "expo-status-bar": "~57.0.0",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "react-native": "0.86.0",
+    "react-native-reanimated": "~4.5.0",
+    "react-native-safe-area-context": "~5.6.0",
+    "react-native-web": "~0.21.0",
+    "react-native-worklets": "~0.10.0"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.25.0",
+    "@types/react": "~19.2.0",
+    "typescript": "^5.5.0"
+  },
+  "trustedDependencies": [
+    "@shopify/react-native-skia"
+  ]
+}

package/templates/blank/scripts/copy-canvaskit.mjs

@@ -0,0 +1,15 @@
+import { copyFile, mkdir } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+
+// LoadSkiaWeb imports canvaskit-wasm/bin/full/canvaskit, so the binary served
+// at / must be the `full` build (~8 MB). bin/canvaskit.wasm is a smaller,
+// ABI-incompatible variant — serving it fails at runtime, not at build time.
+const require = createRequire(import.meta.url);
+const source = require.resolve("canvaskit-wasm/bin/full/canvaskit.wasm");
+const targetDir = join(process.cwd(), "public");
+
+await mkdir(targetDir, { recursive: true });
+await copyFile(source, join(targetDir, "canvaskit.wasm"));
+
+console.log("copy-canvaskit: public/canvaskit.wasm");

package/templates/blank/src/App.tsx

@@ -0,0 +1,45 @@
+import { Position, Sprite, createProceduralAtlas } from "@flare-engine/engine";
+import type { GameContextValue } from "@flare-engine/engine";
+import { GameView, skiaAtlasModule } from "@flare-engine/react";
+import type React from "react";
+import { StyleSheet, View } from "react-native";
+import { SafeAreaProvider } from "react-native-safe-area-context";
+
+// One cyan square rendered at world origin.
+// Camera default is also (0, 0), so worldToScreen(0, 0) = screen center.
+const ATLAS_FRAMES = [{ name: "sprite", w: 64, h: 64, color: 0xff6bcfff }] as const;
+
+function onReady(ctx: GameContextValue): void {
+  // createProceduralAtlas draws colored rects onto a Skia surface.
+  // Must be called inside onReady — Skia context is live by this point.
+  const atlas = createProceduralAtlas(skiaAtlasModule, ATLAS_FRAMES);
+  const frame = atlas.sheet.frames.find((f) => f.name === "sprite");
+  if (!frame) return;
+
+  const entity = ctx.world.spawn();
+  ctx.world.add(entity, Position, { x: 0, y: 0 });
+  ctx.world.add(entity, Sprite, {
+    image: atlas.image,
+    frame,
+    z: 0,
+    width: frame.w,
+    height: frame.h,
+    anchor: { x: 0.5, y: 0.5 },
+  });
+  // GameView starts the loop after onReady returns — do NOT call ctx.loop.start().
+}
+
+export function App(): React.ReactElement {
+  return (
+    <SafeAreaProvider>
+      <View style={styles.root}>
+        <GameView onReady={onReady} style={styles.game} />
+      </View>
+    </SafeAreaProvider>
+  );
+}
+
+const styles = StyleSheet.create({
+  root: { flex: 1, backgroundColor: "#000" },
+  game: { flex: 1 },
+});

package/templates/blank/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/shmup/README.md

@@ -0,0 +1,59 @@
+# {{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.
+
+## Layout
+
+- `src/App.tsx` — root component; mounts `<GameView>` and configures the Flare game loop.
+- `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.
+
+## Docs
+
+- [Flare engine](https://github.com/grzott/flare-engine)

package/templates/shmup/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
+  }
+}

package/templates/shmup/babel.config.js

@@ -0,0 +1,7 @@
+module.exports = function (api) {
+  api.cache(true);
+  return {
+    presets: ['babel-preset-expo'],
+    plugins: ['react-native-worklets/plugin'],
+  };
+};

package/templates/shmup/gitignore

@@ -0,0 +1,8 @@
+node_modules
+public/canvaskit.wasm
+.expo
+dist
+*.log
+.DS_Store
+android
+ios

package/templates/shmup/index.ts

@@ -0,0 +1,4 @@
+import { registerRootComponent } from "expo";
+import { App } from "./src/App";
+
+registerRootComponent(App);

package/templates/shmup/index.web.ts

@@ -0,0 +1,17 @@
+import { LoadSkiaWeb } from "@shopify/react-native-skia/lib/module/web";
+import { registerRootComponent } from "expo";
+
+// Metro picks this file over index.ts on web because package.json's `main` is
+// extensionless. Keeping the web entry separate is not cosmetic: RN-Skia's web
+// module builds its Skia object from global.CanvasKit at module-eval time, so
+// anything that imports Skia must be loaded only after LoadSkiaWeb resolves.
+// A static `import { App }` here would leave Skia permanently hollow and
+// GameView would throw on Skia.Paint.
+//
+// `bun run web` copies canvaskit.wasm into public/, which Expo serves at the
+// web root — that is what locateFile points at.
+void (async () => {
+  await LoadSkiaWeb({ locateFile: (file: string) => `/${file}` });
+  const { App } = await import("./src/App");
+  registerRootComponent(App);
+})();

package/templates/shmup/metro.config.js

@@ -0,0 +1,3 @@
+const { getDefaultConfig } = require('expo/metro-config');
+
+module.exports = getDefaultConfig(__dirname);

package/templates/shmup/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "{{APP_NAME}}",
+  "version": "0.1.0",
+  "private": true,
+  "main": "index",
+  "scripts": {
+    "start": "expo start",
+    "android": "expo run:android",
+    "ios": "expo run:ios",
+    "web": "node scripts/copy-canvaskit.mjs && expo start --web",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@expo/metro-runtime": "~57.0.0",
+    "@flare-engine/ecs": "{{FLARE_VERSION}}",
+    "@flare-engine/engine": "{{FLARE_VERSION}}",
+    "@flare-engine/react": "{{FLARE_VERSION}}",
+    "@flare-engine/render": "{{FLARE_VERSION}}",
+    "@shopify/react-native-skia": "2.6.0",
+    "canvaskit-wasm": "0.41.0",
+    "expo": "~57.0.0",
+    "expo-status-bar": "~57.0.0",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "react-native": "0.86.0",
+    "react-native-reanimated": "~4.5.0",
+    "react-native-safe-area-context": "~5.6.0",
+    "react-native-web": "~0.21.0",
+    "react-native-worklets": "~0.10.0"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.25.0",
+    "@types/react": "~19.2.0",
+    "typescript": "^5.5.0"
+  },
+  "trustedDependencies": [
+    "@shopify/react-native-skia"
+  ]
+}

package/templates/shmup/scripts/copy-canvaskit.mjs

@@ -0,0 +1,15 @@
+import { copyFile, mkdir } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+
+// LoadSkiaWeb imports canvaskit-wasm/bin/full/canvaskit, so the binary served
+// at / must be the `full` build (~8 MB). bin/canvaskit.wasm is a smaller,
+// ABI-incompatible variant — serving it fails at runtime, not at build time.
+const require = createRequire(import.meta.url);
+const source = require.resolve("canvaskit-wasm/bin/full/canvaskit.wasm");
+const targetDir = join(process.cwd(), "public");
+
+await mkdir(targetDir, { recursive: true });
+await copyFile(source, join(targetDir, "canvaskit.wasm"));
+
+console.log("copy-canvaskit: public/canvaskit.wasm");

package/templates/shmup/src/App.tsx

@@ -0,0 +1,171 @@
+/**
+ * Shmup starter template — thin React Native shell.
+ *
+ * The heavy logic lives in ./logic.ts (headless, no Skia dependency) so it
+ * can be unit-tested without mocks.  This file owns only:
+ *   - Atlas build (needs Skia surface)
+ *   - ECS entity spawn (player)
+ *   - Joystick → player movement
+ *   - Score HUD
+ *   - Wiring the frame loop
+ *
+ * Key conventions:
+ *   DO NOT call ctx.loop.start() — GameView calls it after onReady returns.
+ *   DO call ctx.world.step(dt) in onUpdate — GameLoop does NOT auto-step the world.
+ *   Create all ECS queries in onReady (World.query() registers a permanent query).
+ */
+import { Position, Sprite, createProceduralAtlas } from "@flare-engine/engine";
+import type { GameContextValue, VirtualJoystickState } from "@flare-engine/engine";
+import { GameView, VirtualJoystick, skiaAtlasModule } from "@flare-engine/react";
+import type React from "react";
+import { useCallback, useMemo, useRef, useState } from "react";
+import { StyleSheet, Text, View } from "react-native";
+import { SafeAreaProvider } from "react-native-safe-area-context";
+import {
+  createShmupState,
+  setupShmup,
+  stepShmup,
+} from "./logic";
+
+// ─── Colour palette ───────────────────────────────────────────────────────────
+// ARGB hex constants.  Change these to re-skin the whole game in seconds.
+const COLOR_PLAYER  = 0xff6bcfff; // cyan-ish ship
+const COLOR_BULLET  = 0xffffe566; // bright yellow
+const COLOR_ENEMY   = 0xffff5454; // hostile red
+
+// ─── Atlas frames ─────────────────────────────────────────────────────────────
+const ATLAS_FRAMES = [
+  { name: "player", w: 16, h: 20, color: COLOR_PLAYER },
+  { name: "bullet", w:  6, h: 12, color: COLOR_BULLET },
+  { name: "enemy",  w: 24, h: 24, color: COLOR_ENEMY  },
+] as const;
+
+const PLAYER_START_X = 160;
+const PLAYER_START_Y = 600;
+const PLAYER_HALF_W  = 8;
+const PLAYER_HALF_H  = 10;
+const PLAYER_SPEED   = 200; // px/s
+
+export function App(): React.ReactElement {
+  const dirRef = useRef({ x: 0, y: 0 });
+  const [score, setScore] = useState(0);
+
+  // GameView's onRenderBackground hook is optional; kept empty here — we rely
+  // on the built-in (Position, Sprite) render system.
+  const config = useMemo(() => ({}), []);
+
+  const handleReady = useCallback((ctx: GameContextValue): void => {
+    // ── Build atlas ───────────────────────────────────────────────────────────
+    // createProceduralAtlas draws solid-colour rects onto a Skia surface.
+    // Must be called inside onReady (Skia context is live by this point).
+    // skiaAtlasModule centralises the Skia → SkiaAtlasModuleLike adaptation.
+    const atlas = createProceduralAtlas(skiaAtlasModule, ATLAS_FRAMES);
+
+    const playerFrame = atlas.sheet.frames.find((f) => f.name === "player")!;
+    const bulletFrame = atlas.sheet.frames.find((f) => f.name === "bullet")!;
+    const enemyFrame  = atlas.sheet.frames.find((f) => f.name === "enemy")!;
+
+    // ── Register engine systems + get the mutable bounds handle ──────────────
+    // setupShmup registers createMovementSystem (priority 0) and
+    // createBoundsCullSystem (priority 2).  bounds is updated every frame in
+    // onUpdate from the live camera viewport so wide screens never misfire.
+    const { bounds, stateRef } = setupShmup(ctx.world);
+
+    // ── Spawn player ──────────────────────────────────────────────────────────
+    const player = ctx.world.spawn();
+    ctx.world.add(player, Position, { x: PLAYER_START_X, y: PLAYER_START_Y });
+    ctx.world.add(player, Sprite, {
+      image: atlas.image,
+      frame: playerFrame,
+      z: 1,
+      width: playerFrame.w,
+      height: playerFrame.h,
+      anchor: { x: 0.5, y: 0.5 },
+    });
+
+    // ── Build shared sprite data for bullets and enemies ──────────────────────
+    // These objects are passed to every bullet/enemy entity by reference —
+    // no per-entity copy, satisfying the zero-alloc constraint.
+    const bulletSprite = {
+      image: atlas.image,
+      frame: bulletFrame,
+      z: 2,
+      width: bulletFrame.w,
+      height: bulletFrame.h,
+      anchor: { x: 0.5, y: 0.5 },
+    };
+    const enemySprite = {
+      image: atlas.image,
+      frame: enemyFrame,
+      z: 0,
+      width: enemyFrame.w,
+      height: enemyFrame.h,
+      anchor: { x: 0.5, y: 0.5 },
+    };
+
+    // ── Create game state (queries registered inside, never per-frame) ─────────
+    const state = createShmupState(ctx.world, bulletSprite, enemySprite);
+
+    // Wire stateRef so the cull callback (registered in setupShmup) can access
+    // the pools.  MUST happen before the first world.step call.
+    stateRef.current = state;
+
+    // ── Per-frame update ──────────────────────────────────────────────────────
+    ctx.loop.onUpdate.add((dt) => {
+      // Keep bounds in sync with the live viewport every frame.
+      // camera.viewportWidth is 0 at onReady (layout not measured yet), so we
+      // update here — pure number writes, no allocation.
+      const vw = ctx.camera.viewportWidth  > 0 ? ctx.camera.viewportWidth  : 400;
+      const vh = ctx.camera.viewportHeight > 0 ? ctx.camera.viewportHeight : 750;
+      bounds.minX = -32;
+      bounds.minY = -64;
+      bounds.maxX = vw + 32;
+      bounds.maxY = vh + 64;
+
+      // 1. Move player in-place from joystick, clamped to the live viewport.
+      const pos = ctx.world.get(player, Position);
+      if (pos !== undefined) {
+        pos.x = Math.max(PLAYER_HALF_W, Math.min(vw - PLAYER_HALF_W, pos.x + dirRef.current.x * PLAYER_SPEED * dt));
+        pos.y = Math.max(PLAYER_HALF_H, Math.min(vh - PLAYER_HALF_H, pos.y + dirRef.current.y * PLAYER_SPEED * dt));
+      }
+
+      // 2. Step world systems: movement integrates velocities, cull removes
+      //    entities that crossed the screen boundary.
+      //    Note: player has no Velocity component, so the movement system
+      //    skips it — the manual move above is the only player integration.
+      ctx.world.step(dt);
+
+      // 3. Game logic: fire bullets, spawn enemies, detect collisions.
+      const kills = stepShmup(ctx.world, state, dt, pos?.x ?? PLAYER_START_X, pos?.y ?? PLAYER_START_Y);
+
+      // Update score only on kills — not every frame — to keep React renders minimal.
+      if (kills > 0) setScore((s) => s + kills);
+    });
+
+    // NOTE: Do NOT call ctx.loop.start() — GameView calls it after onReady returns.
+  }, []); // biome-ignore lint/correctness/useExhaustiveDependencies: intentional mount-only
+
+  const handleJoystick = useCallback((state: VirtualJoystickState): void => {
+    dirRef.current.x = state.direction.x;
+    dirRef.current.y = state.direction.y;
+  }, []);
+
+  return (
+    <SafeAreaProvider>
+      <View style={styles.root}>
+        <GameView config={config} onReady={handleReady} style={styles.game}>
+          {/* Score overlay — updated only on kills, not per-frame */}
+          <Text style={styles.score}>Score: {score}</Text>
+          <VirtualJoystick style={styles.joystick} onStateChange={handleJoystick} />
+        </GameView>
+      </View>
+    </SafeAreaProvider>
+  );
+}
+
+const styles = StyleSheet.create({
+  root:    { flex: 1, backgroundColor: "#000" },
+  game:    { flex: 1 },
+  score:   { position: "absolute", top: 24, right: 24, color: "#fff", fontSize: 18 },
+  joystick:{ position: "absolute", left: 24, bottom: 24 },
+});