@threenative/core 0.2.0 → 0.3.1

package/mcp/install.mjs

@@ -0,0 +1,145 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { CODEX_MCP_SERVERS, mergeMcpServers } from "./servers.mjs";
+
+/** The project being installed into, or undefined when this install has no project to write to —
+ * a nested dependency install, or core's own workspace build. */
+export function installTarget(environment = process.env, cwd = process.cwd()) {
+  const target = path.resolve(environment.INIT_CWD ?? cwd);
+  if (target.split(path.sep).includes("node_modules")) return undefined;
+  const manifestPath = path.join(target, "package.json");
+  if (!existsSync(manifestPath)) return undefined;
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch {
+    return undefined;
+  }
+  if (typeof manifest !== "object" || manifest === null || Array.isArray(manifest))
+    return undefined;
+  if (manifest.name === "@threenative/core") return undefined;
+  const dependencyGroups = [
+    manifest.dependencies,
+    manifest.devDependencies,
+    manifest.optionalDependencies,
+    manifest.peerDependencies,
+  ];
+  const declaresCore = dependencyGroups.some(
+    (dependencies) =>
+      typeof dependencies === "object" &&
+      dependencies !== null &&
+      Object.hasOwn(dependencies, "@threenative/core"),
+  );
+  return declaresCore ? target : undefined;
+}
+
+/** Every agent host that reads a **project-scoped** MCP config, and the file each one reads.
+ *
+ * Project-scoped is the whole admission rule. A host that only reads a machine-wide config
+ * (Windsurf, Cline, Amp, the JetBrains assistants) is deliberately absent: installing a library
+ * into one game must never edit a file that governs every other project on the machine. Those
+ * hosts are wired by hand, and `docs/architecture/` says so. */
+export const MCP_HOSTS = Object.freeze([
+  Object.freeze({
+    id: "claude-code",
+    label: "Claude Code",
+    file: ".mcp.json",
+    format: "mcpServers",
+  }),
+  Object.freeze({ id: "codex", label: "Codex", file: ".codex/config.toml", format: "codex" }),
+  Object.freeze({ id: "cursor", label: "Cursor", file: ".cursor/mcp.json", format: "mcpServers" }),
+  Object.freeze({ id: "vscode", label: "VS Code", file: ".vscode/mcp.json", format: "vscode" }),
+  Object.freeze({
+    id: "gemini-cli",
+    label: "Gemini CLI",
+    file: ".gemini/settings.json",
+    format: "mcpServers",
+  }),
+  Object.freeze({
+    id: "opencode",
+    label: "opencode",
+    file: "opencode.json",
+    format: "opencode",
+    // Written only when this installer creates the file, so a second install still reports
+    // "unchanged" rather than rewriting a config the user has since edited.
+    seed: Object.freeze({ $schema: "https://opencode.ai/config.json" }),
+  }),
+  Object.freeze({ id: "zed", label: "Zed", file: ".zed/settings.json", format: "zed" }),
+]);
+
+/** Adds the ThreeNative servers to one host's JSON config, creating it when absent. Returns what it
+ * did so the installer can say so once and stay quiet otherwise. */
+export function ensureJsonMcpConfig(target, file, format, seed = undefined) {
+  const configPath = path.join(target, file);
+  let existing;
+  if (existsSync(configPath)) {
+    // A config we cannot parse is still the user's. Rewriting it would drop servers we never wrote.
+    try {
+      existing = JSON.parse(readFileSync(configPath, "utf8"));
+    } catch {
+      return "unreadable";
+    }
+  }
+  let merged;
+  try {
+    merged = mergeMcpServers(existing, format);
+  } catch {
+    return "unreadable";
+  }
+  const { changed, config, conflicts } = merged;
+  if (!changed) return conflicts.length > 0 ? "conflict" : "unchanged";
+  const written = existing === undefined ? { ...seed, ...config } : config;
+  mkdirSync(path.dirname(configPath), { recursive: true });
+  writeFileSync(configPath, `${JSON.stringify(written, null, 2)}\n`);
+  return conflicts.length > 0 ? "conflict" : existing === undefined ? "created" : "updated";
+}
+
+/** Adds the ThreeNative servers to `<target>/.mcp.json`, the config Claude Code reads. */
+export function ensureMcpConfig(target) {
+  return ensureJsonMcpConfig(target, ".mcp.json", "mcpServers");
+}
+
+/** Adds any missing ThreeNative servers to Codex's project-scoped MCP config without replacing
+ * user-authored settings or server definitions. TOML rather than JSON, so this one appends text
+ * instead of re-serialising: a config we cannot parse back is one we must not rewrite. */
+export function ensureCodexMcpConfig(target) {
+  const directory = path.join(target, ".codex");
+  const configPath = path.join(directory, "config.toml");
+  const existing = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
+  const missing = CODEX_MCP_SERVERS.filter(
+    ({ name }) => !existing.includes(`[mcp_servers.${name}]`),
+  );
+  if (missing.length === 0) return "unchanged";
+  mkdirSync(directory, { recursive: true });
+  const separator =
+    existing.length === 0 || existing.endsWith("\n\n")
+      ? ""
+      : existing.endsWith("\n")
+        ? "\n"
+        : "\n\n";
+  writeFileSync(
+    configPath,
+    `${existing}${separator}${missing.map(({ body }) => body).join("\n\n")}\n`,
+  );
+  return existing.length === 0 ? "created" : "updated";
+}
+
+/** Wires every host in `MCP_HOSTS`, mapping host id to what the write did. One host's unreadable
+ * or unwritable config never stops the rest: a project with a hand-edited `.cursor/mcp.json`
+ * should still get its Codex and VS Code tools. */
+export function ensureHostMcpConfigs(target) {
+  const outcomes = new Map();
+  for (const host of MCP_HOSTS) {
+    try {
+      outcomes.set(
+        host.id,
+        host.format === "codex"
+          ? ensureCodexMcpConfig(target)
+          : ensureJsonMcpConfig(target, host.file, host.format, host.seed),
+      );
+    } catch {
+      outcomes.set(host.id, "unreadable");
+    }
+  }
+  return outcomes;
+}

package/mcp/launch.mjs

@@ -0,0 +1,72 @@
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+/** Where a package is installed, or undefined when it is not. Node's own resolver is the wrong tool
+ * here: `threenative-engine-mcp` publishes an `exports` map with only an `import` condition, which
+ * `createRequire().resolve` refuses, and the answer we want is the directory rather than a
+ * specifier's entry point. Walking `node_modules` upward from both the project and this package
+ * covers a direct dependency, a hoisted one, and pnpm's nested store alike. */
+function packageDirectory(name) {
+  const starts = [process.cwd(), path.dirname(fileURLToPath(import.meta.url))];
+  for (const start of starts) {
+    let directory = path.resolve(start);
+    while (true) {
+      const candidate = path.join(directory, "node_modules", name);
+      if (existsSync(path.join(candidate, "package.json"))) return candidate;
+      const parent = path.dirname(directory);
+      if (parent === directory) break;
+      directory = parent;
+    }
+  }
+  return undefined;
+}
+
+/** The module that starts the server. The published main entry is not always it —
+ * `threenative-sculpt-mcp` exports a library from `dist/index.js` and starts its server from the
+ * `bin` file — so `bin` wins wherever a package declares one. */
+function serverEntry(directory) {
+  const manifest = JSON.parse(readFileSync(path.join(directory, "package.json"), "utf8"));
+  const bin = typeof manifest.bin === "string" ? manifest.bin : manifest.bin?.[manifest.name];
+  const exported =
+    typeof manifest.exports === "string"
+      ? manifest.exports
+      : (manifest.exports?.["."]?.import ?? manifest.exports?.["."]);
+  const relative =
+    bin ??
+    (typeof exported === "string" ? exported : undefined) ??
+    manifest.main ??
+    manifest.module;
+  return relative === undefined ? undefined : path.resolve(directory, relative);
+}
+
+/** Runs an MCP server the project may or may not have installed. Nothing here may write to stdout:
+ * that stream is the JSON-RPC transport, and one stray line makes the server unusable. */
+export async function launchMcpServer({ name, version, env = {} }) {
+  for (const [key, value] of Object.entries(env)) process.env[key] ??= value;
+  const directory = packageDirectory(name);
+  const entry = directory === undefined ? undefined : serverEntry(directory);
+  if (entry !== undefined && existsSync(entry)) {
+    // A server entry that is also a `bin` starts itself only when it is the process's main module,
+    // which it decides by comparing `process.argv[1]` against its own path. Importing it without
+    // this line loads the module and starts nothing, and the host reports a server that connected
+    // and then went silent.
+    process.argv[1] = entry;
+    await import(pathToFileURL(entry).href);
+    return;
+  }
+  // Not installed. `npx` keeps the server available in a project that never listed it, which is the
+  // whole point of wiring these in from the library rather than from a scaffold.
+  const child = spawn("npx", ["--yes", `${name}@${version}`], {
+    env: process.env,
+    stdio: "inherit",
+  });
+  child.on("error", (error) => {
+    process.stderr.write(`TN_MCP_LAUNCH: ${name} is not installed and npx failed: ${error}\n`);
+    process.exit(1);
+  });
+  child.on("exit", (code, signal) => {
+    process.exit(signal === null ? (code ?? 0) : 1);
+  });
+}

package/mcp/sculpt.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { launchMcpServer } from "./launch.mjs";
+import { MCP_PACKAGES } from "./servers.mjs";
+
+await launchMcpServer(MCP_PACKAGES.sculpt);

package/mcp/servers.d.mts

@@ -0,0 +1,34 @@
+// Types for `servers.mjs`. That file is plain JavaScript by design — `@threenative/core`'s
+// postinstall runs it before anything is built — so it can never be a `.ts`. Without this
+// declaration every consumer reached for `@ts-expect-error` and then cast the result back into a
+// shape of its own, which is three private copies of one contract.
+
+export interface IMcpServerEntry {
+  readonly args: readonly string[];
+  readonly command: string;
+  readonly env?: Readonly<Record<string, string>>;
+}
+
+export interface IMcpPackage {
+  readonly name: string;
+  readonly version: string;
+}
+
+/** One host's whole config with this format's server table merged in. The table's key is the
+ * host's own (`mcpServers`, `servers`, `mcp`, `context_servers`), so a caller reading a key it did
+ * not ask for gets `undefined` rather than a silently empty object. */
+export interface IMcpConfigFormat {
+  readonly changed: boolean;
+  readonly config: Record<string, Record<string, Record<string, unknown>> | undefined>;
+}
+
+export interface ICodexMcpServer {
+  readonly body: string;
+  readonly name: string;
+}
+
+export declare const MCP_SERVERS: Readonly<Record<string, IMcpServerEntry>>;
+export declare const MCP_PACKAGES: Readonly<Record<string, IMcpPackage>>;
+export declare const SERVER_FORMAT_NAMES: readonly string[];
+export declare const CODEX_MCP_SERVERS: readonly ICodexMcpServer[];
+export declare function mergeMcpServers(existing: unknown, format?: string): IMcpConfigFormat;

package/mcp/servers.mjs

@@ -0,0 +1,160 @@
+// The MCP servers a ThreeNative project always has. `@threenative/core` is a direct dependency of
+// every generated game, so `./node_modules/@threenative/core/mcp/<file>` is a path that resolves
+// under npm, pnpm and yarn alike — unlike `./node_modules/threenative-asset-mcp/...`, which only
+// exists when the package manager hoists, and which a project that never listed the server as a
+// direct dependency does not have at all.
+export const MCP_SERVERS = Object.freeze({
+  "threenative-assets": Object.freeze({
+    command: "node",
+    args: Object.freeze(["./node_modules/@threenative/core/mcp/assets.mjs"]),
+    // Entries rather than an object literal: these are environment variable names, not identifiers,
+    // and written as property names they read as names the naming rule must judge.
+    env: Object.freeze(
+      Object.fromEntries([
+        ["ASSET_DOWNLOAD_DIR", "./public/assets"],
+        ["AUDIO_DOWNLOAD_DIR", "./public/audio"],
+      ]),
+    ),
+  }),
+  "threenative-sculpt": Object.freeze({
+    command: "node",
+    args: Object.freeze(["./node_modules/@threenative/core/mcp/sculpt.mjs"]),
+  }),
+  "threenative-engine": Object.freeze({
+    command: "node",
+    args: Object.freeze(["./node_modules/@threenative/core/mcp/engine.mjs"]),
+  }),
+  // Drives an installed Blender headlessly so a downloaded .fbx becomes a GLB. It ships no
+  // Blender and probes for one only when a tool is called, so a project that never converts a
+  // model pays nothing for having this server wired.
+  "threenative-blender": Object.freeze({
+    command: "node",
+    args: Object.freeze(["./node_modules/@threenative/core/mcp/blender.mjs"]),
+  }),
+});
+
+/** The external package each shim launches. Core installs asset and sculpt transitively and bundles
+ * engine discovery itself: a game author must never know these package names or install them
+ * separately. The pinned engine version remains an emergency fallback for a legacy development
+ * checkout whose bundle has not been built. */
+export const MCP_PACKAGES = Object.freeze({
+  assets: Object.freeze({ name: "threenative-asset-mcp", version: "0.8.0" }),
+  sculpt: Object.freeze({ name: "threenative-sculpt-mcp", version: "0.1.1" }),
+  engine: Object.freeze({ name: "threenative-engine-mcp", version: "0.2.1" }),
+  blender: Object.freeze({ name: "threenative-blender-mcp", version: "0.1.1" }),
+});
+
+/** How one host spells a stdio MCP server. Hosts agree on what to run and disagree on where to
+ * write it down, so the servers are declared once above and translated here. `key` is the property
+ * the host reads its server table from; `entry` is one server in that host's own shape. */
+const SERVER_FORMATS = Object.freeze({
+  // Claude Code (`.mcp.json`), Cursor and the Gemini CLI all read this one.
+  mcpServers: Object.freeze({
+    key: "mcpServers",
+    entry: (server) => ({
+      command: server.command,
+      args: [...server.args],
+      ...(server.env === undefined ? {} : { env: { ...server.env } }),
+    }),
+  }),
+  // VS Code names the table `servers` and requires an explicit transport per server.
+  vscode: Object.freeze({
+    key: "servers",
+    entry: (server) => ({
+      type: "stdio",
+      command: server.command,
+      args: [...server.args],
+      ...(server.env === undefined ? {} : { env: { ...server.env } }),
+    }),
+  }),
+  // opencode folds the command and its arguments into one array and spells the environment
+  // `environment`. A server it does not mark enabled is written down and never started.
+  opencode: Object.freeze({
+    key: "mcp",
+    entry: (server) => ({
+      type: "local",
+      command: [server.command, ...server.args],
+      enabled: true,
+      ...(server.env === undefined ? {} : { environment: { ...server.env } }),
+    }),
+  }),
+  // Zed calls them context servers and needs `source: "custom"` to accept a command of our own.
+  zed: Object.freeze({
+    key: "context_servers",
+    entry: (server) => ({
+      source: "custom",
+      command: server.command,
+      args: [...server.args],
+      ...(server.env === undefined ? {} : { env: { ...server.env } }),
+    }),
+  }),
+});
+
+export const SERVER_FORMAT_NAMES = Object.freeze(Object.keys(SERVER_FORMATS));
+
+/** Adds the ThreeNative servers to an existing config without touching anything else in it, and
+ * reports whether the file needs rewriting. Fails closed on a config that is not an object: an
+ * unreadable config is the user's, and overwriting it would lose servers we did not write. */
+export function mergeMcpServers(existing, format = "mcpServers") {
+  const shape = SERVER_FORMATS[format];
+  if (shape === undefined) throw new Error(`Unknown MCP config format '${format}'.`);
+  const malformed =
+    existing !== undefined &&
+    (typeof existing !== "object" || existing === null || Array.isArray(existing));
+  if (malformed) {
+    throw new Error("MCP config root must be an object.");
+  }
+  const previous = existing ?? {};
+  const existingServers = previous[shape.key];
+  if (
+    existingServers !== undefined &&
+    (typeof existingServers !== "object" ||
+      existingServers === null ||
+      Array.isArray(existingServers))
+  ) {
+    throw new Error(`MCP config '${shape.key}' must be an object.`);
+  }
+  const servers = { ...(existingServers ?? {}) };
+  for (const [name, server] of Object.entries(servers)) {
+    if (typeof server !== "object" || server === null || Array.isArray(server)) {
+      throw new Error(`MCP server '${name}' in '${shape.key}' must be an object.`);
+    }
+  }
+  let changed = false;
+  const conflicts = [];
+  for (const [name, server] of Object.entries(MCP_SERVERS)) {
+    const wanted = shape.entry(server);
+    if (Object.hasOwn(servers, name)) {
+      if (JSON.stringify(servers[name]) !== JSON.stringify(wanted)) conflicts.push(name);
+      continue;
+    }
+    servers[name] = wanted;
+    changed = true;
+  }
+  return { changed, conflicts, config: { ...previous, [shape.key]: servers } };
+}
+
+/** One server as a Codex TOML table. Derived from `MCP_SERVERS` rather than written out beside it:
+ * two hand-maintained lists of the same three servers drift, and the drift is silent until an
+ * agent in Codex quietly has no asset tools. */
+function codexServerBlock(name, server) {
+  const args = server.args.map((argument) => JSON.stringify(argument)).join(", ");
+  const lines = [
+    `[mcp_servers.${name}]`,
+    `command = ${JSON.stringify(server.command)}`,
+    `args = [${args}]`,
+  ];
+  if (server.env !== undefined) {
+    lines.push("", `[mcp_servers.${name}.env]`);
+    for (const [key, value] of Object.entries(server.env)) {
+      lines.push(`${key} = ${JSON.stringify(value)}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+export const CODEX_MCP_SERVERS = Object.freeze(
+  Object.entries(MCP_SERVERS).map(([name, server]) =>
+    Object.freeze({ body: codexServerBlock(name, server), name }),
+  ),
+);

package/package.json

@@ -1,10 +1,39 @@
 {
   "name": "@threenative/core",
-  "version": "0.2.0",
+  "version": "0.3.1",
+  "license": "MIT AND GPL-2.0-or-later",
   "description": "The small vanilla Three.js game runtime foundation.",
+  "keywords": [
+    "threenative",
+    "three",
+    "threejs",
+    "webgpu",
+    "game-engine",
+    "game-framework",
+    "gamedev",
+    "typescript"
+  ],
+  "homepage": "https://github.com/ThreeNativeHQ/threenative#readme",
+  "bugs": {
+    "url": "https://github.com/ThreeNativeHQ/threenative/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ThreeNativeHQ/threenative.git",
+    "directory": "packages/core"
+  },
   "type": "module",
   "files": [
-    "dist"
+    "dist",
+    "LICENSE",
+    "mcp",
+    "gpl",
+    "scripts/apply-three-patch.mjs",
+    "scripts/ensure-mcp.mjs",
+    "scripts/postinstall.mjs",
+    "patches",
+    "capabilities.json",
+    "README.md"
   ],
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -22,6 +51,22 @@
       "types": "./dist/hot.d.ts",
       "import": "./dist/hot.js"
     },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./ui-layer": {
+      "types": "./dist/ui-layer.d.ts",
+      "import": "./dist/ui-layer.js"
+    },
+    "./world": {
+      "types": "./dist/world.d.ts",
+      "import": "./dist/world.js"
+    },
+    "./net": {
+      "types": "./dist/net.d.ts",
+      "import": "./dist/net.js"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
@@ -31,18 +76,43 @@
   "dependencies": {
     "three": "0.185.1",
     "three-mesh-bvh": "0.9.14",
-    "zustand": "5.x"
+    "threenative-asset-mcp": "0.8.0",
+    "threenative-sculpt-mcp": "0.1.1",
+    "zustand": "5.0.14"
   },
   "devDependencies": {
+    "@types/react": "19.2.0",
+    "@types/react-reconciler": "0.32.1",
     "@types/three": "0.185.3",
     "publint": "0.3.22",
+    "react": "19.2.0",
+    "react-reconciler": "0.33.0",
     "tsup": "8.5.1",
     "typescript": "5.9.3",
-    "@threenative/playtest": "0.2.0"
+    "@threenative/playtest": "0.3.1",
+    "threenative-engine-mcp": "0.2.1",
+    "threenative-blender-mcp": "0.1.1"
+  },
+  "peerDependencies": {
+    "@threenative/playtest": ">=0.3.1 <0.4.0",
+    "react": ">=19.2.0 <20",
+    "react-reconciler": ">=0.33.0 <0.34"
+  },
+  "peerDependenciesMeta": {
+    "@threenative/playtest": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-reconciler": {
+      "optional": true
+    }
   },
   "scripts": {
-    "build": "tsup --config tsup.config.ts && publint",
+    "postinstall": "node ./scripts/postinstall.mjs",
+    "build": "node scripts/generate-version.mjs && tsup --config tsup.config.ts && node scripts/bundle-engine-mcp.mjs && node scripts/bundle-blender-mcp.mjs && publint",
     "typecheck": "tsc --noEmit",
-    "test": "pnpm run build"
+    "test": "publint --strict"
   }
 }