@forgeax/game 0.2.4 → 0.3.0

package/docs/asset3d.md

@@ -0,0 +1,157 @@
+# Asset3D local provider and Engine transaction
+
+Asset3D is a project-local integration composed from three separately reviewed
+inputs: the `asset3d-search` provider bundle, the `art-3d-asset-library` workflow
+package, and the released ForgeaX Engine SDK. `@forgeax/game` owns installation,
+configuration, quarantine validation, transaction state, and the handoff to the
+Engine CLI. It does not call an asset service directly and does not implement a
+second importer or Preview server.
+
+> [!IMPORTANT]
+> Asset3D is disabled by default. `install` and ordinary `init` neither contact the
+> internal catalog nor write Asset3D project state. The user must run `asset3d enable`
+> inside an already initialized Engine game.
+
+> [!IMPORTANT]
+> Provider archives are platform-specific release artifacts and are not embedded in
+> the platform-neutral npm package. Installation deliberately returns
+> `provider_platform_mismatch` when an archive target differs from the current host.
+> Each published target therefore needs its own digest, offline verification, MCP
+> handshake, and real service-path evidence.
+
+## Trust and data flow
+
+```mermaid
+flowchart LR
+    B["Digest-pinned local provider bundle"] --> C["Managed digest cache"]
+    K["Exact K0 workflow TGZ"] --> S["Nine project Skill mounts"]
+    C --> M["Project-local stdio MCP"]
+    M --> Q["Private transaction quarantine"]
+    Q --> V["Checked result and file manifest"]
+    V --> A["Atomic asset-directory publication"]
+    A --> E["Exact Engine semantic-only asset add"]
+    E --> R["Engine verify, list, and inspect"]
+    R --> P["Per-file provenance and terminal result"]
+```
+
+The provider is the only network adapter. Installed download authorities are
+lexically exact `http://host:port` or `https://host:port` values: explicit port,
+no path (including `/`), no query, fragment, userinfo, or wildcard. The canonical
+one-to-eight member set is sorted and encoded as compact JSON in
+`AW_DOWNLOAD_ORIGINS`; `.forgeax/asset3d-install.json` records only its SHA-256
+digest. The provider is responsible for enforcing that set on both initial and
+redirect requests.
+
+When installation supplies `--catalog-base-url`, the exact pathless authority is
+written only to the project-local provider environment. It must also appear in
+`--download-origin`. The provider first attempts the bounded `/api/search` route;
+only an explicit `404` or `405` permits a bounded `/api/assets` fallback, and the
+selected asset is fetched through `/api/download/assets`. Other upstream failures
+remain failures rather than silently expanding to a full-catalog scan. Without the
+option, the provider retains the managed AW search adapter.
+
+## Installation ownership
+
+`asset3d enable` probes the default internal catalog with `HEAD /api/assets`. A `2xx`
+response selects `authentication=none`; the current service follows this path and no
+API Key is required. `401` or `403` without an explicit supported authentication
+contract fails closed as `asset3d_api_key_contract_missing`. The plugin never treats
+an Anthropic or other model-provider credential as an Asset3D credential.
+
+The command reuses an exact verified cache when present. Otherwise it downloads the
+platform release archive over HTTPS, follows at most five HTTPS redirects, enforces a
+256 MiB bound, and verifies the pinned SHA-256 before any provisioning. Bundle schema,
+provider commit, platform, Python range, and checked result/receipt schema digests are
+then verified before invoking the offline bundle verifier. Provisioning uses system
+Python 3.11 or 3.12 and the Provider's hash-locked `--provision` flow. The published
+cache is keyed by archive digest under `~/.forgeax/providers/asset3d-search/`.
+
+The low-level `asset3d install --provider-bundle ...` command remains a maintainer
+surface for release production and controlled evidence; users enable the pinned
+release rather than selecting an arbitrary archive.
+
+The installer merges, rather than replaces, the complete `.forgeax/mcp.json` object.
+Unrelated top-level keys and servers survive. The owned entries are local stdio only:
+
+| Server | Tool timeout | Operation bound |
+|:--|--:|--:|
+| `asset3d-search` / `search_asset` | 195,000 ms | provider work 180,000 ms plus cleanup and bridge margin |
+| `forgeax` / `forgeax_run_current_game` | 165,000 ms | Game Plugin build/readiness 150,000 ms plus cleanup and bridge margin |
+| either server, unknown tool | 30,000 ms | project-MCP default |
+
+A conflicting server is not overwritten. `--replace-owned` is accepted only when the
+current entry still matches the prior ownership digest. Configuration, manifests,
+journals, locks, and provenance are private; file publication uses same-directory
+temporary files, file and directory fsync, and atomic rename. Reinstall is byte
+idempotent. Uninstall removes only entries and Skill files that still match owned
+digests, leaving user-modified or unrelated content in place and reporting the
+collision.
+
+The workflow package is projected beneath `art-3d-asset-library/` in exactly these
+mounts unless `--ide` selects a subset:
+
+```text
+.agents/skills                 .claude/skills
+.cursor/skills                 .trae/skills
+.codebuddy/skills              .codeium/windsurf/skills
+.vscode/skills                 .zcode/skills
+.config/opencode/skills
+```
+
+`workbuddy` is an input alias for the `.codebuddy/skills` mount. Every projected file
+has its path, byte count, and digest in the ownership manifest.
+
+## Transaction protocol
+
+1. `asset3d begin` records a private journal with a new execution UUID, query digest,
+   provider identity, exact Engine identity, requested count, and the only allowed
+   quarantine root. It returns the relative `output_dir` for `search_asset`; the
+   provider's `MCP_SHARED_PATH` is the same private `workspace/` root, so declared
+   manifest paths and transaction validation address identical bytes.
+2. The configured provider writes beneath that directory and returns one checked
+   `forgeax.asset3d-search-result/1.0.0` TextContent JSON object.
+3. `asset3d commit --provider-result-stdin` reads at most 1 MiB, validates exact
+   fields/counts/roles/digests/sorted relative paths, and ignores `downloaded_to`.
+4. The transaction rejects symlinks, special files, undeclared files, realpath escape,
+   byte mismatch, or digest mismatch before a project asset write.
+5. A 30-second per-asset lock serializes publication at
+   `assets/3d/ea-3d/<safeAssetId>`. The complete prior directory is preserved as the
+   refresh/rollback snapshot.
+6. With the game root as `cwd`, Game Plugin runs the exact released Engine CLI:
+
+   ```text
+   asset add assets/3d/ea-3d/<safeAssetId> --reimport-policy semantic-only --json
+   asset verify --json
+   asset list --json
+   asset inspect <guid> --json
+   ```
+
+   Each command must produce exactly one newline-terminated, at-most-1-MiB
+   `CommandEnvelope@1.0.0`. Game Plugin does not filter diagnostic stdout into a
+   synthetic success.
+7. Only after Engine readback succeeds does `.forgeax-asset.json` publish the provider
+   commit, origin-set digest, exact Engine version/commit, per-file role/digest/bytes,
+   Engine rows, and catalog readback. An Engine failure restores the whole previous
+   asset directory.
+
+Same provider ID and aggregate digest can reuse the existing directory only when all
+declared live files still match and recorded Engine GUIDs remain in list/inspect
+readback. A changed digest fails unless `--refresh` is explicit. `asset3d doctor`
+restores a stale `committing` snapshot and never reports the interrupted operation as
+successful; `asset3d abort` removes only its transaction quarantine.
+
+## Distribution and evidence boundary
+
+The packed Game Plugin includes the self-contained CLI bundle, existing connector
+Skill, exact K0 TGZ, checked P0 result/receipt schemas, and the immutable URL/digest
+table for supported Provider targets. It does not embed the Provider runtime archive,
+Engine payload, source checkout, credentials, or workspace links. Provider archives
+are separate release assets so a disabled installation downloads nothing. The package
+artifact gate recomputes every embedded predecessor digest.
+
+Controlled external-consumer evidence may establish package installation, raw MCP
+framing, local redirect/ZIP handling, multi-GLB and texture import, reuse, refresh,
+failure rollback, offline recovery, Engine build/Preview health, uninstall, and
+process cleanup. Its status is `PASS_SUPPORTING`. Real provider network results,
+Studio project-MCP discovery, supported-host permission behavior, RuntimeInstance UI,
+visible Play, and final independent acceptance remain outside this repository unit.

package/docs/release-0.3.0.md

@@ -0,0 +1,100 @@
+# `@forgeax/game` 0.3.0 release guide
+
+## User-visible contract
+
+Version `0.3.0` makes the public onboarding flow exactly two commands:
+
+```bash
+npx -y @forgeax/game install --ide codex,cursor,claude
+cd /path/to/a-genuinely-empty-directory
+npx -y @forgeax/game init
+```
+
+Restart or reload an Agent host when the install command asks. `init` creates the
+Engine-owned standalone game in the current directory through the exact
+`@forgeax/engine-sdk@0.1.7` carrier, then installs the same Game Plugin Skill/routing
+contract for every selected host. Users do not run `forgeax new` separately.
+
+Standalone author source is `<game-root>/src`. `.forgeax/games/<slug>` belongs to the
+Studio-hosted project model and is not created by this package.
+
+## Agent authoring and Preview
+
+After `init`, ask the Agent to create a game and open Preview. A valid completion must
+include all of the following:
+
+- concrete `forge.json` id/name and a non-template package name;
+- one coherent README with controls and no Empty package-output residue;
+- a behavior test that imports and exercises a named game-specific state transition or
+  rule; renaming an Empty template test is insufficient;
+- UI mounted under Engine Host `uiRoot` or `#game-ui`; direct `document.body` mutation
+  is rejected because the released standalone Host provides `#game-ui`;
+- a successful `forgeax_run_current_game` response containing
+  `preview.status: ready`, the exact root, Engine release, build digest, Preview
+  instance ID, and the returned loopback URL.
+
+An MCP error, a bare HTTP 200, a PID, an old build, or a localhost URL discovered by
+shell probing is not Preview evidence. When another game owns the Preview port, stop
+that exact verified game first:
+
+```bash
+forgeax-game preview stop --target-dir /path/to/the-running-game
+```
+
+The internal 3D catalog is disabled by default and is not contacted by `install` or
+ordinary `init`. A user opts one initialized project in with:
+
+```bash
+npx -y @forgeax/game asset3d enable
+```
+
+The current `http://21.214.216.8:5180` catalog is network-gated and its body-free
+access probe requires no API Key. In particular, `ANTHROPIC_API_KEY` is unrelated and
+must not be supplied. If the service changes to `401`/`403` without publishing a
+supported authentication contract, enablement fails closed. If
+`asset3d-search/search_asset` is absent, the Agent must report
+`BLOCKED(asset-library-tools-missing)`. Procedural meshes and `forgeax_generate_3d`
+are not evidence that the reusable asset library is available.
+
+## Upgrade and compatibility
+
+- Node.js `>=22.13.0` is required.
+- Existing exact Engine games can rerun `forgeax-game init` to refresh project Skill,
+  routing, and authoring baseline without recreating gameplay source.
+- `install` and `init` are idempotent for already-current owned state.
+- Unknown non-empty directories fail before carrier execution or workspace mutation.
+- Engine-owned `forgeax-engine-*` Skills remain supplied by the selected Engine game;
+  this release changes only the Game Plugin-owned `forgeax-game` Skill and rule.
+
+## Release verification
+
+Before publishing, maintainers must run:
+
+```bash
+bun run typecheck
+bun test test/*.test.ts
+bun run build
+npm pack --json
+bun scripts/check-package-artifact.ts /absolute/path/to/forgeax-game-0.3.0.tgz
+```
+
+Then use the TGZ from a fresh consumer to verify:
+
+1. blank-directory `init`;
+2. identical Skill/rule projection for configured hosts;
+3. changed gameplay with stale template identity/tests fails closed;
+4. Engine build diagnostics before the terminal JSON frame are accepted;
+5. duplicate JSON or post-frame diagnostics fail closed;
+6. Preview failure is returned with MCP `isError: true`;
+7. a different game's occupied port is never reported as the new game's Preview;
+8. after stopping the old verified Preview, the new game returns its own exact
+   root/build/instance identity and loopback URL.
+
+Publishing and npm dist-tag changes remain separate maintainer actions after the MR
+and required checks are approved.
+
+> [!CAUTION]
+> Do not publish the npm dist-tag until every advertised host target has a Provider
+> release artifact at the exact URL pinned by the package and its SHA-256 has been
+> verified. The current source pins only `darwin-arm64`; other targets intentionally
+> fail with `asset3d_provider_target_unreleased`.

package/package.json

@@ -1,16 +1,17 @@
 {
   "packageManager": "bun@1.3.14",
   "name": "@forgeax/game",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "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.",
+  "description": "@forgeax/game — an MCP/CLI connector for exact released ForgeaX Engine games and Engine-owned Preview.",
   "main": "./dist/main.js",
   "bin": {
-    "forgeax-game": "dist/main.js"
+    "forgeax-game": "dist/main.js",
+    "game": "dist/main.js"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22.13.0"
   },
   "publishConfig": {
     "access": "public",
@@ -18,13 +19,16 @@
   },
   "files": [
     "dist",
-    "assets/skills",
+    "assets",
+    "docs/asset3d.md",
+    "docs/release-0.3.0.md",
     "README.md"
   ],
   "scripts": {
     "build": "bun build.mjs",
     "release:check": "bun scripts/check-package-artifact.ts",
     "acceptance": "bun scripts/accept-packed-consumer.ts",
+    "acceptance:asset3d": "bun scripts/accept-asset3d-packed-consumer.ts",
     "release:publish": "bun scripts/publish-package.ts",
     "prepack": "bun build.mjs",
     "typecheck": "tsc --noEmit",
@@ -42,10 +46,16 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@forgeax/game-runtime": "0.3.33"
+    "@forgeax/engine-sdk": "0.1.7",
+    "pnpm": "11.7.0"
   },
   "devDependencies": {
     "@types/bun": "^1.2.0",
     "typescript": "^5.9.2"
-  }
+  },
+  "directories": {
+    "doc": "docs",
+    "test": "test"
+  },
+  "author": ""
 }

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

@@ -1,81 +0,0 @@
-# Verified Engine authoring traps
-
-Each entry below was hit while authoring a working game against this Engine pin and
-confirmed against Engine source. They are the failures that do **not** announce
-themselves: the game keeps running, nothing throws, and only the picture or the input
-is wrong. Check them before debugging anything else.
-
-## Camera `fov` is vertical **radians**
-
-`Camera.fov` is passed unchanged to `mat4.perspective(out, fovYRadians, …)`. Degrees
-silently frame the wrong volume — the scene renders, so it reads as a layout bug.
-
-```ts
-// wrong: 50 radians
-perspective({ fov: 50, aspect, near: 0.1, far: 200 })
-// right
-perspective({ fov: Math.PI / 4, aspect, near: 0.1, far: 200 })
-```
-
-Some doc comments in `camera.ts` show `fov: 60`, and the preview host's own fallback
-camera does the same. Trust `mat4.perspective`, not those examples.
-
-## Keyboard is dead until an InputMap resource exists
-
-The input scan system publishes `INPUT_SNAPSHOT_RESOURCE_KEY` only when an InputMap is
-registered. Without it `hasResource` is false forever and every key read is skipped —
-with no error.
-
-```ts
-const KEY = (key: string) => ({ type: 'key', key } as const);
-world.insertResource(INPUT_MAP_KEY, [
-  { action: 'up', bindings: [KEY('ArrowUp'), KEY('w')] },
-] satisfies ActionConfig[]);
-```
-
-The snapshot also lands only after the first `world.update`, so read
-`createInputSnapshot()` as an empty fallback rather than branching every frame.
-
-## Action readpoints are functions, not properties
-
-```ts
-input.action('up').justPressed    // a function object — always truthy, fires every frame
-input.action('up').justPressed()  // the actual edge
-```
-
-`isPressed`, `justPressed` and `justReleased` are all calls; `strength` is a number.
-
-## Diagnose "nothing renders" with `frustumStats`, not screenshots
-
-`__forgeax.renderer.frustumStats` reports `{ culled, total }`. `culled` equal to
-`total` means the camera is aimed away from the content — an orientation or `fov`
-problem, not a material or mesh problem. `__forgeax` also exposes `world`, `app`
-(with `lastError`) and `renderer.perFramePassNames`.
-
-## An unlit dark material is indistinguishable from the cleared background
-
-`Materials.standard` with a low `baseColor` and no `emissive` renders as near-black on
-a dark `clearColor`, which looks identical to "not rendering". Give static geometry a
-small `emissive` value while bringing a scene up, then tune once it is visibly drawing.
-
-## A pure top-down camera hits the degenerate `up` path
-
-`quat.fromLookAt(out, eye, target, up)` auto-selects an alternative `up` when `up` is
-collinear with the view direction. Prefer a tilted eye, and prefer `fromLookAt` over a
-hand-built axis-angle pitch so the forward/up convention stays the Engine's.
-
-## The entry is `bootstrap(world, ctx)` — world first
-
-The preview host instantiates the default scene, then calls
-`export async function bootstrap(world: World, ctx?: BootstrapContext)`. It only spawns
-its own fallback camera when no game entry resolves, so a game that exports `bootstrap`
-owns the camera.
-
-## `Materials.standard` returns the asset, not a Result
-
-```ts
-world.allocSharedRef<'MaterialAsset', MaterialAsset>('MaterialAsset', Materials.standard({ … }))
-```
-
-The `.value` seen in some `mesh-renderer.ts` examples belongs to
-`engine.assets.catalog(...)`, not to `Materials.standard`.

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

@@ -1,35 +0,0 @@
-# Engine project map
-
-Keep these boundaries in working memory while changing a ForgeaX game.
-
-| Concern | Authoritative location |
-|:--|:--|
-| Game selected by the user | `.forgeax/active-game.json` |
-| Game source and local assets | `.forgeax/games/<slug>/` |
-| Engine SDK declarations, templates, skills, and source | `.forgeax/engine-sdk/` |
-| SDK/runtime identity | `.forgeax/engine-sdk.json` and `forgeax_run_current_game` output |
-| New-game scaffold | ForgeaX server `POST /api/workbench/games` |
-| New-game template authority | `.forgeax/engine-sdk/templates/game-default/` and `.forgeax/engine-sdk/templates/game-empty/` |
-| Engine implementation source | `.forgeax/engine-sdk/source/<package>/src/` |
-| Runtime output owned by this plugin | `.forgeax/logs/runtime/runtime.log` |
-
-`forgeax-game init` calls the server scaffold endpoint. Do not copy the template by
-hand: that would bypass the server's active-game update and instance-root checks.
-
-## Change a game
-
-- Work only under the active game's directory unless the request explicitly changes
-  shared engine behavior.
-- Preserve the existing ECS and lifecycle style in that game; inspect neighboring
-  systems before introducing a new abstraction.
-- Keep asset paths relative to the game and use the existing asset-loading APIs.
-- Do not make subagents independently edit `.forgeax/games/<slug>/src/`; the primary
-  agent owns the source and the hot-reload feedback loop.
-- Use a nearby game under `.forgeax/games/` or `packages/games/` as an example, not as
-  a template to duplicate wholesale.
-
-The plugin materializes the SDK from the same Engine pin used by its selected Runtime package.
-Read the relevant `package.json`, declaration files, and template first. If the bundled
-snapshot lacks an API, inspect the matching implementation source under `source/` rather
-than substituting a guessed import. A successful TypeScript transform does not prove that
-the preview is running the intended Engine.

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

@@ -1,24 +0,0 @@
-# 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.
-
-| Skill id | Covers |
-|:--|:--|
-| `forgeax-engine-app` | ForgeaX application bootstrap and browser frame loop. |
-| `forgeax-engine-assets` | forgeax-engine 资产链路：GUID sidecar → CLI 校验 → vite 折 pack-index → runtime 按 GUID 取 payload, `<packagePath>.<name>` 两段式 identity。 |
-| `forgeax-engine-audio` | ForgeaX realm-neutral ECS audio with Host-owned Web Audio playback. |
-| `forgeax-engine-cli` | forgeax-engine 远程求值：对运行中引擎活实例执行 eval(script) + kubectl 式 plugin bin。 |
-| `forgeax-engine-debug` | forgeax-engine 渲染 / 测试 / CI 实战排查手册——按"症状 → 根因 → 修法"索引已踩过的坑（贴图纯白、 CI 断言全过却 exit 1、worktree 本地假失败、热更新贴图丢失等）。 |
-| `forgeax-engine-debug-draw` | forgeax-engine immediate-mode 调试可视化层：line / sphere / aabb / frustum / arrow / axes 线框 overlay， runtime 自动挂载 app.debugDraw（零配置），low path 手写 RHI flush（自定义 graph / 录帧脚本）。 |
-| `forgeax-engine-ecs` | ForgeaX archetype ECS: define SoA components and systems, attach systems to the Update or FixedUpdate schedule with token-first World APIs, and advance a World through world.update |
-| `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 渲染管线、后处理与 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. |
-| `forgeax-engine-shader` | Author WGSL modules that are consumed by cooked MaterialAsset contracts. |
-| `forgeax-engine-state` | forgeax-engine typed state-machine: defineState creates a StateToken, setNextState requests a transition, state-scoped entities auto-despawn via despawnOnExit/despawnOnEnter, OnEnt |
-| `forgeax-engine-vfx` | ForgeaX code-first GPU VFX: author two WGSL hooks, cook Pack v2, play through ECS, and render executable billboard, mesh, ribbon, trail, or beam output. |

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

@@ -1,26 +0,0 @@
-# Validation loop
-
-Use the narrowest proof that exercises the user's real path, then run the repository
-gate before shipping a product change.
-
-1. Call `forgeax://status` or `forgeax_status_lite` and record the active game.
-2. Run focused tests for the changed code.
-3. Call `forgeax_run_current_game` and use the returned URLs.
-4. For Studio or viewport behavior, open `http://localhost:18920` and exercise the
-   embedded editor path. For standalone Play behavior, exercise the returned Play URL.
-5. Inspect browser errors and the runtime log returned by the tool.
-6. Run `bun fx check` for a normal repository change. Run the owning repository's
-   `bun fx ci` before creating or updating a pull request.
-
-## Evidence boundary
-
-| Result | What it proves |
-|:--|:--|
-| MCP handshake and status | The host can load the plugin and bind the project |
-| Focused tests | The changed code's asserted contract |
-| Play URL responds | The standalone runtime is reachable |
-| Real Studio interaction | The assembled product path works |
-| Full repository gate | The broader source tree remains compatible |
-
-Do not collapse these into one “green” claim. Mark any layer that was not exercised as
-unverified.