@vgai/engine 0.2.0 → 0.4.0-canary.20260715.0

package/schemas/vgai-game.schema.json

@@ -0,0 +1,383 @@
+{
+  "$comment": "AUTO-GENERATED by scripts/generate-schema.ts — do not edit manually",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "description": "Optional JSON Schema URI for editor autocomplete and validation",
+      "type": "string"
+    },
+    "manifestVersion": {
+      "type": "number",
+      "const": 2,
+      "description": "Manifest file format version (v2 clean roots)"
+    },
+    "name": {
+      "type": "string",
+      "description": "Game display name"
+    },
+    "appId": {
+      "description": "Stable reverse-domain application id used by packaged targets",
+      "type": "string"
+    },
+    "editorPort": {
+      "description": "Stable preferred local editor port; launchers may fall forward when occupied",
+      "type": "integer",
+      "minimum": 1024,
+      "maximum": 65535
+    },
+    "version": {
+      "type": "string",
+      "description": "The game's own version (used for orphan detection)"
+    },
+    "engine": {
+      "type": "object",
+      "properties": {
+        "version": {
+          "type": "string",
+          "description": "Exact @vgai/engine semver this game was scaffolded/last upgraded against — an identity pin, not a range"
+        }
+      },
+      "required": [
+        "version"
+      ],
+      "description": "Engine version pin"
+    },
+    "roots": {
+      "minItems": 1,
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Unique id for this root within the manifest (enforced-unique, D-V6 — GameManifestSchema.roots rejects duplicates)"
+          },
+          "description": {
+            "description": "Optional one-line description of this root's game/content (e.g. an ingested game's blurb — the manifest-native replacement for a registry entry's description field)",
+            "type": "string"
+          },
+          "adapter": {
+            "anyOf": [
+              {
+                "type": "string",
+                "enum": [
+                  "threejs",
+                  "pixijs",
+                  "react"
+                ]
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "module": {
+                    "type": "string",
+                    "description": "Game-folder-relative path to a custom adapter module (trust boundary)"
+                  },
+                  "surface": {
+                    "type": "string",
+                    "enum": [
+                      "threejs",
+                      "pixijs",
+                      "react"
+                    ],
+                    "description": "Native surface exposed by this custom adapter contract"
+                  }
+                },
+                "required": [
+                  "module",
+                  "surface"
+                ],
+                "additionalProperties": false
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "surface": {
+                    "type": "string",
+                    "enum": [
+                      "threejs",
+                      "pixijs",
+                      "react"
+                    ],
+                    "description": "Native surface captured from the unmodified game"
+                  },
+                  "ingest": {
+                    "type": "object",
+                    "properties": {
+                      "strategy": {
+                        "type": "string",
+                        "enum": [
+                          "shared",
+                          "deduped",
+                          "iframe-reachable",
+                          "opaque-embed"
+                        ],
+                        "description": "Capture mechanics rung this ingested root uses (§4) — also the root`s natural local capability tier"
+                      },
+                      "entryHtml": {
+                        "description": "Entry HTML path, project-relative. WIRED for opaque-embed (D-W2, docs/WAVE4-FTUE-HARDENING-DESIGN.md): the file`s bytes are read verbatim through the project-static route and hosted in a sandboxed iframe (embed-only, no scene introspection), for both pixijs and threejs roots. Legal but NOT wired to a mount for iframe-reachable (a named error at resolve names this — use `bundleUrl` instead, the wired reachable route).",
+                        "type": "string"
+                      },
+                      "assets": {
+                        "description": "Path-substring -> served-URL rewrites for this ingested game (IngestGame.assets today)",
+                        "type": "object",
+                        "propertyNames": {
+                          "type": "string"
+                        },
+                        "additionalProperties": {
+                          "type": "string"
+                        }
+                      },
+                      "domStubs": {
+                        "description": "DOM API stub ids this ingested game requires to run headlessly/in-realm",
+                        "type": "array",
+                        "items": {
+                          "type": "string"
+                        }
+                      },
+                      "captureTimeoutMs": {
+                        "description": "Max time to wait for in-realm/cross-realm capture before failing loudly",
+                        "type": "number"
+                      },
+                      "bundleUrl": {
+                        "description": "Absolute URL of the externalized built game bundle — the WIRED iframe-reachable mount route (iframe-reachable only), for BOTH pixijs (Track P, ingest-iframe-2d.ts's mountIngestGame2DIframeReachableMulti) and threejs (D-W1, docs/WAVE4-FTUE-HARDENING-DESIGN.md, ingest-iframe-reachable-adapter.ts's mountIngestGameIframeReachableBundle). PRECONDITION: the bundle must externalize its root`s own runtime as a bare, un-rewritten import (`pixi.js` for pixijs, `three` for threejs — `vgai bundle` does this for you) so it resolves through the iframe importmap to the HOST instance the capture trap is installed on; a bundle with an inlined runtime is unreachable and degrades to the embed-only floor. Exactly one of bundleUrl/entryHtml is required when strategy is iframe-reachable.",
+                        "type": "string"
+                      },
+                      "baseHref": {
+                        "description": "Iframe <base href> so the game's relative asset URLs resolve (iframe-reachable only).",
+                        "type": "string"
+                      },
+                      "assetBaseUrl": {
+                        "description": "Host-side basePath forced onto the trapped runtime's own asset resolution — pixi's `Assets.init` for a pixijs root, three's `DefaultLoadingManager.setURLModifier` for a threejs root (D-W1) — absolute, or root-relative (resolved against the editor page's own origin at mount time, ingest-mode.ts, so a static manifest never has to know the dev-server port) (iframe-reachable only — a document.write iframe keeps the parent window.location).",
+                        "type": "string"
+                      },
+                      "extraDeps": {
+                        "description": "Bare specifiers of this root's externalized deps beyond its own runtime (pixi.js/three — e.g. '@pixi/sound', 'gsap'). Resolved by the editor's host-namespace registry into module namespaces when known (D-P1 — the manifest carries data, not code); an unregistered specifier falls back to the open project's own node_modules (D-Z3, docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md), served as a verbatim iframe importmap URL. Throws a named error if neither resolves it (iframe-reachable only).",
+                        "type": "array",
+                        "items": {
+                          "type": "string"
+                        }
+                      },
+                      "pixiModuleUrl": {
+                        "description": "PIXI-ONLY: standalone matching-major pixi ESM URL to trap instead of the host pixi, for version-skewed games (e.g. a v6 game on a v8 host); this field's PRESENCE is how the skew is expressed (D-P2 — no separate strategy/tier for version skew) (iframe-reachable only). Declaring this on a `kind: \"threejs\"` root is schema-legal (this field is kind-agnostic here) but throws a NAMED not-supported error at resolve — three has no version-skew mount this wave (D-W7, docs/WAVE4-FTUE-HARDENING-DESIGN.md: a hypothetical `threeModuleUrl` is explicitly parked, no consumer exists).",
+                        "type": "string"
+                      },
+                      "bodyHtml": {
+                        "description": "HTML injected into the iframe body before the game script boots (e.g. a `<div id=\"game-root\">` the game expects to find) (iframe-reachable only).",
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "strategy"
+                    ],
+                    "description": "Ingest adapter configuration for an unmodified game (a repo-vendored game or your own external folder)"
+                  }
+                },
+                "required": [
+                  "surface",
+                  "ingest"
+                ],
+                "additionalProperties": false
+              }
+            ],
+            "description": "This root's adapter and sole rendering/lifecycle discriminator"
+          },
+          "scene": {
+            "description": ".vscn.json / .scn2d.json scene path (default adapters only — ingest adapters keep their own formats)",
+            "type": "string"
+          },
+          "entry": {
+            "description": "Module exporting setup()/adapter (default adapters' code-authored alternative to `scene`)",
+            "type": "string"
+          },
+          "zOrder": {
+            "default": 0,
+            "description": "Canvas stacking order (COMPOSITION-DESIGN); ties broken by array order",
+            "type": "integer",
+            "minimum": -9007199254740991,
+            "maximum": 9007199254740991
+          },
+          "pausable": {
+            "default": true,
+            "description": "Whether play-mode pause/step applies to this root",
+            "type": "boolean"
+          },
+          "loop": {
+            "default": "gated",
+            "description": "gated: host-driven loop (default). self-driven: this root drives its own loop (the \"composited, unsynchronized\" tier) — an axis independent of capability tier",
+            "type": "string",
+            "enum": [
+              "gated",
+              "self-driven"
+            ]
+          },
+          "capabilities": {
+            "description": "Per-delivery-context capability tier declarations (§4). Declaring above the adapter's ceiling for that context is an error; declaring at or below it (including `unsupported`) is legal.",
+            "type": "object",
+            "properties": {
+              "local": {
+                "description": "Declared capability tier when served via the local CLI (Vite pipeline); omitted -> derived (§4)",
+                "type": "string",
+                "enum": [
+                  "first-party",
+                  "shared",
+                  "deduped",
+                  "iframe-reachable",
+                  "opaque-embed",
+                  "unsupported"
+                ]
+              },
+              "hosted": {
+                "description": "Declared capability tier when served hosted (no bundler: esbuild-wasm + externals only); omitted -> derived (§4)",
+                "type": "string",
+                "enum": [
+                  "first-party",
+                  "shared",
+                  "deduped",
+                  "iframe-reachable",
+                  "opaque-embed",
+                  "unsupported"
+                ]
+              }
+            }
+          }
+        },
+        "required": [
+          "id",
+          "adapter"
+        ],
+        "additionalProperties": false
+      },
+      "description": "The Game's explicit, non-empty adapter-root composition. There is no implicit root."
+    },
+    "authoring": {
+      "description": "Editor-only authoring metadata; never runtime ownership",
+      "type": "object",
+      "properties": {
+        "hierarchy": {
+          "description": "Editor projection for native adapter roots",
+          "type": "object",
+          "properties": {
+            "rootLabels": {
+              "description": "Optional editor labels keyed by adapter-root id",
+              "type": "object",
+              "propertyNames": {
+                "type": "string"
+              },
+              "additionalProperties": {
+                "type": "string"
+              }
+            },
+            "groups": {
+              "description": "Optional editor-only hierarchy groups",
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "id": {
+                    "type": "string",
+                    "description": "Unique editor-only group id"
+                  },
+                  "label": {
+                    "type": "string",
+                    "description": "Editor-only group label"
+                  },
+                  "roots": {
+                    "minItems": 1,
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "Adapter-root ids shown under this editor-only group"
+                  }
+                },
+                "required": [
+                  "id",
+                  "label",
+                  "roots"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "server": {
+      "description": "Multiplayer server config (Colyseus), if this game registers a room",
+      "type": "object",
+      "properties": {
+        "room": {
+          "type": "string",
+          "description": "Colyseus room name"
+        },
+        "module": {
+          "description": "Module path for the Colyseus room bootstrap; defaults to the scaffolded server bootstrap",
+          "type": "string"
+        }
+      },
+      "required": [
+        "room"
+      ]
+    },
+    "resolution": {
+      "description": "Canvas resolution",
+      "type": "object",
+      "properties": {
+        "width": {
+          "type": "number",
+          "description": "Canvas width in pixels"
+        },
+        "height": {
+          "type": "number",
+          "description": "Canvas height in pixels"
+        }
+      },
+      "required": [
+        "width",
+        "height"
+      ]
+    },
+    "debug": {
+      "description": "Debug-bridge production gating (D18) — governs whether ?vgai-debug=1 installs window.__vgai outside dev builds.",
+      "type": "object",
+      "properties": {
+        "allowInProduction": {
+          "type": "boolean",
+          "description": "Allow the ?vgai-debug=1 introspection bridge and debug-command invocation in production builds. Default false: the bridge only installs in dev builds. The runtime reader is the debug-bridge installer (D18)."
+        }
+      },
+      "required": [
+        "allowInProduction"
+      ]
+    },
+    "determinism": {
+      "description": "Seeded-RNG determinism contract (D15, docs/D15-DETERMINISM-DESIGN.md) — governs whether ctx.random is boot-seeded from a reproducible seed and whether the gameplay-rng-ban scan / dev-mode Math.random phase trap are active for this project.",
+      "type": "object",
+      "properties": {
+        "seededRandom": {
+          "type": "boolean",
+          "description": "Declares that ALL gameplay RNG in this project flows through ctx.random (the named-stream seeded PRNG, docs/D15-DETERMINISM-DESIGN.md) rather than raw Math.random/Date.now/performance.now. Three runtime enforcers key off this flag: the boot-time seeding reader (mount-manifest.ts seeds ctx.random from defaultSeed/?vgai-seed=/explicit config, in that precedence, only when true), the gameplay-rng-ban burn-down scan (test/gameplay-rng-ban.test.ts — lints this project's src/ for raw RNG/wall-clock calls), and the dev-mode Math.random phase trap (runtime/gameplay-rng-trap.ts — warns once per call site during a gameplay frame, never throws). Default false: an undeclared project gets no determinism contract at all (that IS the opt-out — no dead field, per the T4.1 policy)."
+        },
+        "defaultSeed": {
+          "description": "The seed ctx.random boots from when seededRandom is true, unless overridden by ?vgai-seed=<int> (the query param always wins over this manifest default) or an even higher-precedence explicit config value a host passes directly. Optional — omit to fall back to the runtime's own fixed default seed.",
+          "type": "integer",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991
+        }
+      },
+      "required": [
+        "seededRandom"
+      ]
+    }
+  },
+  "required": [
+    "manifestVersion",
+    "name",
+    "version",
+    "engine",
+    "roots"
+  ],
+  "additionalProperties": false,
+  "description": "Game manifest (vgai.game.json) — the complete v2 project configuration"
+}