@donut-games/create-game 0.1.0

package/dist/index.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import path from "path";
+import { fileURLToPath } from "url";
+import { existsSync } from "fs";
+import { initializeProject } from "@donut-games/cli";
+function printUsage() {
+  const usage = [
+    "Usage: npx @donut-games/create-game <targetDirectory> [--2d|--3d] [--skip-install]",
+    "",
+    "Options:",
+    "  --2d            Scaffold a Pixi 2D game (default).",
+    "  --3d            Scaffold a Three.js 3D game.",
+    "  --skip-install  Do not run the post-scaffold dependency install.",
+    "  --help, -h      Show this message."
+  ].join("\n");
+  console.log(usage);
+}
+function resolveTemplateDirectory() {
+  const shippedCandidate = fileURLToPath(new URL("../template", import.meta.url));
+  if (existsSync(shippedCandidate)) {
+    return shippedCandidate;
+  }
+  const devCandidate = fileURLToPath(new URL("../../template", import.meta.url));
+  if (existsSync(devCandidate)) {
+    return devCandidate;
+  }
+  throw new Error(
+    `Unable to locate the create-game template directory. Checked:
+  ${shippedCandidate}
+  ${devCandidate}`
+  );
+}
+function parseCommandLineArguments(rawArguments) {
+  let rendererTarget = "pixi-2d";
+  let skipInstall = false;
+  const positionalArguments = [];
+  for (const argument of rawArguments) {
+    if (argument === "--2d") {
+      rendererTarget = "pixi-2d";
+      continue;
+    }
+    if (argument === "--3d") {
+      rendererTarget = "three-3d";
+      continue;
+    }
+    if (argument === "--skip-install") {
+      skipInstall = true;
+      continue;
+    }
+    if (argument.startsWith("--")) {
+      throw new Error(`Unknown option: ${argument}`);
+    }
+    positionalArguments.push(argument);
+  }
+  if (positionalArguments.length === 0) {
+    throw new Error("Missing <targetDirectory> argument.");
+  }
+  if (positionalArguments.length > 1) {
+    throw new Error(`Unexpected extra arguments: ${positionalArguments.slice(1).join(" ")}`);
+  }
+  return { targetDirectory: positionalArguments[0], rendererTarget, skipInstall };
+}
+async function main() {
+  const rawArguments = process.argv.slice(2);
+  if (rawArguments.includes("--help") || rawArguments.includes("-h") || rawArguments.length === 0) {
+    printUsage();
+    return;
+  }
+  const parsedArguments = parseCommandLineArguments(rawArguments);
+  resolveTemplateDirectory();
+  const absoluteTargetDirectory = path.resolve(parsedArguments.targetDirectory);
+  const projectName = path.basename(absoluteTargetDirectory);
+  await initializeProject({
+    projectName,
+    rendererTarget: parsedArguments.rendererTarget,
+    targetDirectory: absoluteTargetDirectory,
+    skipInstall: parsedArguments.skipInstall
+  });
+}
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`create-game: ${message}`);
+  process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import path from 'node:path';\nimport { fileURLToPath } from 'node:url';\nimport { existsSync } from 'node:fs';\nimport { initializeProject, type RendererTarget } from '@donut-games/cli';\n\n/**\n * Print CLI usage to stdout.\n */\nfunction printUsage(): void {\n  const usage = [\n    'Usage: npx @donut-games/create-game <targetDirectory> [--2d|--3d] [--skip-install]',\n    '',\n    'Options:',\n    '  --2d            Scaffold a Pixi 2D game (default).',\n    '  --3d            Scaffold a Three.js 3D game.',\n    '  --skip-install  Do not run the post-scaffold dependency install.',\n    '  --help, -h      Show this message.',\n  ].join('\\n');\n  console.log(usage);\n}\n\n/**\n * Resolve the `template/` directory that ships alongside this package.\n *\n * Shipped layout places `template/` next to `dist/` in the tarball, so the\n * first candidate works in production. The fallback targets the source-tree\n * layout used when the file is invoked directly out of `src/` during local\n * development (rare, but keeps dev ergonomics predictable).\n */\nfunction resolveTemplateDirectory(): string {\n  const shippedCandidate = fileURLToPath(new URL('../template', import.meta.url));\n  if (existsSync(shippedCandidate)) {\n    return shippedCandidate;\n  }\n  const devCandidate = fileURLToPath(new URL('../../template', import.meta.url));\n  if (existsSync(devCandidate)) {\n    return devCandidate;\n  }\n  throw new Error(\n    `Unable to locate the create-game template directory. Checked:\\n  ${shippedCandidate}\\n  ${devCandidate}`,\n  );\n}\n\n/**\n * Minimal argv parser. Keeps the package dependency-free.\n */\nfunction parseCommandLineArguments(rawArguments: readonly string[]): {\n  readonly targetDirectory: string;\n  readonly rendererTarget: RendererTarget;\n  readonly skipInstall: boolean;\n} {\n  let rendererTarget: RendererTarget = 'pixi-2d';\n  let skipInstall = false;\n  const positionalArguments: string[] = [];\n\n  for (const argument of rawArguments) {\n    if (argument === '--2d') {\n      rendererTarget = 'pixi-2d';\n      continue;\n    }\n    if (argument === '--3d') {\n      rendererTarget = 'three-3d';\n      continue;\n    }\n    if (argument === '--skip-install') {\n      skipInstall = true;\n      continue;\n    }\n    if (argument.startsWith('--')) {\n      throw new Error(`Unknown option: ${argument}`);\n    }\n    positionalArguments.push(argument);\n  }\n\n  if (positionalArguments.length === 0) {\n    throw new Error('Missing <targetDirectory> argument.');\n  }\n  if (positionalArguments.length > 1) {\n    throw new Error(`Unexpected extra arguments: ${positionalArguments.slice(1).join(' ')}`);\n  }\n\n  return { targetDirectory: positionalArguments[0], rendererTarget, skipInstall };\n}\n\n/**\n * Entry point. Parses argv, resolves the template directory, and delegates to\n * `initializeProject` from `@donut-games/cli`.\n */\nasync function main(): Promise<void> {\n  const rawArguments = process.argv.slice(2);\n  if (rawArguments.includes('--help') || rawArguments.includes('-h') || rawArguments.length === 0) {\n    printUsage();\n    return;\n  }\n\n  const parsedArguments = parseCommandLineArguments(rawArguments);\n  // Template directory is resolved so step 5 can wire it into the copier.\n  // Step 4's initializeProject still renders files via its internal functions.\n  resolveTemplateDirectory();\n\n  const absoluteTargetDirectory = path.resolve(parsedArguments.targetDirectory);\n  const projectName = path.basename(absoluteTargetDirectory);\n\n  await initializeProject({\n    projectName,\n    rendererTarget: parsedArguments.rendererTarget,\n    targetDirectory: absoluteTargetDirectory,\n    skipInstall: parsedArguments.skipInstall,\n  });\n}\n\nmain().catch((error: unknown) => {\n  const message = error instanceof Error ? error.message : String(error);\n  console.error(`create-game: ${message}`);\n  process.exit(1);\n});\n"],"mappings":";;;AAAA,OAAO,UAAU;AACjB,SAAS,qBAAqB;AAC9B,SAAS,kBAAkB;AAC3B,SAAS,yBAA8C;AAKvD,SAAS,aAAmB;AAC1B,QAAM,QAAQ;AAAA,IACZ;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF,EAAE,KAAK,IAAI;AACX,UAAQ,IAAI,KAAK;AACnB;AAUA,SAAS,2BAAmC;AAC1C,QAAM,mBAAmB,cAAc,IAAI,IAAI,eAAe,YAAY,GAAG,CAAC;AAC9E,MAAI,WAAW,gBAAgB,GAAG;AAChC,WAAO;AAAA,EACT;AACA,QAAM,eAAe,cAAc,IAAI,IAAI,kBAAkB,YAAY,GAAG,CAAC;AAC7E,MAAI,WAAW,YAAY,GAAG;AAC5B,WAAO;AAAA,EACT;AACA,QAAM,IAAI;AAAA,IACR;AAAA,IAAoE,gBAAgB;AAAA,IAAO,YAAY;AAAA,EACzG;AACF;AAKA,SAAS,0BAA0B,cAIjC;AACA,MAAI,iBAAiC;AACrC,MAAI,cAAc;AAClB,QAAM,sBAAgC,CAAC;AAEvC,aAAW,YAAY,cAAc;AACnC,QAAI,aAAa,QAAQ;AACvB,uBAAiB;AACjB;AAAA,IACF;AACA,QAAI,aAAa,QAAQ;AACvB,uBAAiB;AACjB;AAAA,IACF;AACA,QAAI,aAAa,kBAAkB;AACjC,oBAAc;AACd;AAAA,IACF;AACA,QAAI,SAAS,WAAW,IAAI,GAAG;AAC7B,YAAM,IAAI,MAAM,mBAAmB,QAAQ,EAAE;AAAA,IAC/C;AACA,wBAAoB,KAAK,QAAQ;AAAA,EACnC;AAEA,MAAI,oBAAoB,WAAW,GAAG;AACpC,UAAM,IAAI,MAAM,qCAAqC;AAAA,EACvD;AACA,MAAI,oBAAoB,SAAS,GAAG;AAClC,UAAM,IAAI,MAAM,+BAA+B,oBAAoB,MAAM,CAAC,EAAE,KAAK,GAAG,CAAC,EAAE;AAAA,EACzF;AAEA,SAAO,EAAE,iBAAiB,oBAAoB,CAAC,GAAG,gBAAgB,YAAY;AAChF;AAMA,eAAe,OAAsB;AACnC,QAAM,eAAe,QAAQ,KAAK,MAAM,CAAC;AACzC,MAAI,aAAa,SAAS,QAAQ,KAAK,aAAa,SAAS,IAAI,KAAK,aAAa,WAAW,GAAG;AAC/F,eAAW;AACX;AAAA,EACF;AAEA,QAAM,kBAAkB,0BAA0B,YAAY;AAG9D,2BAAyB;AAEzB,QAAM,0BAA0B,KAAK,QAAQ,gBAAgB,eAAe;AAC5E,QAAM,cAAc,KAAK,SAAS,uBAAuB;AAEzD,QAAM,kBAAkB;AAAA,IACtB;AAAA,IACA,gBAAgB,gBAAgB;AAAA,IAChC,iBAAiB;AAAA,IACjB,aAAa,gBAAgB;AAAA,EAC/B,CAAC;AACH;AAEA,KAAK,EAAE,MAAM,CAAC,UAAmB;AAC/B,QAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AACrE,UAAQ,MAAM,gBAAgB,OAAO,EAAE;AACvC,UAAQ,KAAK,CAAC;AAChB,CAAC;","names":[]}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@donut-games/create-game",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "create-game": "./dist/index.js"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "template",
+    "README.md"
+  ],
+  "dependencies": {
+    "@donut-games/cli": "0.1.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.0",
+    "typescript": "^5.7.0",
+    "@types/node": "^20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup && chmod +x dist/index.js",
+    "clean": "rm -rf dist"
+  }
+}

package/template/base/.donut/mcp-config.json

@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "tools": []
+}

package/template/base/README.md.tpl

@@ -0,0 +1,70 @@
+# {{projectName}}
+
+A Donut game. Two ways to build it: on your own, or with Claude.
+
+## Quick reference
+
+| Command            | What it does                                         |
+| ------------------ | ---------------------------------------------------- |
+| `npm run dev`      | Start the dev server with HMR on http://localhost:5173 |
+| `npm run validate` | Type-check, manifest-check, import-graph check       |
+| `npm run build`    | Produce `dist/{{projectName}}-<version>.donut`       |
+| `npm run review`   | Run the Donut submission review pipeline             |
+
+## Track 1 — Code it yourself
+
+Edit files under `src/`. Vite reloads on save.
+
+- `src/components/` — pure data. Import only from
+  `@donut-games/engine/core` and `@donut-games/engine/math`.
+- `src/systems/` — behavior. Same import restriction as components.
+- `src/scenes/default-scene.ts` — wires entities together. This is
+  the only place renderer-specific imports
+  (`@donut-games/engine/pixi` or `@donut-games/engine/three`) are
+  allowed.
+
+Run `npm run validate` before every commit. It fails if:
+
+- `donut.json` is missing a field.
+- A component or system imports from a renderer subpath.
+- A file imports the wrong renderer for this project's
+  `rendererTarget`.
+
+## Track 2 — Author with Claude
+
+This project ships a Donut MCP server. Install the CLI globally once:
+
+```bash
+npm install -g @donut-games/cli
+claude mcp add donut -- donut-mcp
+```
+
+Then start Claude Code from this directory. Leave `npm run dev`
+running in a second terminal (Claude can also start it itself as a
+background task). Ask for what you want:
+
+> Add an enemy that spawns every three seconds and chases the player.
+
+Claude has four tool categories through the MCP:
+
+- **component-system** — create, edit, delete components and systems.
+- **entity-scene** — edit the scene graph and default scene.
+- **quality** — type-check, lint, validate imports.
+- **runtime** — inspect the running game, send synthetic input,
+  read logs.
+
+Claude is subject to the same import rules as you. Game logic may
+only import from `@donut-games/engine/core` and
+`@donut-games/engine/math`. The MCP enforces this before writing.
+
+## Renderer target
+
+This project targets `{{rendererTarget}}`. Switching targets means
+changing `donut.json`, swapping the installed renderer dependency
+(`pixi.js` ↔ `three`), and updating every
+`@donut-games/engine/pixi` or `@donut-games/engine/three` import
+under `src/scenes/`.
+
+## Docs
+
+https://donut.games/docs

package/template/base/_eslintrc.json

@@ -0,0 +1,33 @@
+{
+  "root": true,
+  "parser": "@typescript-eslint/parser",
+  "plugins": [
+    "@typescript-eslint",
+    "import"
+  ],
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended",
+    "plugin:import/recommended",
+    "plugin:import/typescript"
+  ],
+  "rules": {
+    "no-console": "warn",
+    "@typescript-eslint/no-unused-vars": "error",
+    "@typescript-eslint/no-explicit-any": "warn",
+    "import/order": [
+      "warn",
+      {
+        "groups": [
+          "builtin",
+          "external",
+          "internal",
+          "parent",
+          "sibling",
+          "index"
+        ],
+        "newlines-between": "always"
+      }
+    ]
+  }
+}

package/template/base/src/components/example-component.ts

@@ -0,0 +1,27 @@
+import { Component } from '@donut-games/engine/core';
+
+/**
+ * Example component demonstrating the minimal shape required by Donut.
+ * Components hold state only; no renderer imports are allowed here.
+ */
+export class ExampleComponent extends Component {
+  /** Arbitrary counter used by the example system. */
+  public tickCount: number = 0;
+
+  /** Deep clone required by the Component contract. */
+  public clone(): ExampleComponent {
+    const copy = new ExampleComponent();
+    copy.tickCount = this.tickCount;
+    return copy;
+  }
+
+  /** Serialize this component to plain JSON. */
+  public serialize(): Record<string, unknown> {
+    return { tickCount: this.tickCount };
+  }
+
+  /** Restore state from plain JSON produced by {@link serialize}. */
+  public deserialize(data: Record<string, unknown>): void {
+    this.tickCount = typeof data.tickCount === 'number' ? data.tickCount : 0;
+  }
+}

package/template/base/src/systems/example-system.ts

@@ -0,0 +1,28 @@
+import { System, SystemType, SystemPriority, type World } from '@donut-games/engine/core';
+import { ExampleComponent } from '../components/example-component.js';
+
+/**
+ * Example system that increments {@link ExampleComponent.tickCount}
+ * for every matching entity each frame.
+ */
+export class ExampleSystem extends System {
+  public readonly systemType = SystemType.Update;
+  public static priority: number = SystemPriority.Average;
+
+  private readonly exampleQuery;
+
+  public constructor(world: World) {
+    super();
+    this.exampleQuery = world.query([ExampleComponent]);
+  }
+
+  /** Runs once per simulation tick. */
+  public update(_elapsedMilliseconds: number): void {
+    for (const entity of this.exampleQuery.entities) {
+      const exampleComponent = entity.get(ExampleComponent);
+      if (exampleComponent !== undefined) {
+        exampleComponent.tickCount += 1;
+      }
+    }
+  }
+}

package/template/base/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": [
+    "src/**/*"
+  ]
+}

package/template/pixi-2d/donut.json.tpl

@@ -0,0 +1,6 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.1.0",
+  "rendererTarget": "{{rendererTarget}}",
+  "donutEngineVersion": "{{donutEngineVersion}}"
+}

package/template/pixi-2d/package.json.tpl

@@ -0,0 +1,24 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "donut dev",
+    "validate": "donut validate",
+    "build": "donut build",
+    "review": "donut review"
+  },
+  "dependencies": {
+    "@donut-games/engine": "^{{donutEngineVersion}}",
+    "pixi.js": "^{{pixiVersion}}"
+  },
+  "devDependencies": {
+    "@donut-games/cli": "^{{donutEngineVersion}}",
+    "typescript": "^5.4.0",
+    "eslint": "^8.57.0",
+    "@typescript-eslint/parser": "^6.21.0",
+    "@typescript-eslint/eslint-plugin": "^6.21.0",
+    "eslint-plugin-import": "^2.29.1"
+  }
+}

package/template/pixi-2d/src/scenes/default-scene.ts

@@ -0,0 +1,43 @@
+import { Entity, TransformComponent, type World } from '@donut-games/engine/core';
+import { Vector3 } from '@donut-games/engine/math';
+import {
+  CtrllrInputComponent,
+  type CtrllrManagerBridge,
+} from '@donut-games/engine/ctrllr';
+import { SpriteComponent } from '@donut-games/engine/pixi';
+
+/**
+ * Build the default starter scene: one player entity with a transform,
+ * a visual component, and CTRLLR input bindings for basic movement.
+ *
+ * Invoked by the player's `startGame` after all built-in systems are
+ * registered. Add entities and project-specific systems to `world` here.
+ */
+export function createDefaultScene(
+  world: World,
+  ctrllrManager: CtrllrManagerBridge,
+): void {
+  const playerEntity = new Entity({ name: 'Player' });
+
+  const transformComponent = new TransformComponent();
+  transformComponent.position = new Vector3(0, 0, 0);
+  playerEntity.addComponent(transformComponent);
+
+  const spriteComponent = new SpriteComponent();
+  spriteComponent.texturePath = '';
+  spriteComponent.tintColor = 0xff5577;
+  playerEntity.addComponent(spriteComponent);
+
+  const inputComponent = new CtrllrInputComponent({
+    managerBridge: ctrllrManager,
+    actionMap: {
+      moveLeft: 'onMoveLeft',
+      moveRight: 'onMoveRight',
+      moveUp: 'onMoveUp',
+      moveDown: 'onMoveDown',
+    },
+  });
+  playerEntity.addComponent(inputComponent);
+
+  world.add(playerEntity);
+}

package/template/three-3d/donut.json.tpl

@@ -0,0 +1,6 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.1.0",
+  "rendererTarget": "{{rendererTarget}}",
+  "donutEngineVersion": "{{donutEngineVersion}}"
+}

package/template/three-3d/package.json.tpl

@@ -0,0 +1,24 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "donut dev",
+    "validate": "donut validate",
+    "build": "donut build",
+    "review": "donut review"
+  },
+  "dependencies": {
+    "@donut-games/engine": "^{{donutEngineVersion}}",
+    "three": "^{{threeVersion}}"
+  },
+  "devDependencies": {
+    "@donut-games/cli": "^{{donutEngineVersion}}",
+    "typescript": "^5.4.0",
+    "eslint": "^8.57.0",
+    "@typescript-eslint/parser": "^6.21.0",
+    "@typescript-eslint/eslint-plugin": "^6.21.0",
+    "eslint-plugin-import": "^2.29.1"
+  }
+}

package/template/three-3d/src/scenes/default-scene.ts

@@ -0,0 +1,40 @@
+import { Entity, TransformComponent, type World } from '@donut-games/engine/core';
+import { Vector3 } from '@donut-games/engine/math';
+import {
+  CtrllrInputComponent,
+  type CtrllrManagerBridge,
+} from '@donut-games/engine/ctrllr';
+// TODO: import sprite/mesh components from '@donut-games/engine/three' when available
+
+/**
+ * Build the default starter scene: one player entity with a transform,
+ * a visual component, and CTRLLR input bindings for basic movement.
+ *
+ * Invoked by the player's `startGame` after all built-in systems are
+ * registered. Add entities and project-specific systems to `world` here.
+ */
+export function createDefaultScene(
+  world: World,
+  ctrllrManager: CtrllrManagerBridge,
+): void {
+  const playerEntity = new Entity({ name: 'Player' });
+
+  const transformComponent = new TransformComponent();
+  transformComponent.position = new Vector3(0, 0, 0);
+  playerEntity.addComponent(transformComponent);
+
+  // 3D visual component wiring goes here once @donut/three lands.
+
+  const inputComponent = new CtrllrInputComponent({
+    managerBridge: ctrllrManager,
+    actionMap: {
+      moveLeft: 'onMoveLeft',
+      moveRight: 'onMoveRight',
+      moveUp: 'onMoveUp',
+      moveDown: 'onMoveDown',
+    },
+  });
+  playerEntity.addComponent(inputComponent);
+
+  world.add(playerEntity);
+}