@downdraft/cli 0.0.0 → 0.1.0

package/templates/_shared/ai-companion/engine-prompt.eta

@@ -0,0 +1,155 @@
+# DownDraft Engine — API Reference for AI Companions
+
+## Architecture
+
+DownDraft is a TypeScript-first game engine built on winit + wgpu (a single native process, hosted under Bun, Node, or Deno — Bun is the default) + WebGPU, with an MCP server enabling AI agents to design, build, debug, and manage games via natural language.
+
+**Execution contexts:**
+1. **Native host (main thread)** — Game module, renderer, render loop, engine orchestrator, MCP server, asset manager
+2. **Sim worker** — ECS world, game systems, physics, AI, modules (SharedArrayBuffer channels for frame sync)
+3. **DB worker** — Persistence layer with schema versioning
+
+## ECS (Entity Component System)
+
+- **Entity**: `{ index: u32, generation: u32 }` — generational indices prevent stale-handle corruption
+- **Component**: Plain data class implementing `Component` interface, registered with `ComponentId`
+- **Archetype**: Set of component types, SoA column storage for cache-friendly iteration
+- **Query**: Declares read/write access to component types, returns matching archetypes
+- **System**: Function `(query, resources, commands) => void`
+- **Schedule**: Single-threaded by default, dependency-ordered. Multi-threading via module/SAB.
+- **Events**: Double-buffered channels (written this tick, readable next tick)
+- **Commands**: Deferred operations (spawn/despawn, add/remove component) applied at stage boundaries
+
+### Hierarchy
+- Parent/child tree stored in side table (not archetype columns) — avoids archetype moves on reparenting
+- Dirty-flag propagation: parent Transform change marks children dirty (O(depth))
+- Lazy world matrix: computed on read when dirty
+
+### Change Detection
+- Per-component `lastChanged` tick counter — O(1) check for consumers
+- Cross-thread: `Atomics` on SAB headers for frame sync
+
+## Core API
+
+```typescript
+import { World, Camera, MeshBuilder, Component, system, createLogger } from "@downdraft/engine";
+
+// Define components
+const Health = Component.register<{ current: number; max: number }>("Health", { current: 100, max: 100 });
+
+// Define a system
+const damageSystem = system(
+  (w: World, dt: number) => {
+    const view = w.view([Health]);
+    for (const ent of view) {
+      const health = w.getComponent(ent, Health);
+      if (health && health.data.current <= 0) {
+        w.despawn(ent);
+      }
+    }
+  }
+);
+
+// Setup
+const world = new World();
+const camera = new Camera();
+camera.setAspect(16, 9);
+world.setResource("camera", camera);
+
+// Spawn entities
+const entity = world.spawn();
+world.addComponent(entity, Health.create({ current: 50, max: 100 }));
+
+// Procedural meshes
+const cube = MeshBuilder.cube(1);
+const sphere = MeshBuilder.sphere(0.5, 16, 16);
+```
+
+## Module System
+
+Modules are loadable packages that register systems, components, resources, and assets.
+
+```typescript
+import { Module } from "@downdraft/engine";
+
+const myModule: Module = {
+  name: "my-module",
+  register(ctx: ModuleContext) {
+    // Register components, systems, resources
+  },
+};
+
+world.registerModule(myModule);
+```
+
+### Engine Libraries (`@downdraft/engine/libraries/*`)
+- `@downdraft/engine/libraries/water` — Gerstner waves, refraction, reflection
+- `@downdraft/engine/libraries/physics-rapier` — Rapier physics backend
+- `@downdraft/engine/libraries/physics-native` — Pure-TS physics backend
+- `@downdraft/engine/libraries/marching-cubes` — Volumetric deformable terrain
+- `@downdraft/engine/libraries/surface-nets` — Surface nets mesh extraction
+- `@downdraft/engine/libraries/models` — GLTF/GLB/PLY/3DS model loading
+- `@downdraft/engine/libraries/audio-kira` — Kira audio backend
+- `@downdraft/engine/libraries/entities` — Generic model renderer
+- `@downdraft/engine/libraries/lighting` — Lighting system
+- `@downdraft/engine/libraries/weather` — Weather simulation
+- `@downdraft/engine/libraries/weatherfx` — Cloud particle effects
+- `@downdraft/engine/libraries/navmesh` — Navigation meshes
+- `@downdraft/engine/libraries/persistence` — Save system (OPFS, File, IndexedDB)
+- `@downdraft/engine/libraries/networking` — Multiplayer networking
+- `@downdraft/engine/libraries/gaussian-splats` — Gaussian splat rendering
+- `@downdraft/engine/libraries/sand` — Falling-sand simulation
+- `@downdraft/engine/libraries/stickman` — Stickman skeleton rendering
+
+### Engine Modules (`@downdraft/engine/modules/*`)
+- `@downdraft/engine/modules/devtools` — DevTools panel, scene inspector, GPU debugging
+- `@downdraft/engine/modules/camera-controls` — Camera input handling
+- `@downdraft/engine/modules/terrain` — Terrain composition (marching-cubes + LOD)
+- `@downdraft/engine/modules/movement-3d` — 3D player movement
+- `@downdraft/engine/modules/movement-2d` — 2D grid-based movement
+- `@downdraft/engine/modules/sailing` — Sailing mechanics (wind, buoyancy, steering)
+- `@downdraft/engine/modules/mcp` — MCP automation server
+- `@downdraft/engine/modules/xr` — WebXR support
+
+### Game Modules (to-the-ocean example: `@to-the-ocean/module-*`)
+- `@to-the-ocean/module-crafting` — Crafting recipes and system
+- `@to-the-ocean/module-inventory` — Inventory system
+- `@to-the-ocean/module-wildlife` — Wildlife AI (fish, sharks, eels, etc.)
+- `@to-the-ocean/module-buoyancy` — Water buoyancy physics
+- `@to-the-ocean/module-collision` — Entity collision detection
+
+### Game Libraries (to-the-ocean example: `@to-the-ocean/library-*`)
+- `@to-the-ocean/library-items` — Item definitions and management
+- `@to-the-ocean/library-fishing` — Fishing mechanics
+- `@to-the-ocean/library-economy` — Market/trading system
+- `@to-the-ocean/library-survival` — Survival stats (hunger, thirst, oxygen)
+- `@to-the-ocean/library-boats` — Boat building and piloting
+
+## Builder Modes
+
+| Mode | Use case |
+|---|---|
+| **dev** | Full DevTools, hot-reload, telemetry. Fastest iteration. |
+| **debug** | Local verification on the production native runtime. |
+| **prod** | Optimized production build. No devtools/debug overhead. |
+
+## CLI Commands
+
+```
+draft new [path] [options]      Scaffold a new game project
+draft dev [options]             Start dev server with HMR
+draft debug [options]           Run engine in debug mode
+draft release [options]         Unified build + package + sign pipeline
+                                (--stage=build|package|release, --target=win|linux|mac|all)
+draft assets <cmd>              Manage remote asset packs
+```
+
+## MCP Tools (for AI agents)
+
+The MCP server exposes tools for scene management, entity operations, component manipulation, material/shader editing, mesh import, animation, lighting, camera, physics, audio, scripting, asset management, debugging, checkpoints, and build/export.
+
+## Conventions
+
+- **Logging**: No manual `[module]` prefixes — automatic source attribution
+- **Loops**: Prefer indexed `for` loops over `for..of`
+- **Package manager**: Bun (workspace protocol for internal deps)

package/templates/_shared/ai-companion/logging-rule.eta

@@ -0,0 +1,3 @@
+# Logging Convention
+
+Logs are automatically sourced to the line from which they are printed. Do NOT manually add `[module]` prefixes to log messages — the logging system handles source attribution automatically.

package/templates/_shared/ai-companion/loops-rule.eta

@@ -0,0 +1,3 @@
+# Loop Convention
+
+Always prefer indexed `for` loops (`for (let i = 0; i < arr.length; i++)`) over `for..of` loops.

package/templates/_shared/partials/config-json-fields.eta

@@ -0,0 +1,3 @@
+  "name": "<%= it.name %>",
+  "version": "<%= it.version %>",
+  "engine": "downdraft"

package/templates/_shared/partials/dev-deps.eta

@@ -0,0 +1,8 @@
+  "devDependencies": {
+    "@downdraft/cli": "^0.1.0",
+    "@types/node": "^22.10.0",
+    "@webgpu/types": "^0.1.71",
+    "oxlint": "^1.4.0",
+    "typescript": "^5.9.3",
+    "vite": "^6.0.0"
+  }

package/templates/_shared/partials/package-json-fields.eta

@@ -0,0 +1,12 @@
+  "version": "<%= it.version %>",<% if (it.description) { %>
+  "description": "<%= it.description %>",<% } %><% if (it.author) { %>
+  "author": { "name": "<%= it.author %>" },<% } %>
+  "type": "module",
+  "scripts": {
+    "dev": "draft dev",
+    "build": "draft release --stage=build",
+    "release": "draft release",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint",
+    "test": "npm test"
+  },

package/templates/_shared/partials/tsconfig.eta

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "types": ["@webgpu/types", "node", "vite/client"],
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true
+  },
+  "include": ["src"]
+}

package/templates/_shared/partials/vscode-extensions.eta

@@ -0,0 +1,11 @@
+{
+  "recommendations": [
+    "antaalt.shader-validator",
+    "PKief.material-icon-theme",
+    "actboy168.tasks",
+    "Gruntfuggly.todo-tree",
+    "augustocdias.tasks-shell-input",
+    "oxc.oxc-vscode",
+    "wgsl-analyzer.wgsl-analyzer"
+  ]
+}

package/templates/_shared/partials/vscode-settings.eta

@@ -0,0 +1,29 @@
+{
+  "explorer.fileNesting.enabled": true,
+  "explorer.fileNesting.expand": false,
+  "explorer.fileNesting.patterns": {
+    "*.ts": "${capture}.js, ${capture}.spec.ts, ${capture}.*.spec.ts, ${capture}.test.ts",
+    "*.tsx": "${capture}.spec.ts, ${capture}.*.spec.ts, ${capture}.test.ts",
+    "*.js": "${capture}.js.map, ${capture}.min.js, ${capture}.d.ts, ${capture}.wasm, ${capture}.wasm.map",
+    "tsconfig.json": "tsconfig.*.json",
+    "package.json": "package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lock"
+  },
+  "editor.codeActionsOnSave": {
+    "source.organizeImports": "explicit"
+  },
+  "files.associations": {
+    "*.wgsl": "wgsl"
+  },
+  "files.watcherExclude": {
+    "**/node_modules/**": true,
+    "**/dist/**": true,
+    "**/export/**": true,
+    "**/tmp/**": true
+  },
+  "search.exclude": {
+    "**/node_modules/**": true,
+    "**/dist/**": true,
+    "**/export/**": true,
+    "**/tmp/**": true
+  }
+}

package/templates/_shared/partials/vscode-tasks.eta

@@ -0,0 +1,93 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "Dev",
+      "detail": "Start the game in dev mode with hot reload",
+      "type": "shell",
+      "command": "draft dev",
+      "options": {
+        "cwd": "${workspaceFolder}"
+      },
+      "isBackground": true,
+      "problemMatcher": [],
+      "group": {
+        "kind": "build",
+        "isDefault": true
+      }
+    },
+    {
+      "label": "Release",
+      "detail": "Build + package for a desktop target",
+      "type": "shell",
+      "command": "draft release --target=${input:releaseTarget} --mode=${input:buildMode}",
+      "options": {
+        "cwd": "${workspaceFolder}"
+      },
+      "presentation": {
+        "echo": true,
+        "reveal": "always",
+        "panel": "dedicated",
+        "clear": true,
+        "showReuseMessage": false
+      },
+      "problemMatcher": []
+    },
+    {
+      "label": "Build Only",
+      "detail": "Bundle the game with Vite (no packaging)",
+      "type": "shell",
+      "command": "draft release --stage=build --mode=${input:buildMode}",
+      "options": {
+        "cwd": "${workspaceFolder}"
+      },
+      "problemMatcher": []
+    },
+    {
+      "label": "Typecheck",
+      "detail": "Run tsc --noEmit",
+      "type": "shell",
+      "command": "npm run typecheck",
+      "options": {
+        "cwd": "${workspaceFolder}"
+      },
+      "problemMatcher": ["$tsc"]
+    },
+    {
+      "label": "Lint",
+      "detail": "Run oxlint",
+      "type": "shell",
+      "command": "npm run lint",
+      "options": {
+        "cwd": "${workspaceFolder}"
+      },
+      "problemMatcher": []
+    },
+    {
+      "label": "Test",
+      "detail": "Run tests",
+      "type": "shell",
+      "command": "npm test",
+      "options": {
+        "cwd": "${workspaceFolder}"
+      },
+      "problemMatcher": []
+    }
+  ],
+  "inputs": [
+    {
+      "id": "releaseTarget",
+      "type": "pickString",
+      "options": ["all", "win", "linux", "mac"],
+      "default": "all",
+      "description": "Target platform(s)"
+    },
+    {
+      "id": "buildMode",
+      "type": "pickString",
+      "options": ["prod", "dev", "debug"],
+      "default": "prod",
+      "description": "Build mode"
+    }
+  ]
+}

package/templates/full/.gitignore.eta

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

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

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

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

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

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

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

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) %>
+}