@downdraft/cli 0.0.0 → 0.1.1

package/templates/full/README.md.eta

@@ -0,0 +1,45 @@
+# <%= it.name %>
+
+<% if (it.description) { %><%= it.description %><% } else { %>A full-featured game built with the DownDraft Engine.<% } %>
+
+## Getting Started
+
+```bash
+# Install dependencies
+bun install
+
+# Start dev server (includes DevTools panel)
+npm run dev
+
+# Build for production
+npm run build
+
+# Export for distribution
+npm run export
+```
+
+## Project Structure
+
+```
+src/                    Game source code
+  native-entry.ts       Native runtime entry (draft dev)
+  systems/              Game systems (ECS)
+  entities/             Entity definitions and prefabs
+assets/                 Game assets
+  shaders/              Custom WGSL shaders
+  models/               3D models (GLTF, PLY, 3DS)
+  textures/             Textures (PNG, WebP, KTX2, DDS, HDR)
+downdraft.config.json   Engine configuration
+```
+
+## Plugins
+
+- **@downdraft/engine/libraries/water** — Gerstner wave simulation, refraction, reflection
+- **@downdraft/engine/libraries/physics-rapier** — Rapier physics backend
+- **@downdraft/engine/libraries/marching-cubes** — Volumetric deformable terrain
+- **@downdraft/engine/libraries/models** — Model loading (GLTF/GLB, PLY, 3DS)
+- **@downdraft/engine/modules/devtools** — DevTools panel with scene inspector, GPU debugging
+
+## Engine
+
+Built with [DownDraft Engine](https://github.com/downdraft-engine) — a TypeScript-first game engine on WebGPU — native runtime (Bun + SDL + wgpu).

package/templates/full/downdraft.config.json.eta

@@ -0,0 +1,10 @@
+{
+<%~ include("_shared/partials/config-json-fields", it) %>,
+  "plugins": [
+    "physics-rapier",
+    "water",
+    "marching-cubes",
+    "models",
+    "devtools"
+  ]
+}

package/templates/full/package.json.eta

@@ -0,0 +1,9 @@
+{
+  "name": "<%= it.name %>",
+<%~ include("_shared/partials/package-json-fields", it) %>
+  "dependencies": {
+    "@downdraft/engine": "^0.1.0",
+    "@downdraft/platform-native": "^0.1.0"
+  },
+<%~ include("_shared/partials/dev-deps", it) %>
+}

package/templates/full/src/game-module.ts.eta

@@ -0,0 +1,30 @@
+import { GameRenderer } from "@downdraft/engine";
+import type { GameModule } from "@downdraft/engine/app/renderer";
+import { SimHost } from "./sim-host";
+
+// ============================================================================
+// Full template — ECS sim worker + GameRenderer + engine libraries
+//
+// The sim runs in sim-worker.ts (a Web Worker): an ECS World with a rotation
+// system. The SAME module drives both entry points:
+//   src/native-entry.ts — Bun + SDL + wgpu-native (draft dev, the default)
+// Engine libraries can be declared via GameModule.libraries[] for automatic
+// SAB allocation + DI wiring.
+// ============================================================================
+
+export const gameModule: GameModule = {
+  // ── Renderer + Sim ──
+  renderer: (canvas) => new GameRenderer(canvas),
+  sim: () => new SimHost(),
+  simConfig: { seed: 12345 },
+
+  // ── Post-init wiring ──
+  onReady: (ctx) => {
+    console.log("[game] ready", { simSAB: ctx.simSAB, inputSAB: ctx.inputSAB });
+  },
+
+  // ── Cleanup ──
+  onDispose: () => {
+    console.log("[game] disposed");
+  },
+};

package/templates/full/src/native-entry.ts.eta

@@ -0,0 +1,14 @@
+import { runNativeGameModule } from "@downdraft/platform-native";
+import { gameModule } from "./game-module";
+
+// Native entry — `draft dev`/`draft release` runtime (winit + wgpu under Bun, Node, or Deno).
+// Saves, MCP, display info, and screenshots work through the in-process
+// HostAPI bridge.
+
+await runNativeGameModule(gameModule, {
+  title: "<%= it.name %> — Native",
+  appId: "downdraft-<%= it.name %>",
+}).catch((e) => {
+  console.error("[native-entry] Fatal:", e);
+  process.exit(1);
+});

package/templates/full/src/sim-host.ts.eta

@@ -0,0 +1,19 @@
+import { SimWorkerHost } from "@downdraft/engine";
+
+// Sim worker host — spawns sim-worker.ts on the main (renderer) thread and
+// exposes the sim SAB + event stream to startGame().
+export class SimHost extends SimWorkerHost {
+  constructor() {
+    // Replace with your game's sim-buffer allocation (see the SAB APIs in
+    // @downdraft/engine, e.g. defineRecordBuffer/allocateSimBuffer).
+    super(new SharedArrayBuffer(4096));
+  }
+
+  protected createWorker(): Worker {
+    return new Worker(new URL("./sim-worker.ts", import.meta.url), { type: "module" });
+  }
+
+  protected async onInit(): Promise<void> {
+    await this.getProxy()!.proxy.init(this.getSimBuffer());
+  }
+}

package/templates/full/src/sim-worker.ts.eta

@@ -0,0 +1,99 @@
+import {
+  c,
+  Component,
+  createLogger,
+  createSimWorker,
+  Query,
+  q,
+  spawn,
+  Stage,
+  systemWithParams,
+  World,
+} from "@downdraft/engine";
+
+const log = createLogger();
+
+// Full template sim worker — an ECS World with a rotation system.
+// createSimWorker owns the tick loop, worker protocol, and stats;
+// this file provides onInit + onTick.
+
+// --- Components ---
+
+type TransformData = {
+  position: [number, number, number];
+  rotation: [number, number, number];
+  scale: number;
+};
+
+const Transform = Component.register<TransformData>("Transform", {
+  position: [0, 0, 0],
+  rotation: [0, 0, 0],
+  scale: 1,
+});
+
+type RenderableData = {
+  mesh: string;
+  color: [number, number, number];
+};
+
+const Renderable = Component.register<RenderableData>("Renderable", {
+  mesh: "cube",
+  color: [1, 1, 1],
+});
+
+// --- Queries ---
+
+const rotateQuery = new Query([Transform.id, Renderable.id]);
+
+let world: World;
+
+createSimWorker({
+  fixedDt: 1 / 60,
+
+  onInit() {
+    world = new World();
+
+    // Spawn ground entity
+    spawn(world,
+      c(Transform, { position: [0, -0.5, 0], scale: 10 }),
+      c(Renderable, { mesh: "cube", color: [0.3, 0.5, 0.3] }),
+    );
+
+    // Spawn rotating entities
+    for (let i = 0; i < 5; i++) {
+      spawn(world,
+        c(Transform, { position: [(i - 2) * 2, 0.5, 0] }),
+        c(Renderable, {
+          mesh: i % 2 === 0 ? "cube" : "sphere",
+          color: [Math.random(), Math.random(), Math.random()],
+        }),
+      );
+    }
+
+    // Register system using systemWithParams for typed dependency injection
+    const rotateSystem = systemWithParams(
+      "rotate-entities",
+      Stage.Update,
+      [q(Transform, Renderable)],
+      (ctx, entities) => {
+        entities.iterate(ctx.tick, (_entity, comps) => {
+          const transform = comps[0] as TransformData;
+          const [rx, ry, rz] = transform.rotation;
+          transform.rotation = [rx, ry + ctx.dt * 0.5, rz];
+        });
+      },
+    );
+
+    world.schedule.addSystem(rotateSystem);
+
+    log.info("sim", "full demo initialized — 5 entities on a ground plane");
+  },
+
+  onTick(dt) {
+    world.step(dt);
+  },
+
+  onShutdown() {
+    log.info("sim", "sim worker shutdown");
+  },
+});

package/templates/full/tsconfig.json.eta

@@ -0,0 +1 @@
+<%~ include("_shared/partials/tsconfig", it) %>

package/templates/gamemodule/README.md.eta

@@ -0,0 +1,32 @@
+# <%= it.name %>
+
+<% if (it.description) { %><%= it.description %><% } else { %>A game built with the DownDraft Engine.<% } %>
+
+## Getting Started
+
+```bash
+# Install dependencies
+bun install
+
+# Start dev server
+npm run dev
+
+# Build for production
+npm run build
+
+# Export for distribution
+npm run export
+```
+
+## Project Structure
+
+```
+src/          Game source code
+  native-entry.ts  Native runtime entry (draft dev)
+assets/       Game assets (models, textures, shaders)
+downdraft.config.json   Engine configuration
+```
+
+## Engine
+
+Built with [DownDraft Engine](https://github.com/downdraft-engine) — a TypeScript-first game engine on WebGPU — native runtime (Bun + SDL + wgpu).

package/templates/gamemodule/downdraft.config.json.eta

@@ -0,0 +1,3 @@
+{
+<%~ include("_shared/partials/config-json-fields", it) %>
+}

package/templates/gamemodule/package.json.eta

@@ -0,0 +1,9 @@
+{
+  "name": "<%= it.name %>",
+<%~ include("_shared/partials/package-json-fields", it) %>
+  "dependencies": {
+    "@downdraft/engine": "^0.1.0",
+    "@downdraft/platform-native": "^0.1.0"
+  },
+<%~ include("_shared/partials/dev-deps", it) %>
+}

package/templates/gamemodule/src/game-module.ts.eta

@@ -0,0 +1,63 @@
+import { GameRenderer } from "@downdraft/engine";
+import type { GameModule, SimWorkerSeed } from "@downdraft/engine/app/renderer";
+import { WaterLib } from "@downdraft/engine/libraries/water";
+import { SimHost } from "./sim-host";
+
+// ============================================================================
+// GameModule template — declarative game with libraries + plugins
+//
+// The SAME module drives both entry points:
+//   src/native-entry.ts — Bun + SDL + wgpu-native (draft dev, the default)
+//
+// This template shows the full declarative pattern:
+// - Engine libraries (WaterLib) for SAB allocation + DI tokens
+// - Declarative event routing (events map)
+// - Save config
+// - Game-specific hooks (onReady, onDispose)
+//
+// Feature modules such as @downdraft/engine/modules/terrain can be registered on the
+// renderer's module host inside onReady.
+// ============================================================================
+
+export const gameModule: GameModule = {
+  // ── Engine libraries (declarative SAB allocation + DI tokens) ──
+  libraries: [WaterLib],
+
+  // ── Renderer + Sim ──
+  renderer: (canvas) => new GameRenderer(canvas),
+  sim: (seed?: SimWorkerSeed) => new SimHost(seed?.libraryBuffers),
+  simConfig: { seed: 12345, gamemode: 0, rules: {} },
+
+  // ── Sim→Renderer event routing (declarative) ──
+  events: {
+    ready: (_data, _ctx) => {
+      console.log("[game] Sim ready");
+    },
+    error: (data) => {
+      console.error("[game] Sim error:", data);
+    },
+  },
+
+  // ── Save ──
+  save: {
+    mode: "auto",
+    engineVersion: "0.1.0",
+    maxGenerations: 3,
+  },
+
+  // ── Post-init wiring ──
+  onReady: (ctx) => {
+    // Library-allocated SABs are available on ctx.extraBuffers, keyed by the
+    // library descriptor's channel name.
+    console.log("[game] ready", {
+      simSAB: ctx.simSAB,
+      inputSAB: ctx.inputSAB,
+      water: ctx.extraBuffers.water,
+    });
+  },
+
+  // ── Cleanup ──
+  onDispose: () => {
+    console.log("[game] disposed");
+  },
+};

package/templates/gamemodule/src/native-entry.ts.eta

@@ -0,0 +1,14 @@
+import { runNativeGameModule } from "@downdraft/platform-native";
+import { gameModule } from "./game-module";
+
+// Native entry — `draft dev`/`draft release` runtime (winit + wgpu under Bun, Node, or Deno).
+// Saves, MCP, display info, and screenshots work through the in-process
+// HostAPI bridge.
+
+await runNativeGameModule(gameModule, {
+  title: "<%= it.name %> — Native",
+  appId: "downdraft-<%= it.name %>",
+}).catch((e) => {
+  console.error("[native-entry] Fatal:", e);
+  process.exit(1);
+});

package/templates/gamemodule/src/sim-host.ts.eta

@@ -0,0 +1,25 @@
+import { SimWorkerHost } from "@downdraft/engine";
+
+// Sim worker host — spawns sim-worker.ts on the main (renderer) thread and
+// exposes the sim SAB + event stream to startGame().
+//
+// `libraryBuffers` are the SABs allocated by EngineLibrary descriptors in
+// GameModule.libraries[] — forwarded to the worker via the init RPC.
+export class SimHost extends SimWorkerHost {
+  private libraryBuffers?: Record<string, SharedArrayBuffer>;
+
+  constructor(libraryBuffers?: Record<string, SharedArrayBuffer>) {
+    // Replace with your game's sim-buffer allocation (see the SAB APIs in
+    // @downdraft/engine, e.g. defineRecordBuffer/allocateSimBuffer).
+    super(new SharedArrayBuffer(4096));
+    this.libraryBuffers = libraryBuffers;
+  }
+
+  protected createWorker(): Worker {
+    return new Worker(new URL("./sim-worker.ts", import.meta.url), { type: "module" });
+  }
+
+  protected async onInit(): Promise<void> {
+    await this.getProxy()!.proxy.init(this.getSimBuffer(), this.libraryBuffers);
+  }
+}

package/templates/gamemodule/src/sim-worker.ts.eta

@@ -0,0 +1,24 @@
+import { createSimWorker } from "@downdraft/engine";
+
+// Sim worker — runs the fixed-timestep simulation loop in a Web Worker.
+// createSimWorker handles the tick loop, pause/resume/step control, stats,
+// and the "ready" event; you provide onInit + onTick.
+//
+// The init RPC args sent by SimHost arrive after `control`:
+//   proxy.init(simBuffer, libraryBuffers) → onInit(sab, control, libraryBuffers)
+createSimWorker({
+  fixedDt: 1 / 60,
+
+  onInit(sab, _control, libraryBuffers?: Record<string, SharedArrayBuffer>) {
+    // `sab` is the sim state buffer shared with the renderer.
+    // `libraryBuffers` are the SABs allocated by your EngineLibrary
+    // descriptors (e.g. WaterLib's water channel) — wire them into your sim.
+    void sab;
+    void libraryBuffers;
+  },
+
+  onTick(dt, _ctx) {
+    // Step your simulation here. `dt` equals fixedDt.
+    void dt;
+  },
+});

package/templates/gamemodule/tsconfig.json.eta

@@ -0,0 +1 @@
+<%~ include("_shared/partials/tsconfig", it) %>

package/templates/minimal/.gitignore.eta

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+export/
+*.log
+.DS_Store

package/templates/minimal/.vscode/extensions.json.eta

@@ -0,0 +1 @@
+<%~ include("_shared/partials/vscode-extensions", it) %>

package/templates/minimal/.vscode/settings.json.eta

@@ -0,0 +1 @@
+<%~ include("_shared/partials/vscode-settings", it) %>

package/templates/minimal/.vscode/tasks.json.eta

@@ -0,0 +1 @@
+<%~ include("_shared/partials/vscode-tasks", it) %>

package/templates/minimal/README.md.eta

@@ -0,0 +1,32 @@
+# <%= it.name %>
+
+<% if (it.description) { %><%= it.description %><% } else { %>A game built with the DownDraft Engine.<% } %>
+
+## Getting Started
+
+```bash
+# Install dependencies
+bun install
+
+# Start dev server
+npm run dev
+
+# Build for production
+npm run build
+
+# Export for distribution
+npm run export
+```
+
+## Project Structure
+
+```
+src/          Game source code
+  native-entry.ts  Native runtime entry (draft dev)
+assets/       Game assets (models, textures, shaders)
+downdraft.config.json   Engine configuration
+```
+
+## Engine
+
+Built with [DownDraft Engine](https://github.com/downdraft-engine) — a TypeScript-first game engine on WebGPU — native runtime (Bun + SDL + wgpu).

package/templates/minimal/downdraft.config.json.eta

@@ -0,0 +1,3 @@
+{
+<%~ include("_shared/partials/config-json-fields", it) %>
+}

package/templates/minimal/package.json.eta

@@ -0,0 +1,9 @@
+{
+  "name": "<%= it.name %>",
+<%~ include("_shared/partials/package-json-fields", it) %>
+  "dependencies": {
+    "@downdraft/engine": "^0.1.0",
+    "@downdraft/platform-native": "^0.1.0"
+  },
+<%~ include("_shared/partials/dev-deps", it) %>
+}

package/templates/minimal/src/game-module.ts.eta

@@ -0,0 +1,44 @@
+import type { GameModule } from "@downdraft/engine/app/renderer";
+
+// ============================================================================
+// Minimal game template — declarative GameModule
+//
+// The SAME module drives both entry points:
+//   src/native-entry.ts — Bun + SDL + wgpu-native (draft dev, the default)
+//
+// For a more complete example with WebGPU rendering, sim worker, and
+// libraries, see the "full" template (`draft init --template full`).
+// ============================================================================
+
+export const gameModule: GameModule = {
+  // Renderer factory — creates the renderer from a canvas element
+  renderer: (canvas) => ({
+    async init() { return true; },
+    setBuffers() {},
+    setupInputListeners() {},
+    render() {},
+    stop() {},
+    getFPS() { return 0; },
+  }),
+
+  // Sim worker factory — creates the sim worker
+  sim: () => ({
+    async start(_config: unknown) {},
+    onEvent(_cb: (msg: any) => void) {},
+    getSimBuffer() { return new SharedArrayBuffer(1024); },
+    getInputBuffer() { return new SharedArrayBuffer(1024); },
+  }),
+
+  // Sim config (passed to sim.start())
+  simConfig: { seed: 12345 },
+
+  // Post-init wiring — called after renderer init + sim start
+  onReady: (ctx) => {
+    console.log("[game] ready", { sim: ctx.sim, renderer: ctx.renderer });
+  },
+
+  // Cleanup — called on hot-reload dispose
+  onDispose: () => {
+    console.log("[game] disposed");
+  },
+};

package/templates/minimal/src/native-entry.ts.eta

@@ -0,0 +1,14 @@
+import { runNativeGameModule } from "@downdraft/platform-native";
+import { gameModule } from "./game-module";
+
+// Native entry — `draft dev`/`draft release` runtime (winit + wgpu under Bun, Node, or Deno).
+// Saves, MCP, display info, and screenshots work through the in-process
+// HostAPI bridge.
+
+await runNativeGameModule(gameModule, {
+  title: "<%= it.name %> — Native",
+  appId: "downdraft-<%= it.name %>",
+}).catch((e) => {
+  console.error("[native-entry] Fatal:", e);
+  process.exit(1);
+});

package/templates/minimal/tsconfig.json.eta

@@ -0,0 +1 @@
+<%~ include("_shared/partials/tsconfig", it) %>

package/templates/physics/.gitignore.eta

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+export/
+*.log
+.DS_Store

package/templates/physics/.vscode/extensions.json.eta

@@ -0,0 +1 @@
+<%~ include("_shared/partials/vscode-extensions", it) %>

package/templates/physics/.vscode/settings.json.eta

@@ -0,0 +1 @@
+<%~ include("_shared/partials/vscode-settings", it) %>

package/templates/physics/.vscode/tasks.json.eta

@@ -0,0 +1 @@
+<%~ include("_shared/partials/vscode-tasks", it) %>

package/templates/physics/README.md.eta

@@ -0,0 +1,36 @@
+# <%= it.name %>
+
+<% if (it.description) { %><%= it.description %><% } else { %>A physics-based game built with the DownDraft Engine.<% } %>
+
+## Getting Started
+
+```bash
+# Install dependencies
+bun install
+
+# Start dev server
+npm run dev
+
+# Build for production
+npm run build
+
+# Export for distribution
+npm run export
+```
+
+## Project Structure
+
+```
+src/          Game source code
+  native-entry.ts  Native runtime entry (draft dev)
+assets/       Game assets (models, textures, shaders)
+downdraft.config.json   Engine configuration (physics-rapier plugin enabled)
+```
+
+## Plugins
+
+- **@downdraft/engine/libraries/physics-rapier** — Rapier physics backend for rigid body simulation, colliders, and raycasting.
+
+## Engine
+
+Built with [DownDraft Engine](https://github.com/downdraft-engine) — a TypeScript-first game engine on WebGPU — native runtime (Bun + SDL + wgpu).

package/templates/physics/downdraft.config.json.eta

@@ -0,0 +1,6 @@
+{
+<%~ include("_shared/partials/config-json-fields", it) %>,
+  "plugins": [
+    "physics-rapier"
+  ]
+}

package/templates/physics/package.json.eta

@@ -0,0 +1,9 @@
+{
+  "name": "<%= it.name %>",
+<%~ include("_shared/partials/package-json-fields", it) %>
+  "dependencies": {
+    "@downdraft/engine": "^0.1.0",
+    "@downdraft/platform-native": "^0.1.0"
+  },
+<%~ include("_shared/partials/dev-deps", it) %>
+}

package/templates/physics/src/game-module.ts.eta

@@ -0,0 +1,29 @@
+import { GameRenderer } from "@downdraft/engine";
+import type { GameModule } from "@downdraft/engine/app/renderer";
+import { SimHost } from "./sim-host";
+
+// ============================================================================
+// Physics template — ECS sim worker + GameRenderer
+//
+// The sim runs in sim-worker.ts (a Web Worker): an ECS World with gravity and
+// integration systems that spawns falling shapes. The SAME module drives
+// both entry points:
+//   src/native-entry.ts — Bun + SDL + wgpu-native (draft dev, the default)
+// ============================================================================
+
+export const gameModule: GameModule = {
+  // ── Renderer + Sim ──
+  renderer: (canvas) => new GameRenderer(canvas),
+  sim: () => new SimHost(),
+  simConfig: { seed: 12345 },
+
+  // ── Post-init wiring ──
+  onReady: (ctx) => {
+    console.log("[game] ready", { simSAB: ctx.simSAB, inputSAB: ctx.inputSAB });
+  },
+
+  // ── Cleanup ──
+  onDispose: () => {
+    console.log("[game] disposed");
+  },
+};