@forgeax/game 0.2.2 → 0.2.4

package/README.md

@@ -10,7 +10,7 @@ One executable provides both surfaces:
 - `forgeax-game` with no arguments runs the stdio MCP server.
 - `forgeax-game <command>` performs one-time setup and project operations.
 
-The package has one exact runtime dependency, `@forgeax/game-runtime@0.3.32`, and
+The package has one exact runtime dependency, `@forgeax/game-runtime@0.3.33`, and
 externalizes it from the Game bundle.
 
 > [!IMPORTANT]
@@ -133,6 +133,8 @@ one-time actions on every turn.
 | `forgeax://status` | Resource | Preferred read-only project, service, and next-action status |
 | `forgeax_status_lite` | Tool | Status fallback for clients without MCP resource support |
 | `forgeax_run_current_game` | Tool | Build or reuse the active game's static preview, return its URL and health identity, and identify the runtime log file |
+| `forgeax_generate_image` | Tool | Text-to-image, or image-to-image with a local `image`; saves a PNG/JPG into the active game's `assets/` and returns its path |
+| `forgeax_generate_3d` | Tool | Text-to-3D (`prompt`) or image-to-3D (public https `image` URL); runs the async job to completion and saves a `.glb` into `assets/` |
 
 When this plugin cold-starts the managed Runtime, runtime output is written to:
 
@@ -158,6 +160,33 @@ The game SDK is available at `.forgeax/engine-sdk/`. Use its declaration files a
 `templates/game-default` or `templates/game-empty` before writing imports. If an API
 is absent, inspect `source/<package>/src/` instead of guessing.
 
+### Asset generation (LiteLLM)
+
+`forgeax_generate_image` and `forgeax_generate_3d` produce art and 3D assets through a
+LiteLLM gateway and save them into the active game's `assets/` directory, returning the
+project-relative path to reference from game code. Configure via environment:
+
+| Variable | Required | Default |
+|:--|:-:|:--|
+| `FORGEAX_LITELLM_API_KEY` | yes | — (secret; never commit it) |
+| `FORGEAX_LITELLM_BASE_URL` | no | the shared ForgeaX gateway |
+| `FORGEAX_GEN_IMAGE_MODEL` | no | `gemini-3-pro-image` |
+| `FORGEAX_GEN_3D_TEXT_MODEL` | no | `tripo-3d-text` |
+| `FORGEAX_GEN_3D_IMAGE_MODEL` | no | `tripo-3d-image` |
+| `FORGEAX_COS_BUCKET` / `FORGEAX_COS_REGION` | for local image-to-3D | — |
+| `FORGEAX_COS_SECRET_ID` / `FORGEAX_COS_SECRET_KEY` | for local image-to-3D | — (secret; never commit) |
+
+- **Text-to-image / image-to-image**: `forgeax_generate_image({ prompt, image? })`. A
+  local `image` path switches to editing that image with the prompt.
+- **Text-to-3D**: `forgeax_generate_3d({ prompt })` — submits, polls to completion
+  (~1–2 min), and downloads the `.glb`.
+- **Image-to-3D**: `forgeax_generate_3d({ image })`. `image` is a **public https URL**,
+  or a **local file path** when COS is configured — the file is uploaded to the COS
+  bucket and passed to the backend as a short-lived presigned URL (the private bucket
+  stays private; the URL expires within the hour). This makes the "generate a concept
+  image, then turn it into a mesh" flow work end to end. Without COS, only a public URL
+  is accepted, because the 3D endpoint rejects local paths and inline base64.
+
 ## Supported clients
 
 | Client ID | Config path | Scope |
@@ -197,7 +226,7 @@ real Studio-versus-Play validation boundary.
 The published package also carries the host-install metadata needed to expose that
 Skill directly to Codex, Claude Code, Cursor and other configured clients. A harness
 checkout is optional compatibility support, not a user prerequisite. Inside a ForgeaX
-project, `install`, `init`, and `upgrade` refresh it automatically. It can also be
+project, `install`, `init`, and `update` refresh it automatically. It can also be
 installed explicitly:
 
 ```bash

package/assets/skills/forgeax-game/references/engine-skills.md

@@ -1,4 +1,4 @@
-# Engine skills available in Runtime 0.3.32
+# Engine skills available in Runtime 0.3.33
 
 Derived from the Engine skills carried by the installed Runtime package. Invoke only
 ids listed here; Engine package names and skill ids are not interchangeable.
@@ -15,7 +15,7 @@ ids listed here; Engine package names and skill ids are not interchangeable.
 | `forgeax-engine-material` | Build and debug visible ForgeaX materials through the single MaterialAsset route. |
 | `forgeax-engine-math` | forgeax-engine 的纯函数数学库：vec / mat / quat / euler / color 的 out-param 风格函数， 从 Transform.world mat4 读 pose，screenToRay / rayAabbIntersects 做拾取。 |
 | `forgeax-engine-physics` | forgeax-engine 物理：给 entity 挂 Transform + RigidBody + Collider 即被每帧驱动位置。 |
-| `forgeax-engine-render-pipeline` | forgeax-engine 渲染管线与后处理：Camera 内建后处理开关 + skybox + 后处理读相机深度 + 声明式 RenderGraph 替换整条 per-frame 管线。Use when toggling tonemap/bloom/fxaa/ msaa/skybox, reading camera depth in a post-pro |
+| `forgeax-engine-render-pipeline` | forgeax-engine 渲染管线、后处理与 typed RenderGraph。Use when toggling camera effects, authoring a custom RenderPipeline, contributing compute or raster RenderFeature work, or tracing graph  |
 | `forgeax-engine-rhi` | forgeax-engine 底层渲染硬件接口（贡献者向）：spec-aligned 纯接口、opaque handle、 math-free、双实现同发、capability gate。Use when contributing to or debugging the RHI backend, reading capability gates, or tr |
 | `forgeax-engine-rhi-debug` | forgeax-engine 的 RHI 帧录制 + 确定性 replay + 离线 per-draw inspect（RenderDoc 思想）。 |
 | `forgeax-engine-sdk` | Build and verify the portable ForgeaX browser-game SDK ZIP from an Engine checkout. |

package/dist/main.js

@@ -248,7 +248,7 @@ function runStdioServer(spec) {
 }
 
 // src/mcp/forgeax-server.ts
-import { readFileSync as readFileSync6 } from "node:fs";
+import { readFileSync as readFileSync7 } from "node:fs";
 
 // src/status/collect.ts
 import { readFileSync as readFileSync4 } from "node:fs";
@@ -664,6 +664,14 @@ reasoning and game-code edits; the plugin owns ForgeaX Runtime lifecycle and fee
 - Reading runtime errors or engine logs: read the file path returned in
   \`runtime_logs.local_file\` with your own file-reading tool. Log tailing is
   deliberately not an MCP tool — the log is a file, so read it like one.
+- Generating art or 3D assets ("make a sprite", "I need a texture", "generate a
+  model of…"): call \`forgeax_generate_image\` (text-to-image, or image-to-image
+  with a local \`image\`) or \`forgeax_generate_3d\` (text-to-3D via \`prompt\`,
+  image-to-3D via \`image\`). Both save into the active game's \`assets/\` directory
+  and return the project-relative path to reference from code. Image-to-3D accepts a
+  public https URL, or a local file path when COS is configured (it is uploaded and
+  passed as a short-lived presigned URL). They need \`FORGEAX_LITELLM_API_KEY\` (and
+  \`FORGEAX_COS_*\` for local-file image-to-3D) in the environment.
 - Creating a game, switching the active game, installing or upgrading the plugin:
   these are one-time operations and are CLI subcommands, not MCP tools. Run
   \`npx -y -p @forgeax/game forgeax-game <init|use|doctor|devkit|upgrade>\`.
@@ -1652,11 +1660,432 @@ function resolveSlug(root, requested) {
   return { slug, dir };
 }
 
+// src/gen/generate.ts
+import { existsSync as existsSync4, mkdirSync as mkdirSync7, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "node:fs";
+import { basename, extname, join as join7, relative as relative3 } from "node:path";
+
+// src/gen/config.ts
+var DEFAULT_LITELLM_BASE_URL = "http://21.214.33.175:4000";
+var DEFAULT_MODELS = {
+  textToImage: "gemini-3-pro-image",
+  textTo3d: "tripo-3d-text",
+  imageTo3d: "tripo-3d-image"
+};
+function env(name) {
+  const value = process.env[name]?.trim();
+  return value ? value : undefined;
+}
+function resolveLiteLlmConfig() {
+  const baseUrl = (env("FORGEAX_LITELLM_BASE_URL") ?? DEFAULT_LITELLM_BASE_URL).replace(/\/+$/, "");
+  const apiKey = env("FORGEAX_LITELLM_API_KEY");
+  if (!apiKey) {
+    throw new Error("FORGEAX_LITELLM_API_KEY is not set. Export the LiteLLM key so the asset tools can reach the gateway, e.g. `export FORGEAX_LITELLM_API_KEY=sk-...`.");
+  }
+  return {
+    baseUrl,
+    apiKey,
+    models: {
+      textToImage: env("FORGEAX_GEN_IMAGE_MODEL") ?? DEFAULT_MODELS.textToImage,
+      textTo3d: env("FORGEAX_GEN_3D_TEXT_MODEL") ?? DEFAULT_MODELS.textTo3d,
+      imageTo3d: env("FORGEAX_GEN_3D_IMAGE_MODEL") ?? DEFAULT_MODELS.imageTo3d
+    }
+  };
+}
+
+// src/gen/cos.ts
+import { createHash as createHash2, createHmac } from "node:crypto";
+var DEFAULT_EXPIRES_SEC = 3600;
+var SKEW_SEC = 60;
+function env2(name) {
+  const value = process.env[name]?.trim();
+  return value ? value : undefined;
+}
+function resolveCosConfig() {
+  const bucket = env2("FORGEAX_COS_BUCKET");
+  const region = env2("FORGEAX_COS_REGION");
+  const secretId = env2("FORGEAX_COS_SECRET_ID");
+  const secretKey = env2("FORGEAX_COS_SECRET_KEY");
+  if (!bucket || !region || !secretId || !secretKey)
+    return;
+  return { bucket, region, secretId, secretKey };
+}
+function cosHost(cfg) {
+  return `${cfg.bucket}.cos.${cfg.region}.myqcloud.com`;
+}
+function rfc3986(value) {
+  return encodeURIComponent(value).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+function formatKv(map) {
+  const lowered = {};
+  for (const [k, v] of Object.entries(map))
+    lowered[k.toLowerCase()] = v;
+  const keys = Object.keys(lowered).sort();
+  return {
+    serialized: keys.map((k) => `${rfc3986(k)}=${rfc3986(lowered[k])}`).join("&"),
+    keyList: keys.map((k) => rfc3986(k)).join(";")
+  };
+}
+function buildAuthorization(cfg, opts) {
+  const start = opts.nowSec - SKEW_SEC;
+  const end = opts.nowSec + (opts.expiresSec ?? DEFAULT_EXPIRES_SEC);
+  const signTime = `${start};${end}`;
+  const signKey = createHmac("sha1", cfg.secretKey).update(signTime).digest("hex");
+  const { serialized: paramStr, keyList: paramList } = formatKv(opts.params ?? {});
+  const { serialized: headerStr, keyList: headerList } = formatKv(opts.headers ?? {});
+  const httpString = `${opts.method.toLowerCase()}
+${opts.pathname}
+${paramStr}
+${headerStr}
+`;
+  const httpStringSha1 = createHash2("sha1").update(httpString).digest("hex");
+  const stringToSign = `sha1
+${signTime}
+${httpStringSha1}
+`;
+  const signature = createHmac("sha1", signKey).update(stringToSign).digest("hex");
+  return [
+    "q-sign-algorithm=sha1",
+    `q-ak=${cfg.secretId}`,
+    `q-sign-time=${signTime}`,
+    `q-key-time=${signTime}`,
+    `q-header-list=${headerList}`,
+    `q-url-param-list=${paramList}`,
+    `q-signature=${signature}`
+  ].join("&");
+}
+function presignGetUrl(cfg, key, expiresSec = DEFAULT_EXPIRES_SEC, nowSec = Math.floor(Date.now() / 1000)) {
+  const pathname = key.startsWith("/") ? key : `/${key}`;
+  const auth = buildAuthorization(cfg, { method: "get", pathname, nowSec, expiresSec });
+  return `https://${cosHost(cfg)}${pathname}?${auth}`;
+}
+async function uploadObject(cfg, key, bytes, contentType) {
+  const host = cosHost(cfg);
+  const pathname = key.startsWith("/") ? key : `/${key}`;
+  const auth = buildAuthorization(cfg, {
+    method: "put",
+    pathname,
+    headers: { host },
+    nowSec: Math.floor(Date.now() / 1000),
+    expiresSec: 600
+  });
+  const ctrl = new AbortController;
+  const timer = setTimeout(() => ctrl.abort(), 60000);
+  try {
+    const res = await fetch(`https://${host}${pathname}`, {
+      method: "PUT",
+      headers: { authorization: auth, "content-type": contentType },
+      body: bytes,
+      signal: ctrl.signal
+    });
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      throw new Error(`COS upload of ${key} failed: ${res.status} ${res.statusText}${body ? ` — ${body.slice(0, 400)}` : ""}`);
+    }
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function uploadAndPresign(cfg, key, bytes, contentType, expiresSec = DEFAULT_EXPIRES_SEC) {
+  await uploadObject(cfg, key, bytes, contentType);
+  return presignGetUrl(cfg, key, expiresSec);
+}
+
+// src/gen/litellm.ts
+var TASK_TIMEOUT_MS = 420000;
+var POLL_INTERVAL_MS = 3000;
+var REQUEST_TIMEOUT_MS = 60000;
+function authHeaders(cfg) {
+  return { authorization: `Bearer ${cfg.apiKey}` };
+}
+async function request(url, init, timeoutMs = REQUEST_TIMEOUT_MS) {
+  const ctrl = new AbortController;
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, { ...init, signal: ctrl.signal });
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      throw new Error(`LiteLLM ${init.method ?? "GET"} ${url} failed: ${res.status} ${res.statusText}${body ? ` — ${body.slice(0, 600)}` : ""}`);
+    }
+    return res;
+  } catch (err) {
+    if (err instanceof Error && err.name === "AbortError") {
+      throw new Error(`LiteLLM request timed out after ${timeoutMs}ms: ${url}`);
+    }
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function decodeImagePayload(item) {
+  if (!item)
+    return {};
+  const b64 = typeof item.b64_json === "string" ? item.b64_json : undefined;
+  const url = typeof item.url === "string" ? item.url : undefined;
+  return { b64, url };
+}
+function sniffImageExt(bytes) {
+  if (bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255)
+    return "jpg";
+  return "png";
+}
+async function materializeImage(payload) {
+  if (payload.b64) {
+    const bytes = new Uint8Array(Buffer.from(payload.b64, "base64"));
+    return { bytes, ext: sniffImageExt(bytes) };
+  }
+  if (payload.url) {
+    const res = await request(payload.url, { method: "GET" });
+    const bytes = new Uint8Array(await res.arrayBuffer());
+    return { bytes, ext: sniffImageExt(bytes) };
+  }
+  throw new Error("LiteLLM image response contained neither b64_json nor url.");
+}
+async function generateImage(cfg, opts) {
+  const res = await request(`${cfg.baseUrl}/v1/images/generations`, {
+    method: "POST",
+    headers: { ...authHeaders(cfg), "content-type": "application/json" },
+    body: JSON.stringify({ model: opts.model, prompt: opts.prompt, n: 1, ...opts.size ? { size: opts.size } : {} })
+  });
+  const json = await res.json();
+  return materializeImage(decodeImagePayload(json.data?.[0]));
+}
+async function editImage(cfg, opts) {
+  const form = new FormData;
+  form.set("model", opts.model);
+  form.set("prompt", opts.prompt);
+  form.set("n", "1");
+  form.set("image", new Blob([opts.image]), opts.filename);
+  const res = await request(`${cfg.baseUrl}/v1/images/edits`, {
+    method: "POST",
+    headers: authHeaders(cfg),
+    body: form
+  });
+  const json = await res.json();
+  return materializeImage(decodeImagePayload(json.data?.[0]));
+}
+async function submit3dTask(cfg, body) {
+  const res = await request(`${cfg.baseUrl}/v1/3d/generations`, {
+    method: "POST",
+    headers: { ...authHeaders(cfg), "content-type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  const json = await res.json();
+  if (!json.id)
+    throw new Error(`LiteLLM 3D submit returned no task id: ${JSON.stringify(json).slice(0, 400)}`);
+  return json.id;
+}
+async function poll3dTask(cfg, id, onProgress) {
+  const deadline = Date.now() + TASK_TIMEOUT_MS;
+  for (;; ) {
+    const res = await request(`${cfg.baseUrl}/v1/3d/tasks/${encodeURIComponent(id)}`, {
+      method: "GET",
+      headers: authHeaders(cfg)
+    });
+    const state = await res.json();
+    if (typeof state.progress === "number")
+      onProgress?.(state.progress);
+    const status = state.status?.toLowerCase();
+    if (status === "succeeded" || status === "success" || status === "completed")
+      return state;
+    if (status === "failed" || status === "error" || status === "cancelled") {
+      throw new Error(`LiteLLM 3D task ${id} ${state.status}${state.error ? `: ${JSON.stringify(state.error).slice(0, 300)}` : ""}`);
+    }
+    if (Date.now() > deadline) {
+      throw new Error(`LiteLLM 3D task ${id} did not finish within ${TASK_TIMEOUT_MS / 1000}s (last status: ${state.status}).`);
+    }
+    await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+  }
+}
+async function downloadMesh(state) {
+  const assets = (state.data ?? []).map((d) => ({
+    url: typeof d.url === "string" ? d.url : undefined,
+    type: typeof d.type === "string" ? d.type : "",
+    format: typeof d.format === "string" ? d.format : ""
+  }));
+  const mesh = assets.find((a) => a.url && (a.type === "mesh" || /\.(glb|gltf|obj|fbx|usdz)/i.test(a.url ?? ""))) ?? assets.find((a) => a.url);
+  if (!mesh?.url)
+    throw new Error(`LiteLLM 3D task ${state.id} completed with no downloadable mesh asset.`);
+  const res = await request(mesh.url, { method: "GET" });
+  const bytes = new Uint8Array(await res.arrayBuffer());
+  const ext = mesh.format || (mesh.url.match(/\.([a-z0-9]+)(?:\?|$)/i)?.[1] ?? "glb").toLowerCase();
+  return { bytes, ext, assetType: mesh.type || "mesh" };
+}
+async function generate3dFromText(cfg, opts) {
+  const id = await submit3dTask(cfg, { model: opts.model, prompt: opts.prompt });
+  return downloadMesh(await poll3dTask(cfg, id, opts.onProgress));
+}
+async function generate3dFromImageUrl(cfg, opts) {
+  const id = await submit3dTask(cfg, { model: opts.model, image_url: opts.imageUrl, ...opts.prompt ? { prompt: opts.prompt } : {} });
+  return downloadMesh(await poll3dTask(cfg, id, opts.onProgress));
+}
+
+// src/gen/generate.ts
+function assetsDirFor(cwd, explicitGame) {
+  const binding = resolveProject(cwd);
+  if (!binding.root) {
+    throw new Error(`No ForgeaX project found from ${binding.searchedFrom}. Run \`forgeax-game init --game <slug>\` in the workspace first, or pass \`game\`/\`target_dir\`.`);
+  }
+  const slug = explicitGame?.trim() || activeGame(binding.root);
+  if (!slug) {
+    const games = listGames(binding.root);
+    throw new Error(`No active game to save the asset into.${games.length ? ` Pass one of: ${games.join(", ")}` : " Create one with `forgeax-game init --game <slug>`."}`);
+  }
+  const dir = gameDir(binding.root, slug);
+  if (!dir)
+    throw new Error(`Game ${JSON.stringify(slug)} not found in this project.`);
+  const assets = join7(dir, "assets");
+  mkdirSync7(assets, { recursive: true });
+  return { dir: assets, root: binding.root, slug };
+}
+function safeStem(preferred, fallback) {
+  const source = (preferred ?? fallback).toLowerCase();
+  const stem = source.replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 48);
+  return stem || "asset";
+}
+function uniquePath(dir, stem, ext) {
+  let candidate = join7(dir, `${stem}.${ext}`);
+  for (let i = 1;existsSync4(candidate); i += 1)
+    candidate = join7(dir, `${stem}-${i}.${ext}`);
+  return candidate;
+}
+function logProgress(label) {
+  let last = -1;
+  return (pct) => {
+    const step = Math.floor(pct / 10);
+    if (step !== last) {
+      last = step;
+      process.stderr.write(`[forgeax] ${label}: ${pct}%
+`);
+    }
+  };
+}
+var GAME_PROPERTY = {
+  game: {
+    type: "string",
+    description: "Game slug to save the asset into. Defaults to the active game."
+  },
+  target_dir: {
+    type: "string",
+    description: "Directory to resolve the ForgeaX project from. Defaults to the server working directory."
+  },
+  name: {
+    type: "string",
+    description: "Base file name for the saved asset (without extension). Defaults to a slug of the prompt."
+  }
+};
+var GENERATE_IMAGE_SCHEMA = {
+  type: "object",
+  properties: {
+    prompt: { type: "string", description: "What to draw. Required for both text-to-image and editing an input image." },
+    image: {
+      type: "string",
+      description: "Optional local image path to edit (image-to-image). When set, the prompt describes the desired change."
+    },
+    model: { type: "string", description: "Override the image model. Defaults to the configured text-to-image model." },
+    ...GAME_PROPERTY
+  },
+  required: ["prompt"],
+  additionalProperties: false
+};
+var GENERATE_3D_SCHEMA = {
+  type: "object",
+  properties: {
+    prompt: { type: "string", description: "Text description for text-to-3D. Provide this or `image`." },
+    image: {
+      type: "string",
+      description: "Image for image-to-3D: a public https URL, or a local file path when COS is configured (FORGEAX_COS_*) — local files are uploaded to COS and passed as a short-lived presigned URL. Without COS, only a public URL works."
+    },
+    model: { type: "string", description: "Override the 3D model. Defaults to the configured text/image-to-3D model." },
+    ...GAME_PROPERTY
+  },
+  additionalProperties: false
+};
+var HTTP_URL_RE = /^https?:\/\//i;
+async function generateImageTool(args, cwd) {
+  const prompt = typeof args.prompt === "string" ? args.prompt.trim() : "";
+  if (!prompt)
+    throw new Error("`prompt` is required.");
+  const cfg = resolveLiteLlmConfig();
+  const targetDir = typeof args.target_dir === "string" ? args.target_dir : cwd;
+  const { dir, root, slug } = assetsDirFor(targetDir, typeof args.game === "string" ? args.game : undefined);
+  const model = typeof args.model === "string" && args.model.trim() ? args.model.trim() : cfg.models.textToImage;
+  let result;
+  let mode;
+  const inputImage = typeof args.image === "string" ? args.image.trim() : "";
+  if (inputImage) {
+    if (HTTP_URL_RE.test(inputImage)) {
+      throw new Error("Image-to-image expects a LOCAL image path, not a URL. Download it first, then pass the path.");
+    }
+    if (!existsSync4(inputImage))
+      throw new Error(`Input image not found: ${inputImage}`);
+    const bytes = new Uint8Array(readFileSync6(inputImage));
+    result = await editImage(cfg, { model, prompt, image: bytes, filename: basename(inputImage) });
+    mode = "image-to-image";
+  } else {
+    result = await generateImage(cfg, { model, prompt });
+    mode = "text-to-image";
+  }
+  const stem = safeStem(typeof args.name === "string" ? args.name : undefined, prompt);
+  const outPath = uniquePath(dir, stem, result.ext);
+  writeFileSync4(outPath, result.bytes);
+  const rel = relative3(root, outPath);
+  return `Saved ${mode} asset to \`${rel}\` (game: ${slug}, model: ${model}, ${result.bytes.length} bytes). Reference it from game code by this path.`;
+}
+function imageContentType(path) {
+  const ext = extname(path).toLowerCase();
+  if (ext === ".jpg" || ext === ".jpeg")
+    return "image/jpeg";
+  if (ext === ".webp")
+    return "image/webp";
+  return "image/png";
+}
+async function resolveImageUrlFor3d(image, slug) {
+  if (HTTP_URL_RE.test(image))
+    return image;
+  if (!existsSync4(image))
+    throw new Error(`Input image not found: ${image}`);
+  const cos = resolveCosConfig();
+  if (!cos) {
+    throw new Error("Image-to-3D from a local file needs COS configured (FORGEAX_COS_BUCKET/REGION/SECRET_ID/SECRET_KEY) so the image can be hosted for the backend to fetch. Alternatively pass a public https URL.");
+  }
+  const bytes = new Uint8Array(readFileSync6(image));
+  const stem = safeStem(basename(image, extname(image)), "input");
+  const ext = (extname(image).replace(".", "") || "png").toLowerCase();
+  const key = `forgeax/${slug}/${stem}-${Date.now()}.${ext}`;
+  return uploadAndPresign(cos, key, bytes, imageContentType(image));
+}
+async function generate3dTool(args, cwd) {
+  const prompt = typeof args.prompt === "string" ? args.prompt.trim() : "";
+  const image = typeof args.image === "string" ? args.image.trim() : "";
+  if (!prompt && !image)
+    throw new Error("Provide `prompt` (text-to-3D) or `image` (image-to-3D).");
+  const cfg = resolveLiteLlmConfig();
+  const targetDir = typeof args.target_dir === "string" ? args.target_dir : cwd;
+  const { dir, root, slug } = assetsDirFor(targetDir, typeof args.game === "string" ? args.game : undefined);
+  let result;
+  let mode;
+  if (image) {
+    const imageUrl = await resolveImageUrlFor3d(image, slug);
+    const model = typeof args.model === "string" && args.model.trim() ? args.model.trim() : cfg.models.imageTo3d;
+    result = await generate3dFromImageUrl(cfg, { model, imageUrl, prompt: prompt || undefined, onProgress: logProgress("image-to-3D") });
+    mode = "image-to-3D";
+  } else {
+    const model = typeof args.model === "string" && args.model.trim() ? args.model.trim() : cfg.models.textTo3d;
+    result = await generate3dFromText(cfg, { model, prompt, onProgress: logProgress("text-to-3D") });
+    mode = "text-to-3D";
+  }
+  const stem = safeStem(typeof args.name === "string" ? args.name : undefined, prompt || "model");
+  const outPath = uniquePath(dir, stem, result.ext);
+  writeFileSync4(outPath, result.bytes);
+  const rel = relative3(root, outPath);
+  return `Saved ${mode} ${result.assetType} to \`${rel}\` (game: ${slug}, ${result.bytes.length} bytes). Reference it from game code by this path.`;
+}
+
 // src/mcp/forgeax-server.ts
 function packageVersion() {
-  for (const relative3 of ["../package.json", "../../package.json"]) {
+  for (const relative4 of ["../package.json", "../../package.json"]) {
     try {
-      const version = JSON.parse(readFileSync6(new URL(relative3, import.meta.url), "utf8")).version;
+      const version = JSON.parse(readFileSync7(new URL(relative4, import.meta.url), "utf8")).version;
       if (version)
         return version;
     } catch {}
@@ -1698,18 +2127,30 @@ function createForgeaxMcpServer() {
         description: 'Build, preview, reload, or verify the active game. One call covers what the user means by "run it", "let me see it", "reload", or "does it work": it installs the selected Runtime when needed, builds or reuses a static preview, returns a preview URL to open, and reports the Runtime log file. Read an available `runtime_logs.local_file` with your own file tool — log tailing is intentionally not a tool. Call this after a requested game change, not for ordinary edits the user has not asked to see.',
         inputSchema: RUN_TOOL_SCHEMA,
         run: async (args, ctx) => runCurrentGame(args, ctx.cwd)
+      },
+      {
+        name: "forgeax_generate_image",
+        description: "Generate a game image asset from a text prompt (text-to-image), or edit a local image when `image` is set (image-to-image). Saves the PNG/JPG into the active game's `assets/` directory and returns its project-relative path to reference from game code. Backed by the ForgeaX LiteLLM gateway; requires FORGEAX_LITELLM_API_KEY. Use when the user asks for a sprite, texture, icon, background, or concept art.",
+        inputSchema: GENERATE_IMAGE_SCHEMA,
+        run: async (args, ctx) => generateImageTool(args, ctx.cwd)
+      },
+      {
+        name: "forgeax_generate_3d",
+        description: "Generate a 3D model (.glb) for the game. Provide `prompt` for text-to-3D, or `image` for image-to-3D — a public https URL, or a local file path when COS is configured (the file is uploaded and passed as a short-lived presigned URL). Runs the async generation to completion (~1–2 min) and saves the mesh into the active game's `assets/` directory, returning its project-relative path. Backed by the ForgeaX LiteLLM gateway; requires FORGEAX_LITELLM_API_KEY (and FORGEAX_COS_* for local-file image-to-3D).",
+        inputSchema: GENERATE_3D_SCHEMA,
+        run: async (args, ctx) => generate3dTool(args, ctx.cwd)
       }
     ]
   };
 }
 
 // src/cli/dispatch.ts
-import { existsSync as existsSync5, readFileSync as readFileSync8, rmSync as rmSync2, writeFileSync as writeFileSync5 } from "node:fs";
-import { basename, join as join8 } from "node:path";
+import { existsSync as existsSync6, readFileSync as readFileSync9, rmSync as rmSync2, writeFileSync as writeFileSync6 } from "node:fs";
+import { basename as basename2, join as join9 } from "node:path";
 
 // src/install/clients.ts
 import { homedir as homedir3 } from "node:os";
-import { join as join7, resolve as resolve4 } from "node:path";
+import { join as join8, resolve as resolve4 } from "node:path";
 var HOME = homedir3();
 var CLIENTS = [
   {
@@ -1717,7 +2158,7 @@ var CLIENTS = [
     label: "Codex CLI",
     format: "toml",
     scope: "user",
-    path: () => join7(HOME, ".codex", "config.toml"),
+    path: () => join8(HOME, ".codex", "config.toml"),
     commandShape: "split",
     postInstallNote: "Restart Codex, then run /mcp to confirm the server is connected."
   },
@@ -1726,7 +2167,7 @@ var CLIENTS = [
     label: "Claude Code",
     format: "json",
     scope: "user",
-    path: () => join7(HOME, ".claude.json"),
+    path: () => join8(HOME, ".claude.json"),
     serverMapKey: ["mcpServers"],
     commandShape: "split",
     postInstallNote: "Restart Claude Code, then run /mcp to confirm the server is connected."
@@ -1736,7 +2177,7 @@ var CLIENTS = [
     label: "Cursor",
     format: "json",
     scope: "user",
-    path: () => join7(HOME, ".cursor", "mcp.json"),
+    path: () => join8(HOME, ".cursor", "mcp.json"),
     serverMapKey: ["mcpServers"],
     commandShape: "split",
     postInstallNote: "Reload Cursor, then check Settings > MCP."
@@ -1746,7 +2187,7 @@ var CLIENTS = [
     label: "Trae (project)",
     format: "json",
     scope: "project",
-    path: (projectRoot) => join7(projectRoot, ".trae", "mcp.json"),
+    path: (projectRoot) => join8(projectRoot, ".trae", "mcp.json"),
     serverMapKey: ["mcpServers"],
     commandShape: "split",
     postInstallNote: "Reload Trae, then check the project MCP server list."
@@ -1757,7 +2198,7 @@ var CLIENTS = [
     label: "CodeBuddy / WorkBuddy",
     format: "json",
     scope: "user",
-    path: () => join7(HOME, ".codebuddy", ".mcp.json"),
+    path: () => join8(HOME, ".codebuddy", ".mcp.json"),
     serverMapKey: ["mcpServers"],
     commandShape: "split",
     postInstallNote: "Restart CodeBuddy or WorkBuddy, then run /mcp to confirm the server is connected."
@@ -1767,7 +2208,7 @@ var CLIENTS = [
     label: "Windsurf",
     format: "json",
     scope: "user",
-    path: () => join7(HOME, ".codeium", "windsurf", "mcp_config.json"),
+    path: () => join8(HOME, ".codeium", "windsurf", "mcp_config.json"),
     serverMapKey: ["mcpServers"],
     commandShape: "split",
     postInstallNote: "Reload Windsurf to pick up the new server."
@@ -1777,7 +2218,7 @@ var CLIENTS = [
     label: "VS Code (workspace)",
     format: "json",
     scope: "project",
-    path: (projectRoot) => join7(projectRoot, ".vscode", "mcp.json"),
+    path: (projectRoot) => join8(projectRoot, ".vscode", "mcp.json"),
     serverMapKey: ["servers"],
     commandShape: "split",
     postInstallNote: 'Open .vscode/mcp.json and click Start, or run "MCP: List Servers".'
@@ -1787,7 +2228,7 @@ var CLIENTS = [
     label: "ZCode",
     format: "json",
     scope: "user",
-    path: () => join7(HOME, ".zcode", "cli", "config.json"),
+    path: () => join8(HOME, ".zcode", "cli", "config.json"),
     serverMapKey: ["mcp", "servers"],
     commandShape: "split",
     postInstallNote: "Start a new ZCode session, then run /mcp status to confirm the server is connected."
@@ -1797,7 +2238,7 @@ var CLIENTS = [
     label: "OpenCode",
     format: "json",
     scope: "user",
-    path: () => join7(HOME, ".config", "opencode", "opencode.json"),
+    path: () => join8(HOME, ".config", "opencode", "opencode.json"),
     serverMapKey: ["mcp"],
     commandShape: "argv",
     extraEntryFields: { type: "local", enabled: true },
@@ -1821,7 +2262,7 @@ function launchSpec(mode) {
 }
 
 // src/install/write-config.ts
-import { copyFileSync as copyFileSync2, existsSync as existsSync4, mkdirSync as mkdirSync7, readFileSync as readFileSync7, writeFileSync as writeFileSync4 } from "node:fs";
+import { copyFileSync as copyFileSync2, existsSync as existsSync5, mkdirSync as mkdirSync8, readFileSync as readFileSync8, writeFileSync as writeFileSync5 } from "node:fs";
 import { dirname as dirname4 } from "node:path";
 
 // src/install/toml-section.ts
@@ -2031,11 +2472,11 @@ function mergeTomlConfig(existing, entry) {
 }
 function inspectConfig(spec, projectRoot, launch) {
   const path = spec.path(projectRoot);
-  if (!existsSync4(path))
+  if (!existsSync5(path))
     return { path, state: "missing" };
   let existing;
   try {
-    existing = readFileSync7(path, "utf8");
+    existing = readFileSync8(path, "utf8");
     if (spec.format === "toml") {
       const header = `mcp_servers.${SERVER_KEY}`;
       if (!hasTomlTable(existing, header)) {
@@ -2080,25 +2521,25 @@ function inspectConfig(spec, projectRoot, launch) {
 }
 function applyConfig(spec, projectRoot, launch) {
   const path = spec.path(projectRoot);
-  const existing = existsSync4(path) ? readFileSync7(path, "utf8") : undefined;
+  const existing = existsSync5(path) ? readFileSync8(path, "utf8") : undefined;
   const entry = buildEntry(spec, launch);
   const merged = spec.format === "toml" ? mergeTomlConfig(existing, entry) : mergeJsonConfig(existing, spec, entry);
   if (!merged.changed)
     return { path, changed: false };
-  mkdirSync7(dirname4(path), { recursive: true });
+  mkdirSync8(dirname4(path), { recursive: true });
   let backup;
   if (existing !== undefined) {
     backup = `${path}.bak.latest`;
     copyFileSync2(path, backup);
   }
-  writeFileSync4(path, merged.content);
+  writeFileSync5(path, merged.content);
   return { path, changed: true, ...backup ? { backup } : {} };
 }
 function removeConfig(spec, projectRoot) {
   const path = spec.path(projectRoot);
-  if (!existsSync4(path))
+  if (!existsSync5(path))
     return { path, changed: false };
-  const existing = readFileSync7(path, "utf8");
+  const existing = readFileSync8(path, "utf8");
   let content;
   if (spec.format === "toml") {
     content = removeTomlTable(existing, `mcp_servers.${SERVER_KEY}`);
@@ -2126,7 +2567,7 @@ function removeConfig(spec, projectRoot) {
     return { path, changed: false };
   const backup = `${path}.bak.latest`;
   copyFileSync2(path, backup);
-  writeFileSync4(path, content);
+  writeFileSync5(path, content);
   return { path, changed: true, backup };
 }
 
@@ -2330,23 +2771,23 @@ function requireProject() {
   return project.root;
 }
 function updateAgentsFile(root) {
-  const path = join8(root, "AGENTS.md");
-  const existing = existsSync5(path) ? readFileSync8(path, "utf8") : undefined;
+  const path = join9(root, "AGENTS.md");
+  const existing = existsSync6(path) ? readFileSync9(path, "utf8") : undefined;
   const content = upsertBlock(existing, ROUTING_TEXT);
   if (content === existing)
     return { path, changed: false };
-  writeFileSync5(path, content);
+  writeFileSync6(path, content);
   return { path, changed: true };
 }
 function removeAgentsBlock(root) {
-  const path = join8(root, "AGENTS.md");
-  if (!existsSync5(path))
+  const path = join9(root, "AGENTS.md");
+  if (!existsSync6(path))
     return { path, changed: false };
-  const existing = readFileSync8(path, "utf8");
+  const existing = readFileSync9(path, "utf8");
   const content = removeBlock(existing);
   if (content === existing)
     return { path, changed: false };
-  writeFileSync5(path, content);
+  writeFileSync6(path, content);
   return { path, changed: true };
 }
 async function apiPost(path, body) {
@@ -2425,7 +2866,7 @@ async function installCommand(args) {
   return failures === 0 ? 0 : 1;
 }
 function defaultSlug(root) {
-  const raw = basename(root).toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
+  const raw = basename2(root).toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
   return SLUG_RE.test(raw) ? raw : "my-game";
 }
 var INIT_USAGE = "usage: forgeax-game init [--game <slug>] [--ide codex,claude,cursor,...]";
@@ -2581,7 +3022,7 @@ async function uninstallCommand(args) {
     const agents = removeAgentsBlock(root);
     process.stdout.write(`${agents.changed ? "REMOVED" : "ABSENT "} routing block: ${agents.path}
 `);
-    process.stdout.write(`KEPT    your games and project metadata: ${join8(root, ".forgeax")}
+    process.stdout.write(`KEPT    your games and project metadata: ${join9(root, ".forgeax")}
 `);
   } else {
     process.stdout.write(`INFO  no ForgeaX project bound; only client configuration was touched.

package/package.json

@@ -1,6 +1,7 @@
 {
+  "packageManager": "bun@1.3.14",
   "name": "@forgeax/game",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "private": false,
   "type": "module",
   "description": "@forgeax/game \u2014 ForgeaX game development as a plugin for MCP-capable agent CLIs (Codex, Claude Code, Cursor, Trae, ZCode, OpenCode, WorkBuddy). Single binary, dual mode: no args = stdio MCP server, subcommand = CLI.",
@@ -41,7 +42,7 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@forgeax/game-runtime": "0.3.32"
+    "@forgeax/game-runtime": "0.3.33"
   },
   "devDependencies": {
     "@types/bun": "^1.2.0",