@forgeax/game 0.3.4 → 0.3.5

package/README.md

@@ -10,7 +10,7 @@ runtime.
 
 > [!IMPORTANT]
 > The published package carries `forgeax-game` and scoped `game` binary aliases and resolves the exact
-> `@forgeax/engine-sdk@0.1.7` and `pnpm@11.7.0` dependencies. It has no
+> `@forgeax/engine-sdk@0.1.26` and `pnpm@11.7.0` dependencies. It has no
 > `@forgeax/game-runtime` dependency and no static Preview fallback.
 
 ## Supported flow
@@ -44,9 +44,11 @@ cd ./empty-game-directory
 npx -y @forgeax/game init
 ```
 
-The first command writes only the `forgeax` MCP member in the canonical Codex,
+The first command writes the `forgeax` MCP member in the canonical Codex,
 Cursor, and Claude Code user configs. It preserves unrelated bytes and values,
 reports `CURRENT` on an idempotent rerun, and says which host must restart or reload.
+Existing older package-owned Asset3D MCP entries are also refreshed; absent or
+custom Asset3D entries are not added or overwritten.
 The second command must run from the intended blank directory. It creates the Engine
 game there, binds the exact release identity, and reports the canonical root and
 host-skill result. Existing exact games are read back and bound without recreation;
@@ -60,9 +62,13 @@ npx -y @forgeax/game@latest update --ide codex
 ```
 
 `update` reports the configured transition, for example
-`plugin 0.3.3 -> 0.3.4`. It refreshes configuration, skills, and routing from the
+`plugin 0.3.4 -> 0.3.5`. It refreshes configuration, skills, and routing from the
 package being executed; it does not independently fetch another package.
 
+See [0.3.5 compatibility notes](docs/release-0.3.5.md) before upgrading games pinned
+to older Engine versions. This release recognizes strict v2 manifests without
+requiring the removed `entry` field, but does not migrate game dependencies.
+
 > [!NOTE]
 > Asset3D is optional and **disabled by default**. The two commands above never contact
 > the internal asset catalog, provision the bundled platform Provider, or add

package/dist/main.js

@@ -342,7 +342,7 @@ function engineGameId(root) {
   try {
     const manifest = JSON.parse(readFileSync(join2(root, "forge.json"), "utf8"));
     const pkg = JSON.parse(readFileSync(join2(root, "package.json"), "utf8"));
-    return typeof manifest.id === "string" && SLUG_RE.test(manifest.id) && typeof manifest.entry === "string" && typeof pkg.dependencies?.["@forgeax/engine"] === "string" ? manifest.id : undefined;
+    return typeof manifest.id === "string" && SLUG_RE.test(manifest.id) && (manifest.schemaVersion === "2.0.0" ? typeof manifest.defaultScene === "string" && /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i.test(manifest.defaultScene) : (manifest.schemaVersion === undefined || manifest.schemaVersion === "1.0.0") && typeof manifest.entry === "string") && typeof pkg.dependencies?.["@forgeax/engine"] === "string" ? manifest.id : undefined;
   } catch {
     return;
   }
@@ -710,8 +710,8 @@ import { existsSync as existsSync3, lstatSync as lstatSync3, readFileSync as rea
 import { isAbsolute as isAbsolute2, relative as relative3, resolve as resolve4, sep as sep2 } from "node:path";
 
 // src/engine/constants.ts
-var ENGINE_VERSION = "0.1.7";
-var ENGINE_COMMIT = "984e80ac55b5f4f2afed3211c854b482a4018199";
+var ENGINE_VERSION = "0.1.26";
+var ENGINE_COMMIT = "f3d0db12405e168e4204e32a9cde32e0df8d87ae";
 var ENGINE_SDK_PACKAGE = "@forgeax/engine-sdk";
 var PNPM_VERSION = "11.7.0";
 
@@ -732,7 +732,7 @@ import { createRequire } from "node:module";
 import { basename, delimiter, dirname as dirname4, isAbsolute, relative as relative2, resolve as resolve3, sep } from "node:path";
 import { tmpdir } from "node:os";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
-var SDK_MANIFEST_SCHEMA = "1.6.0";
+var SDK_MANIFEST_SCHEMA = "1.7.0";
 var SDK_CLI_RELATIVE = ["bin", "forgeax.mjs"];
 var CARRIER_ENVIRONMENT_ALLOWLIST = [
   "HOME",
@@ -1690,7 +1690,7 @@ async function startEnginePreview(projectRoot, gameRoot, options = {}) {
     }
     const token = randomBytes(32).toString("hex");
     const previewInstanceId = randomUUID();
-    const child = spawn(process.execPath, [release.cliPath, "preview", "--json"], {
+    const child = spawn(process.execPath, [release.cliPath, "preview", "--port", "0", "--json"], {
       cwd: release.gameRoot,
       detached: true,
       env: { ...process.env, FORGEAX_PREVIEW_INSTANCE_TOKEN: token },
@@ -2946,12 +2946,12 @@ var RELEASE_IDENTITY_MIME = "application/vnd.forgeax.game-release-identity+json"
 var RELEASE_IDENTITY = Object.freeze({
   schema: RELEASE_IDENTITY_SCHEMA,
   gamePackage: "@forgeax/game",
-  gameVersion: "0.3.4",
+  gameVersion: "0.3.5",
   gameBin: "forgeax-game",
   engineSdkPackage: ENGINE_SDK_PACKAGE,
   engineSdkVersion: ENGINE_VERSION,
   engineSourceCommit: ENGINE_COMMIT,
-  carrierIntegrity: "sha512-f3Nz+ZoIOLVjNeKPock46+gwmC1wOWh9TJupQPl25+wZbIN1dJmki5LK6mNhchPxF7fffarbcFWGMqpKHkjQSw==",
+  carrierIntegrity: "sha512-G5ovsbdzkWWeMfFy3MxVk0qcAvWnZxJnlypMGgxFUDaKr3Wv9uVuhPV88LZ1A9mhFJJSfrE1d5R3WvHgulygRQ==",
   sdkManifestDigest: `sha256:${"0".repeat(64)}`,
   sdkTreeDigest: `sha256:${"0".repeat(64)}`,
   fullZipDigest: `sha256:${"0".repeat(64)}`,
@@ -3356,7 +3356,7 @@ function launchSpec(mode) {
   }
   return {
     command: "npx",
-    args: ["-y", "-p", "@forgeax/game@0.3.4", "forgeax-game", "mcp"]
+    args: ["-y", "-p", "@forgeax/game@0.3.5", "forgeax-game", "mcp"]
   };
 }
 function asset3dLaunchSpec(mode) {
@@ -5872,7 +5872,7 @@ async function runDormantAsset3dMcp() {
           result: {
             protocolVersion,
             capabilities: { tools: {} },
-            serverInfo: { name: "asset3d-search", version: "0.3.4" }
+            serverInfo: { name: "asset3d-search", version: "0.3.5" }
           }
         };
       } else if (request2.method === "tools/list") {
@@ -6086,6 +6086,38 @@ async function runAsset3dMcpProxy(projectRoot, launch) {
   });
 }
 
+// src/asset3d/host-config.ts
+function inspectAsset3dHost(client, root) {
+  const launch = asset3dLaunchSpec("npx");
+  const status = inspectConfig(client, root, launch, ASSET3D_SERVER_KEY);
+  if (status.state !== "different")
+    return status;
+  const previous = configuredGameVersion(client, root, ASSET3D_SERVER_KEY);
+  const current = launch.args.find((arg) => arg.startsWith("@forgeax/game@"))?.slice("@forgeax/game@".length);
+  if (!previous || !current || !/^\d+\.\d+\.\d+$/.test(previous) || !/^\d+\.\d+\.\d+$/.test(current))
+    return status;
+  const oldParts = previous.split(".").map(Number);
+  const newParts = current.split(".").map(Number);
+  const differing = oldParts.findIndex((part, index) => part !== newParts[index]);
+  if (differing < 0 || oldParts[differing] >= newParts[differing])
+    return status;
+  const oldLaunch = { ...launch, args: launch.args.map((arg) => arg === `@forgeax/game@${current}` ? `@forgeax/game@${previous}` : arg) };
+  if (inspectConfig(client, root, oldLaunch, ASSET3D_SERVER_KEY).state !== "current")
+    return status;
+  return { ...status, state: "outdated" };
+}
+function refreshAsset3dHost(client, root) {
+  const status = inspectAsset3dHost(client, root);
+  if (status.state === "outdated") {
+    const result = applyConfig(client, root, asset3dLaunchSpec("npx"), ASSET3D_SERVER_KEY);
+    process.stdout.write(`UPDATED ${client.label} Asset3D bridge: ${result.path}
+`);
+  } else if (status.state === "different" || status.state === "invalid") {
+    process.stderr.write(`WARN ${client.label}: existing ${ASSET3D_SERVER_KEY} configuration was preserved; it is not a recognized older package launcher.
+`);
+  }
+}
+
 // src/cli/dispatch.ts
 var HELP = `ForgeaX game development plugin
 
@@ -6190,6 +6222,7 @@ async function installCommand(args) {
     }
     try {
       const result = applyConfig(client, project.root ?? process.cwd(), launch);
+      refreshAsset3dHost(client, project.root ?? process.cwd());
       process.stdout.write(`${result.changed ? "UPDATED" : "CURRENT"} ${client.label}: ${result.path}${result.backup ? ` (backup: ${result.backup})` : ""}
 `);
       if (client.postInstallNote)
@@ -6569,6 +6602,7 @@ async function updateCommand(args) {
   for (const client of configured) {
     const previousVersion = configuredGameVersion(client, root);
     const result = applyConfig(client, root, launch);
+    refreshAsset3dHost(client, root);
     process.stdout.write(`${result.changed ? "UPDATED" : "CURRENT"} ${client.label}: ${result.path} (plugin ${formatVersionTransition(previousVersion)})
 `);
   }
@@ -6691,7 +6725,7 @@ async function asset3dCommand(args) {
         const client = findClient(id);
         if (!client)
           throw new Error(`asset3d_client_invalid: ${id}`);
-        const state = inspectConfig(client, projectRoot, bridge, ASSET3D_SERVER_KEY);
+        const state = inspectAsset3dHost(client, projectRoot);
         if (state.state === "different") {
           throw new Error(`asset3d_client_server_conflict: ${client.label} already has a different ${ASSET3D_SERVER_KEY} entry`);
         }

package/docs/release-0.3.5.md

@@ -0,0 +1,32 @@
+# @forgeax/game 0.3.5
+
+## Compatibility repair
+
+| Boundary | Release behavior |
+|:--|:--|
+| Engine SDK | Exact dependency 0.1.26, commit `f3d0db12405e168e4204e32a9cde32e0df8d87ae` |
+| Project discovery | Recognizes strict `forge.json` v2 with `defaultScene`; does not inject the forbidden legacy `entry` field |
+| SDK manifest | Validates the released 1.7.0 manifest and exact Engine/DevKit identities |
+| Preview | Uses Engine-owned `--port 0` allocation instead of conflicting with another game on port 5173 |
+| Asset3D upgrade | Refreshes existing older package-owned bridges during install/update; preserves custom configurations |
+
+## Install or update
+
+```bash
+npx -y @forgeax/game@0.3.5 install --ide codex,cursor,claude
+# In a genuinely empty game directory:
+npx -y @forgeax/game@0.3.5 init
+```
+
+For an existing Engine 0.1.26 project, run `update --ide codex` with this package,
+then restart the host session. Asset3D remains opt-in with `asset3d enable`.
+
+> [!IMPORTANT]
+> This release pins Engine 0.1.26. It does not silently migrate games using Engine
+> 0.1.7. Keep those games on plugin 0.3.4 until deliberately migrating through the
+> Engine-supported workflow. Do not add `entry` to a v2 manifest to work around the
+> old plugin's project detection.
+
+The plugin must return Engine-owned Preview readiness and matching root/build
+identity. A direct Engine CLI preview or a listening port alone is not MCP
+acceptance. Asset search/import and visible gameplay require separate verification.

package/package.json

@@ -1,7 +1,7 @@
 {
   "packageManager": "bun@1.3.14",
   "name": "@forgeax/game",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "private": false,
   "type": "module",
   "description": "@forgeax/game — an MCP/CLI connector for exact released ForgeaX Engine games and Engine-owned Preview.",
@@ -26,6 +26,7 @@
     "docs/release-0.3.2.md",
     "docs/release-0.3.3.md",
     "docs/release-0.3.4.md",
+    "docs/release-0.3.5.md",
     "README.md"
   ],
   "scripts": {
@@ -51,7 +52,7 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@forgeax/engine-sdk": "0.1.7",
+    "@forgeax/engine-sdk": "0.1.26",
     "pnpm": "11.7.0"
   },
   "devDependencies": {