@forgeax/game 0.3.5 → 0.3.7

package/README.md

@@ -93,12 +93,17 @@ connector refuses Preview until the Agent has replaced the template identity, ke
 single game README heading, removed the Empty package output name, updated gameplay
 tests, and documented controls. A valid behavior test imports a named game-specific
 state transition or rule and exercises it with an assertion; merely renaming an Empty
-template test does not qualify. Standalone source remains in `<game-root>/src`; the
-Studio-hosted `.forgeax/games/<slug>` layout is never created by this package.
+template test does not qualify. Authoring layout follows the installed Engine and
+`forge.json` (v2 uses `assets/` and `plugins[]`); the Studio-hosted
+`.forgeax/games/<slug>` layout is never created by this package.
 
 Every supported host receives the same packaged `forgeax-game` Skill and routing rule.
 They require UI to mount under the Engine Host `uiRoot` or `#game-ui`. The released
 standalone Host provides `#game-ui`; direct `document.body` mutation is rejected.
+Preview `ready` verifies startup and ownership, not playable behavior. Agents use
+available browser tools for task-relevant interaction checks, or clearly report
+gameplay as unverified and provide manual checks. This guidance does not prescribe
+a game genre, UI implementation, browser brand, or additional blocking gate.
 An explicit request for an existing/library 3D asset requires the separately installed
 project-local `asset3d-search/search_asset` tool. When it is absent, Agents must report
 `BLOCKED(asset-library-tools-missing)` instead of relabeling procedural geometry or

package/assets/asset3d/adapter/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: art-3d-asset-library
+description: Search and import reusable EA/AW assets, including native Pack sources, through the installed ForgeaX game plugin. Use when making games with existing library assets.
+---
+
+# Asset library: Game Plugin adapter
+
+This entry is owned by `@forgeax/game` and matches its pinned Provider. The original
+`@vibegame/art-3d-asset-library@2.0.0` documents remain under `legacy/` for provenance;
+their GLB-only transport and asset-add-only instructions are not this version's contract.
+
+## Search and import
+
+1. Check the project has Asset3D enabled and the current session exposes
+   `asset3d-search/list_asset_candidates` and `search_asset`. Missing tools are a configuration blocker, not
+   an empty library. Do not substitute generated geometry or handwritten HTTP.
+2. Use the same installed `forgeax-game` CLI as the project's `forgeax` MCP server.
+   For a local candidate, use its installed absolute CLI path, not npm's older release.
+   `pnpm exec` can resolve a global CLI when no project dependency exists; verify
+   that executable matches the MCP launcher before starting a transaction.
+   Call `list_asset_candidates` with English queries. Choose a suitable returned
+   `assetId` using its name and format; do not invent an ID or silently take the
+   first candidate. If none fits, refine the query or report no suitable result.
+   Run `forgeax-game asset3d begin --query "<same English query>" --json`.
+3. Call `search_asset` with `queries: [{content: "<same English query>", assetId: "<selected ID>"}]`, returned `execution`, and
+   `output_format: "asset"` to preserve native `.pack.ts` / `.pack.json` when returned.
+   `asset` is the request enum, not `pack.json`. Explicit `glb` requests retain the
+   GLB conversion route. The tool schema must advertise `asset`; otherwise report
+   a Provider version mismatch. Never supply an output directory. Explicit selection
+   uses the calling Agent's judgment and does not need a separate LLM service.
+4. Run `forgeax-game asset3d commit --execution <execution> --json`.
+   The MCP bridge already stores the checked receipt. Inspect per-item failures,
+   `deliveredFormat` in the search result, and the actual returned Engine identities.
+   A successful GLB result is not evidence of a Pack result. If Pack is required but
+   none is returned, report that mismatch rather than renaming or converting source.
+
+## Use the returned assets
+
+- Pack: commit uses the exact Engine build and verified build catalog; use its
+  returned scene/mesh GUIDs. Do not run `asset add` on native Pack source or infer
+  failure solely from a source-only `asset list/inspect` result.
+- GLB: commit uses Engine asset add and catalog readback.
+- Keep the full declared source/helper/texture closure, material parameters and
+  stable identities. Runtime loads cooked assets by GUID. Do not execute downloaded
+  helpers directly. Executable Pack build requires a trusted source; Engine is not
+  itself a security sandbox.
+- Integrate the selected asset into the requested game's normal scene/plugin path,
+  using the installed Engine skills. Choose gameplay, camera and composition to suit
+  the user rather than following a fixed sample game.
+- Call `forgeax_run_current_game`, then verify visible assets and requested input in
+  its verified Preview URL. Search, import, build, and visible gameplay are separate
+  results. Preserve failures, attribution/license gaps and unverified stages.
+
+Asset3D is opt-in. Configure EA using `forgeax-game asset3d enable --library ea
+--ide codex` (choose the requested host). Missing credentials require user setup;
+do not read or expose keys in prompts. Use doctor for diagnosis, not proof of search.

package/assets/asset3d/schemas/result-1.0.0.json

@@ -39,6 +39,9 @@
           {
             "$ref": "#/$defs/success"
           },
+          {
+            "$ref": "#/$defs/packSuccess"
+          },
           {
             "$ref": "#/$defs/error"
           }
@@ -59,7 +62,9 @@
         }
       },
       "then": {
-        "required": ["receipt"]
+        "required": [
+          "receipt"
+        ]
       }
     }
   ],
@@ -75,7 +80,10 @@
       "maxLength": 128,
       "pattern": "^[A-Za-z0-9._-]+$",
       "not": {
-        "enum": [".", ".."]
+        "enum": [
+          ".",
+          ".."
+        ]
       }
     },
     "sha256": {
@@ -91,7 +99,12 @@
     "manifestEntry": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["path", "role", "bytes", "sha256"],
+      "required": [
+        "path",
+        "role",
+        "bytes",
+        "sha256"
+      ],
       "properties": {
         "path": {
           "$ref": "#/$defs/relativePath"
@@ -237,6 +250,112 @@
           "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
         }
       }
+    },
+    "packManifestEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "path",
+        "role",
+        "bytes",
+        "sha256"
+      ],
+      "properties": {
+        "path": {
+          "$ref": "#/$defs/relativePath"
+        },
+        "role": {
+          "enum": [
+            "primary-pack",
+            "auxiliary-pack",
+            "animation",
+            "auxiliary-model",
+            "texture",
+            "metadata"
+          ]
+        },
+        "bytes": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 134217728
+        },
+        "sha256": {
+          "$ref": "#/$defs/sha256"
+        }
+      }
+    },
+    "packSuccess": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "status",
+        "queryIndex",
+        "query",
+        "provider",
+        "providerAssetId",
+        "assetName",
+        "deliveredFormat",
+        "sha256",
+        "bytes",
+        "primaryPack",
+        "manifest",
+        "originSetDigest"
+      ],
+      "properties": {
+        "status": {
+          "const": "ok"
+        },
+        "queryIndex": {
+          "$ref": "#/$defs/queryIndex"
+        },
+        "query": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200
+        },
+        "provider": {
+          "const": "ea-3d"
+        },
+        "providerAssetId": {
+          "$ref": "#/$defs/safeId"
+        },
+        "assetName": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128
+        },
+        "deliveredFormat": {
+          "const": "pack"
+        },
+        "sha256": {
+          "$ref": "#/$defs/sha256"
+        },
+        "bytes": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 268435456
+        },
+        "manifest": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 1024,
+          "items": {
+            "$ref": "#/$defs/packManifestEntry"
+          }
+        },
+        "originSetDigest": {
+          "$ref": "#/$defs/sha256"
+        },
+        "downloaded_to": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512,
+          "pattern": "^(?!/)(?!.*\\\\)(?!.*(?:^|/)\\.{1,2}(?:/|$))(?!.*//)[^\\u0000]+$"
+        },
+        "primaryPack": {
+          "$ref": "#/$defs/relativePath"
+        }
+      }
     }
   }
 }

package/assets/skills/forgeax-game/SKILL.md

@@ -22,14 +22,19 @@ the connector owns Engine CLI execution and Preview lifecycle.
 > [!IMPORTANT]
 > In an empty directory, `forgeax-game init` creates the Engine-owned standalone game
 > through the exact installed carrier. In an existing exact game it refreshes the
-> binding idempotently. Standalone source is `<game-root>/src`; do not create Studio's
-> hosted `.forgeax/games/<slug>` layout.
+> binding idempotently. Follow `forge.json` and the installed Engine's authoring
+> layout (Engine v2 uses `assets/` and `plugins[]`); preserve supported existing
+> layouts rather than moving files to a prescribed directory. Do not create Studio's
+> hosted `.forgeax/games/<slug>` layout inside a standalone game.
 
 ## Edit and verify
 
 1. Make the smallest coherent game-source change using normal file tools. Mount browser
    UI through the Engine Host `uiRoot` or `#game-ui`. The released standalone Host
-   provides `#game-ui`; do not mutate `document.body` directly.
+   provides `#game-ui`; do not mutate `document.body` directly. Resolve Host access
+   and lifecycle from the installed Engine declarations/examples, not a guessed
+   injection name. Check that requested UI is actually mounted; optional chaining
+   that silently skips required UI is not proof it works.
 2. When turning the Empty template into a requested game, also replace the template
    identity in `forge.json`, `package.json`, and README; document controls and keep
    tests aligned. Export at least one named game-specific state transition or rule and
@@ -43,6 +48,14 @@ the connector owns Engine CLI execution and Preview lifecycle.
 6. After a code change, do not reuse an old visual observation as evidence; the new
    build digest and Preview instance must be observed.
 
+Preview `ready` proves startup and ownership, not gameplay or visible UI. For a
+playable-game request, use an available browser tool to check the requested core
+interaction and feedback. Choose checks to fit the game, not a fixed checklist or
+browser brand. If browser access is unavailable, deliver the verified Preview URL
+with gameplay explicitly unverified and short manual checks; do not block useful
+implementation or claim interactions were tested. An Engine-upgrade-only request
+does not require a new gameplay quality review.
+
 ## Reuse 3D assets
 
 - When the user asks for an existing, reusable, library, stock, or licensed 3D asset,