@downdraft/cli 0.0.0 → 0.1.0

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");
+  },
+};

package/templates/physics/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/physics/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/physics/src/sim-worker.ts.eta

@@ -0,0 +1,155 @@
+import {
+  c,
+  Collider,
+  Component,
+  createBoxCollider,
+  createLogger,
+  createSimWorker,
+  createSphereCollider,
+  PhysicsTransform,
+  Query,
+  RigidBody,
+  spawn,
+  Stage,
+  system,
+  Velocity,
+  World,
+} from "@downdraft/engine";
+
+const log = createLogger();
+
+// Physics demo sim worker — an ECS World with gravity + integration systems
+// that spawns falling shapes. createSimWorker owns the tick loop, worker
+// protocol, and stats; this file provides onInit + onTick.
+
+type PhysicsBodyData = {
+  bodyType: "dynamic" | "static" | "kinematic";
+  mass: number;
+  restitution: number;
+  friction: number;
+};
+
+const PhysicsBody = Component.register<PhysicsBodyData>("PhysicsBody", {
+  bodyType: "dynamic",
+  mass: 1,
+  restitution: 0.4,
+  friction: 0.5,
+});
+
+type FallingShapeData = {
+  shape: "box" | "sphere";
+  size: number;
+  color: [number, number, number];
+};
+
+const FallingShape = Component.register<FallingShapeData>("FallingShape", {
+  shape: "box",
+  size: 1,
+  color: [1, 1, 1],
+});
+
+const gravityQuery = new Query([RigidBody.id, Velocity.id, PhysicsTransform.id]);
+
+let world: World;
+let spawnTimer = 0;
+
+createSimWorker({
+  fixedDt: 1 / 60,
+
+  onInit() {
+    world = new World();
+
+    // Ground entity — static body that shapes bounce on.
+    spawn(world,
+      c(PhysicsBody, { bodyType: "static", mass: 0, restitution: 0.3, friction: 0.8 }),
+      c(Collider, createBoxCollider([10, 0.5, 10])),
+      c(PhysicsTransform, { position: [0, -1, 0] }),
+      c(FallingShape, { shape: "box", size: 20, color: [0.3, 0.5, 0.3] }),
+    );
+
+    world.schedule.addSystem(system(
+      "physics-gravity", Stage.Update,
+      (ctx) => {
+        gravityQuery.iterate(ctx.tick, (_ent, comps) => {
+          const body = comps[0] as any;
+          const vel = comps[1] as any;
+          if (body && vel && body.bodyType === "dynamic") {
+            vel.linear[1] -= 9.81 * ctx.dt * (body.gravityScale as number);
+          }
+        });
+      },
+      { queries: [gravityQuery] },
+    ));
+
+    world.schedule.addSystem(system(
+      "physics-integrate", Stage.Update,
+      (ctx) => {
+        gravityQuery.iterate(ctx.tick, (ent, comps) => {
+          const body = comps[0] as any;
+          const vel = comps[1] as any;
+          const transform = comps[2] as any;
+          if (body && vel && transform && body.bodyType === "dynamic") {
+            const [vx, vy, vz] = vel.linear as [number, number, number];
+            const [px, py, pz] = transform.position as [number, number, number];
+            const newPy = py + vy * ctx.dt;
+            transform.position = [px + vx * ctx.dt, newPy, pz + vz * ctx.dt];
+
+            if (newPy < -10) {
+              world.despawn(ent);
+            }
+          }
+        });
+      },
+      { queries: [gravityQuery] },
+    ));
+
+    log.info("sim", "physics demo initialized — shapes will fall and bounce on the ground");
+  },
+
+  onTick(dt) {
+    spawnTimer += dt;
+    if (spawnTimer > 0.5) {
+      spawnTimer = 0;
+      spawnFallingShape();
+    }
+
+    world.step(dt);
+  },
+
+  onShutdown() {
+    log.info("sim", "sim worker shutdown");
+  },
+});
+
+function spawnFallingShape(): void {
+  const isBox = Math.random() > 0.5;
+  const size = 0.5 + Math.random() * 1.5;
+  const x = (Math.random() - 0.5) * 10;
+  const z = (Math.random() - 0.5) * 10;
+
+  spawn(world,
+    c(PhysicsBody, {
+      bodyType: "dynamic",
+      mass: size * size * size,
+      restitution: 0.3 + Math.random() * 0.4,
+      friction: 0.3 + Math.random() * 0.4,
+    }),
+    c(RigidBody, {
+      bodyType: "dynamic",
+      mass: size * size * size,
+      gravityScale: 1,
+    }),
+    c(Velocity, {
+      linear: [(Math.random() - 0.5) * 2, 0, (Math.random() - 0.5) * 2],
+    }),
+    c(PhysicsTransform, { position: [x, 15, z] }),
+    c(Collider, isBox
+      ? createBoxCollider([size / 2, size / 2, size / 2])
+      : createSphereCollider(size * 0.5)),
+    c(FallingShape, {
+      shape: isBox ? "box" : "sphere",
+      size: isBox ? size : size * 0.5,
+      color: [Math.random(), Math.random(), Math.random()],
+    }),
+  );
+}

package/templates/physics/tsconfig.json.eta

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