jgengine 0.8.0

package/dist/doctor.js

@@ -0,0 +1,161 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { findWorkspaceRoot, readPackageJson } from "./pkg.js";
+import { IN_REPO_TSCONFIG_PATHS } from "./templates.js";
+const SKELETON_FILES = new Set(["game.config.ts", "index.tsx", "main.tsx", "loop.ts", "world.ts", "index.css"]);
+const SKELETON_DIRS = new Set(["game"]);
+function allEngineDeps(pkg) {
+    return Object.fromEntries(Object.entries({ ...pkg.dependencies, ...pkg.devDependencies }).filter(([name]) => name.startsWith("@jgengine/")));
+}
+export function diagnose(dir) {
+    const findings = [];
+    const pkg = readPackageJson(join(dir, "package.json"));
+    if (pkg === null) {
+        return [{ ok: false, label: "package.json readable", fix: `no package.json found in ${dir}` }];
+    }
+    const engineDeps = allEngineDeps(pkg);
+    findings.push({
+        ok: Object.keys(engineDeps).length > 0,
+        label: "@jgengine/* dependencies declared",
+        fix: "add the engine: bun add @jgengine/core @jgengine/react @jgengine/shell (or npx jgengine create for a fresh game)",
+    });
+    findings.push({
+        ok: pkg.type === "module",
+        label: 'package.json "type": "module"',
+        fix: 'the engine is ESM-only; set "type": "module"',
+    });
+    findings.push({
+        ok: pkg.scripts?.dev !== undefined,
+        label: '"dev" script present',
+        fix: 'add "dev": "vite" so the standalone harness can launch',
+    });
+    const ranges = new Set(Object.values(engineDeps).filter((range) => range !== "workspace:*"));
+    findings.push({
+        ok: ranges.size <= 1,
+        label: "@jgengine/* versions aligned",
+        fix: `mixed ranges ${[...ranges].join(", ")} — pin every @jgengine/* package to one version, or run npx jgengine versions`,
+    });
+    const workspaceRoot = findWorkspaceRoot(dir);
+    const usesWorkspaceProtocol = Object.values(engineDeps).includes("workspace:*");
+    findings.push({
+        ok: !usesWorkspaceProtocol || workspaceRoot !== null,
+        label: "workspace:* deps only inside a workspace",
+        fix: "this game was copied out of the engine monorepo — replace workspace:* with published versions (e.g. ^0.8.0)",
+    });
+    const tsconfigPath = join(dir, "tsconfig.json");
+    const tsconfig = existsSync(tsconfigPath)
+        ? JSON.parse(readFileSync(tsconfigPath, "utf8"))
+        : null;
+    findings.push({ ok: tsconfig !== null, label: "tsconfig.json present", fix: "scaffold one with npx jgengine create" });
+    const paths = tsconfig?.compilerOptions?.paths ?? {};
+    const monorepoPaths = Object.values(paths)
+        .flat()
+        .filter((target) => target.includes("../../packages/"));
+    const danglingPaths = monorepoPaths.filter((target) => !existsSync(resolve(dir, target.replace(/\/\*$/, ""))));
+    findings.push({
+        ok: danglingPaths.length === 0,
+        label: "tsconfig paths resolve",
+        fix: `paths point into a missing engine checkout (${danglingPaths[0] ?? ""}) — outside the monorepo, drop compilerOptions.paths and rely on node_modules`,
+    });
+    if (workspaceRoot !== null && usesWorkspaceProtocol) {
+        const missing = Object.entries(IN_REPO_TSCONFIG_PATHS).filter(([alias, target]) => paths[alias]?.[0] !== target[0]);
+        findings.push({
+            ok: missing.length === 0,
+            label: "in-repo tsconfig paths match the canonical game shape",
+            fix: `add compilerOptions.paths ${missing.map(([alias]) => `"${alias}"`).join(", ")} per Games/* (see check-game-shape)`,
+        });
+    }
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies, ...pkg.peerDependencies };
+    const usesReactPkg = engineDeps["@jgengine/react"] !== undefined || engineDeps["@jgengine/shell"] !== undefined;
+    if (usesReactPkg) {
+        findings.push({
+            ok: deps.react !== undefined && deps["react-dom"] !== undefined,
+            label: "react + react-dom present for @jgengine/react|shell",
+            fix: "bun add react react-dom (@jgengine/react peers on react ^19)",
+        });
+    }
+    if (engineDeps["@jgengine/shell"] !== undefined) {
+        findings.push({
+            ok: deps.three !== undefined && deps["@react-three/fiber"] !== undefined,
+            label: "three + @react-three/fiber present for @jgengine/shell",
+            fix: "bun add three @react-three/fiber (the shell renders through react-three-fiber)",
+        });
+    }
+    const cssPath = join(dir, "src", "index.css");
+    if (existsSync(cssPath)) {
+        const css = readFileSync(cssPath, "utf8");
+        const usesTailwind = css.includes("tailwindcss");
+        const coversReact = /@source\s+"[^"]*(@jgengine\/react|packages\/react)/.test(css);
+        const coversShell = /@source\s+"[^"]*(@jgengine\/shell|packages\/shell)/.test(css);
+        findings.push({
+            ok: !usesTailwind || (coversReact && coversShell),
+            label: "Tailwind @source covers @jgengine/react and @jgengine/shell",
+            fix: 'without @source entries for the engine UI packages, HUD classes are silently not generated and the UI renders unstyled — add @source "../node_modules/@jgengine/react/dist" and "../node_modules/@jgengine/shell/dist" to src/index.css',
+        });
+    }
+    else {
+        findings.push({ ok: false, label: "src/index.css present", fix: "the standalone harness needs src/index.css importing tailwindcss" });
+    }
+    findings.push({
+        ok: existsSync(join(dir, "index.html")),
+        label: "index.html present (standalone harness)",
+        fix: "scaffold shape: index.html at the game root mounts /src/main.tsx",
+    });
+    findings.push({
+        ok: existsSync(join(dir, "vite.config.ts")),
+        label: "vite.config.ts present",
+        fix: "the standalone harness runs on vite with @vitejs/plugin-react + @tailwindcss/vite",
+    });
+    const configPath = join(dir, "src", "game.config.ts");
+    const configOk = existsSync(configPath) && /from\s+["']@jgengine\/shell\/defineGame["']/.test(readFileSync(configPath, "utf8"));
+    findings.push({
+        ok: configOk,
+        label: 'src/game.config.ts defines the game via defineGame from "@jgengine/shell/defineGame"',
+        fix: "game.config.ts is the single entry — export const game = defineGame({...})",
+    });
+    const barrelPath = join(dir, "src", "index.tsx");
+    const barrelOk = existsSync(barrelPath) &&
+        /\bgame\b/.test(readFileSync(barrelPath, "utf8").match(/export\s*\{[^}]*\}/g)?.join(" ") ?? "");
+    findings.push({
+        ok: barrelOk,
+        label: "src/index.tsx re-exports { game }",
+        fix: 'add: export { game } from "./game.config";',
+    });
+    const srcDir = join(dir, "src");
+    if (existsSync(srcDir)) {
+        const strays = readdirSync(srcDir).filter((entry) => {
+            const isDir = statSync(join(srcDir, entry)).isDirectory();
+            return isDir ? !SKELETON_DIRS.has(entry) : !SKELETON_FILES.has(entry);
+        });
+        findings.push({
+            ok: strays.length === 0,
+            label: "src/ holds only the skeleton (everything else under src/game/)",
+            fix: `move ${strays.join(", ")} under src/game/ — src/ is only game.config.ts, index.tsx, main.tsx, loop.ts, world.ts, index.css`,
+        });
+    }
+    if (!usesWorkspaceProtocol) {
+        findings.push({
+            ok: existsSync(join(dir, "node_modules", "@jgengine", "core")),
+            label: "engine installed in node_modules",
+            fix: "run bun install (or npm install)",
+        });
+    }
+    return findings;
+}
+export function runDoctor(argv) {
+    const dir = resolve(argv.find((arg) => !arg.startsWith("--")) ?? ".");
+    const findings = diagnose(dir);
+    for (const finding of findings) {
+        if (finding.ok) {
+            console.log(`  ✓ ${finding.label}`);
+        }
+        else {
+            console.log(`  ✗ ${finding.label}`);
+            if (finding.fix !== undefined)
+                console.log(`      fix: ${finding.fix}`);
+        }
+    }
+    const failed = findings.filter((finding) => !finding.ok).length;
+    console.log(failed === 0 ? "\ndoctor: all clear" : `\ndoctor: ${failed} problem(s) found`);
+    return failed === 0 ? 0 : 1;
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { gameTemplate, displayNameFromId, GAME_ID_PATTERN, IN_REPO_TSCONFIG_PATHS } from "./templates.js";
+export type { TemplateFile, TemplateOptions, TemplateVariant } from "./templates.js";
+export { runCreate, writeGame, registerRootGameScript } from "./create.js";
+export { diagnose, runDoctor } from "./doctor.js";
+export type { Finding } from "./doctor.js";
+export { cliVersion } from "./pkg.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { gameTemplate, displayNameFromId, GAME_ID_PATTERN, IN_REPO_TSCONFIG_PATHS } from "./templates.js";
+export { runCreate, writeGame, registerRootGameScript } from "./create.js";
+export { diagnose, runDoctor } from "./doctor.js";
+export { cliVersion } from "./pkg.js";

package/dist/pkg.d.ts

@@ -0,0 +1,18 @@
+interface PackageJson {
+    name?: string;
+    version?: string;
+    type?: string;
+    workspaces?: string[];
+    scripts?: Record<string, string>;
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    peerDependencies?: Record<string, string>;
+}
+export type { PackageJson };
+export declare function readPackageJson(path: string): PackageJson | null;
+export declare function cliVersion(): string;
+export declare function findUp(startDir: string, predicate: (dir: string) => boolean): string | null;
+export declare function findWorkspaceRoot(startDir: string): string | null;
+export declare function isEngineMonorepo(rootDir: string): boolean;
+export declare function flag(argv: string[], name: string): string | undefined;
+export declare function hasFlag(argv: string[], name: string): boolean;

package/dist/pkg.js

@@ -0,0 +1,45 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+export function readPackageJson(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function cliVersion() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const own = readPackageJson(join(here, "..", "package.json")) ?? readPackageJson(join(here, "..", "..", "package.json"));
+    return own?.version ?? "0.0.0";
+}
+export function findUp(startDir, predicate) {
+    let dir = resolve(startDir);
+    for (;;) {
+        if (predicate(dir))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+export function findWorkspaceRoot(startDir) {
+    return findUp(startDir, (dir) => {
+        const pkg = readPackageJson(join(dir, "package.json"));
+        return Array.isArray(pkg?.workspaces);
+    });
+}
+export function isEngineMonorepo(rootDir) {
+    return existsSync(join(rootDir, "packages", "core", "src")) && existsSync(join(rootDir, "Games"));
+}
+export function flag(argv, name) {
+    const index = argv.indexOf(`--${name}`);
+    return index >= 0 ? argv[index + 1] : undefined;
+}
+export function hasFlag(argv, name) {
+    return argv.includes(`--${name}`);
+}

package/dist/templates.d.ts

@@ -0,0 +1,15 @@
+export type TemplateVariant = "standalone" | "in-repo";
+export interface TemplateOptions {
+    id: string;
+    name: string;
+    variant: TemplateVariant;
+    engineVersion: string;
+}
+export interface TemplateFile {
+    path: string;
+    contents: string;
+}
+export declare const GAME_ID_PATTERN: RegExp;
+export declare function displayNameFromId(id: string): string;
+export declare const IN_REPO_TSCONFIG_PATHS: Record<string, string[]>;
+export declare function gameTemplate(options: TemplateOptions): TemplateFile[];

package/dist/templates.js

@@ -0,0 +1,341 @@
+export const GAME_ID_PATTERN = /^[a-z][a-z0-9-]*$/;
+export function displayNameFromId(id) {
+    return id
+        .split("-")
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(" ");
+}
+const indexHtml = (name) => `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
+    <title>${name}</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+`;
+const viteConfig = `import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import tailwindcss from "@tailwindcss/vite";
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+const engineSrc = (pkg: string) => fileURLToPath(new URL(\`../../packages/\${pkg}/src\`, import.meta.url));
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+  clearScreen: false,
+  build: { target: "es2022" },
+  resolve: {
+    extensions: [".ts", ".tsx", ".mjs", ".js", ".jsx", ".json"],
+    alias: existsSync(engineSrc("core"))
+      ? [
+          { find: /^@jgengine\\/core\\/(.*)$/, replacement: \`\${engineSrc("core")}/$1\` },
+          { find: /^@jgengine\\/react\\/(.*)$/, replacement: \`\${engineSrc("react")}/$1\` },
+          { find: /^@jgengine\\/ws\\/(.*)$/, replacement: \`\${engineSrc("ws")}/$1\` },
+          { find: /^@jgengine\\/shell\\/(.*)$/, replacement: \`\${engineSrc("shell")}/$1\` },
+          { find: /^@jgengine\\/assets$/, replacement: \`\${engineSrc("assets")}/index.ts\` },
+          { find: /^@jgengine\\/assets\\/(.*)$/, replacement: \`\${engineSrc("assets")}/$1\` },
+        ]
+      : [],
+  },
+});
+`;
+const standalonePackageJson = (id, engineVersion) => `${JSON.stringify({
+    name: id,
+    version: "0.1.0",
+    private: true,
+    type: "module",
+    scripts: {
+        dev: "vite",
+        build: "vite build",
+        preview: "vite preview",
+        "check-types": "tsc --noEmit -p tsconfig.json",
+        test: "bun test src",
+    },
+    dependencies: {
+        "@jgengine/core": `^${engineVersion}`,
+        "@jgengine/react": `^${engineVersion}`,
+        "@jgengine/shell": `^${engineVersion}`,
+        "@react-three/fiber": "^9.5.0",
+        react: "19.2.3",
+        "react-dom": "19.2.3",
+        three: "^0.182.0",
+    },
+    devDependencies: {
+        "@tailwindcss/vite": "^4.0.15",
+        "@types/react": "^19",
+        "@types/react-dom": "^19",
+        "@types/three": "^0.182.0",
+        "@vitejs/plugin-react": "^4.3.4",
+        tailwindcss: "^4.0.15",
+        typescript: "^5",
+        vite: "^6.2.2",
+    },
+}, null, 2)}
+`;
+const inRepoPackageJson = (id) => `${JSON.stringify({
+    name: `@games/${id}`,
+    version: "0.1.0",
+    private: true,
+    type: "module",
+    scripts: {
+        dev: "vite",
+        "check-types": "tsgo --noEmit -p tsconfig.json",
+        test: "bun test src",
+    },
+    dependencies: {
+        "@jgengine/core": "workspace:*",
+        "@jgengine/react": "workspace:*",
+        "@jgengine/shell": "workspace:*",
+        "@react-three/fiber": "^9.5.0",
+        react: "19.2.3",
+        "react-dom": "19.2.3",
+        three: "^0.182.0",
+    },
+    devDependencies: {
+        "@tailwindcss/vite": "^4.0.15",
+        "@types/react": "^19",
+        "@types/react-dom": "^19",
+        "@types/three": "^0.182.0",
+        "@vitejs/plugin-react": "^4.3.4",
+        tailwindcss: "^4.0.15",
+        typescript: "^5",
+        vite: "^6.2.2",
+    },
+    exports: {
+        ".": "./src/index.tsx",
+        "./*": "./src/*",
+    },
+}, null, 2)}
+`;
+const sharedCompilerOptions = {
+    target: "ES2022",
+    lib: ["ES2022", "DOM"],
+    module: "ESNext",
+    moduleResolution: "bundler",
+    jsx: "react-jsx",
+    strict: true,
+    skipLibCheck: true,
+    isolatedModules: true,
+    verbatimModuleSyntax: true,
+    types: ["vite/client"],
+};
+export const IN_REPO_TSCONFIG_PATHS = {
+    "@jgengine/core/*": ["../../packages/core/src/*"],
+    "@jgengine/react/*": ["../../packages/react/src/*"],
+    "@jgengine/ws/*": ["../../packages/ws/src/*"],
+    "@jgengine/shell/*": ["../../packages/shell/src/*"],
+    "@jgengine/assets": ["../../packages/assets/src/index.ts"],
+    "@jgengine/assets/*": ["../../packages/assets/src/*"],
+};
+const tsconfigJson = (variant) => `${JSON.stringify({
+    compilerOptions: variant === "in-repo" ? { ...sharedCompilerOptions, paths: IN_REPO_TSCONFIG_PATHS } : sharedCompilerOptions,
+    include: ["src"],
+    exclude: ["src/**/*.test.ts"],
+}, null, 2)}
+`;
+const indexCss = (variant) => `@import "tailwindcss";
+${variant === "in-repo"
+    ? `@source "../../../packages/react/src";
+@source "../../../packages/shell/src";`
+    : `@source "../node_modules/@jgengine/react/dist";
+@source "../node_modules/@jgengine/shell/dist";`}
+
+html,
+body,
+#root {
+  height: 100%;
+  margin: 0;
+  background: #0a0a0a;
+}
+`;
+const mainTsx = `import "./index.css";
+
+import { createRoot } from "react-dom/client";
+
+import { GameHost } from "@jgengine/shell/GameHost";
+
+import { game } from "./game.config";
+
+const root = document.getElementById("root");
+if (root === null) throw new Error("main: missing #root mount element");
+createRoot(root).render(<GameHost playable={game} />);
+`;
+const indexTsx = `export { game } from "./game.config";
+`;
+const gameConfigTs = (name) => `import { createAssetCatalog } from "@jgengine/core/scene/assetCatalog";
+import { defineGame } from "@jgengine/shell/defineGame";
+
+import { entityById } from "./game/content";
+import { keybinds } from "./game/keybinds";
+import { GameUI } from "./game/ui/GameUI";
+import { onInit, onNewPlayer, onTick } from "./loop";
+import { physics, world } from "./world";
+
+export const game = defineGame({
+  name: "${name}",
+  assets: createAssetCatalog(),
+  world,
+  physics,
+  input: keybinds,
+  server: { mode: "single" },
+  save: "none",
+  content: { entityById },
+  loop: { onInit, onNewPlayer, onTick },
+  GameUI,
+});
+`;
+const worldTs = (id) => `import type { PhysicsConfig } from "@jgengine/core/game/defineGame";
+import { environment, grass, sky, terrain, type EnvironmentWorldFeature } from "@jgengine/core/world/features";
+
+export const world: EnvironmentWorldFeature = environment({
+  terrain: terrain({ bounds: { w: 96, d: 96 }, height: 0, material: "grass" }),
+  sky: sky({ preset: "day" }),
+  vegetation: grass({ area: { w: 80, d: 80 }, density: 2, colors: ["#3f7d2d", "#6bbf4a"], seed: "${id}" }),
+});
+
+export const physics: PhysicsConfig = { gravity: -24 };
+`;
+const loopTs = `import type { GameContext } from "@jgengine/core/runtime/gameContext";
+
+import { PLAYER, SPAWN } from "./game/tuning";
+
+export function onInit(_ctx: GameContext): void {}
+
+export function onNewPlayer(ctx: GameContext): void {
+  ctx.scene.entity.spawn(PLAYER, { id: ctx.player.userId, position: SPAWN });
+}
+
+export function onTick(_ctx: GameContext, _dt: number): void {}
+`;
+const tuningTs = `export const PLAYER = "player";
+export const MAX_HEALTH = 5;
+export const WALK_SPEED = 4;
+export const SPAWN: [number, number, number] = [0, 0, 0];
+`;
+const contentTs = `import type { GameContextEntityEntry } from "@jgengine/core/runtime/gameContext";
+
+import { MAX_HEALTH, PLAYER, WALK_SPEED } from "./tuning";
+
+export function entityById(catalogId: string): GameContextEntityEntry | null {
+  if (catalogId === PLAYER) {
+    return {
+      role: "player",
+      stats: { health: { max: MAX_HEALTH, min: 0 } },
+      receive: { damage: { order: ["health"] } },
+      movement: { walkSpeed: WALK_SPEED },
+    };
+  }
+  return null;
+}
+`;
+const keybindsTs = `import type { ActionCodesMap } from "@jgengine/core/input/actionBindings";
+
+export const keybinds: ActionCodesMap = {
+  interact: ["KeyE"],
+};
+`;
+const gameUiTsx = (name) => `import { useEntityStat, usePlayer } from "@jgengine/react/hooks";
+
+import { MAX_HEALTH } from "../tuning";
+
+function Hearts({ userId }: { userId: string }) {
+  const health = useEntityStat(userId, "health");
+  const current = health === null ? MAX_HEALTH : Math.round(health.current);
+  const max = health === null ? MAX_HEALTH : Math.round(health.max);
+  return (
+    <div className="flex items-center gap-1" aria-label="health">
+      {Array.from({ length: max }, (_, index) => (
+        <span
+          key={index}
+          className={index < current ? "text-lg leading-none text-rose-400" : "text-lg leading-none text-white/20"}
+        >
+          {index < current ? "\\u2665" : "\\u2661"}
+        </span>
+      ))}
+    </div>
+  );
+}
+
+export function GameUI() {
+  const { userId } = usePlayer();
+  return (
+    <div className="pointer-events-none absolute inset-0 p-4 text-white">
+      <div className="flex w-fit items-center gap-4 rounded-lg bg-black/40 px-3 py-2 backdrop-blur">
+        <span className="text-sm font-semibold tracking-wide">${name}</span>
+        <Hearts userId={userId} />
+      </div>
+    </div>
+  );
+}
+`;
+const worldTest = (id) => `import { describe, expect, test } from "bun:test";
+import { summarizeEnvironment } from "@jgengine/core/world/environmentSummary";
+
+import { world } from "../world";
+
+describe("${id} world", () => {
+  const summary = summarizeEnvironment(world);
+
+  test("renders a populated scene", () => {
+    expect(summary.isEmpty).toBe(false);
+  });
+
+  test("has the expected backdrop content", () => {
+    expect(summary.counts.terrain).toBe(1);
+    expect(summary.counts.vegetationFields).toBe(1);
+  });
+
+  test("terrain resolves to a finite ground plane", () => {
+    expect(summary.terrain?.height.finite).toBe(true);
+  });
+});
+`;
+const agentsMd = (name, variant) => `# ${name} — agent notes
+
+This is a JGengine game (pure-TypeScript engine SDK, \`@jgengine/*\` on npm). Load context before writing code:
+
+- Engine API surface: \`npx jgengine llms core\` (any package name works) prints the packaged API docs.
+- Agent skills — API reference, phased game-build workflow, browserless verify gate: \`npx jgengine skills\` installs them into \`.claude/skills\`.
+- Setup broken or UI unstyled: \`npx jgengine doctor\`.
+
+Rules this project follows:
+
+- Shape: \`src/\` holds only \`game.config.ts\`, \`index.tsx\`, \`main.tsx\`, \`loop.ts\`, \`world.ts\`, \`index.css\`; every game-specific module, UI component, and test lives under \`src/game/\`.
+- \`game.config.ts\` is the single entry — \`defineGame({...})\` from \`@jgengine/shell/defineGame\`.
+- Scene and world changes are proven with \`summarizeEnvironment\` assertions in \`bun test src\` (see \`src/game/world.world.test.ts\`), never by screenshots as the inner loop.
+- HUD styling is Tailwind v4: the \`@source\` entries in \`src/index.css\` must cover \`@jgengine/react\` and \`@jgengine/shell\`${variant === "in-repo" ? " (engine source dirs in this monorepo)" : " (their dist dirs in node_modules)"}, or engine UI classes are silently not generated and the HUD renders unstyled.
+- \`onNewPlayer\` spawns the player entity with \`id === ctx.player.userId\`; \`onTick\`'s \`dt\` is game time, never wall-clock.
+`;
+export function gameTemplate(options) {
+    const { id, name, variant, engineVersion } = options;
+    if (!GAME_ID_PATTERN.test(id)) {
+        throw new Error(`game id "${id}" must be kebab-case: lowercase letters, digits, dashes, starting with a letter`);
+    }
+    return [
+        { path: "index.html", contents: indexHtml(name) },
+        { path: "vite.config.ts", contents: viteConfig },
+        {
+            path: "package.json",
+            contents: variant === "in-repo" ? inRepoPackageJson(id) : standalonePackageJson(id, engineVersion),
+        },
+        { path: "tsconfig.json", contents: tsconfigJson(variant) },
+        { path: "AGENTS.md", contents: agentsMd(name, variant) },
+        { path: "src/index.css", contents: indexCss(variant) },
+        { path: "src/main.tsx", contents: mainTsx },
+        { path: "src/index.tsx", contents: indexTsx },
+        { path: "src/game.config.ts", contents: gameConfigTs(name) },
+        { path: "src/loop.ts", contents: loopTs },
+        { path: "src/world.ts", contents: worldTs(id) },
+        { path: "src/game/tuning.ts", contents: tuningTs },
+        { path: "src/game/content.ts", contents: contentTs },
+        { path: "src/game/keybinds.ts", contents: keybindsTs },
+        { path: "src/game/ui/GameUI.tsx", contents: gameUiTsx(name) },
+        { path: "src/game/world.world.test.ts", contents: worldTest(id) },
+    ];
+}