@vgai/engine 0.2.0 → 0.4.0-canary.20260715.0

package/schemas/inputmap.schema.json

@@ -0,0 +1,314 @@
+{
+  "$comment": "AUTO-GENERATED by scripts/generate-schema.ts — do not edit manually",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "version": {
+      "type": "number",
+      "description": "Input map file format version (RESERVED — no range check yet)"
+    },
+    "actions": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "valueType": {
+            "default": "digital",
+            "description": "This action's declared value shape (F1, spec §12). 'digital' (boolean, with pressed/justPressed/justReleased edges) is the default when omitted, matching every action authored before F1. 'scalar' is a single deadzone-rescaled float axis. 'vector2' is a radial-deadzoned, unit-circle-normalized {x,y}. 'pointerDelta' is a per-frame {x,y} movement delta, summed across sources. 'pointerPosition' is an absolute {x,y}, last-write-wins across sources. InputManager enforces this at read time: reading an action through the wrong typed getter (e.g. getScalar on a 'digital' action) throws.",
+            "type": "string",
+            "enum": [
+              "digital",
+              "scalar",
+              "vector2",
+              "pointerDelta",
+              "pointerPosition"
+            ]
+          },
+          "bindings": {
+            "type": "array",
+            "items": {
+              "oneOf": [
+                {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "const": "key",
+                      "description": "Binding kind: a keyboard key (KeyboardEvent.code)"
+                    },
+                    "code": {
+                      "type": "string",
+                      "description": "KeyboardEvent.code value, e.g. \"KeyW\", \"Space\", \"ArrowUp\""
+                    }
+                  },
+                  "required": [
+                    "type",
+                    "code"
+                  ],
+                  "additionalProperties": false
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "const": "mouse_button",
+                      "description": "Binding kind: a mouse button"
+                    },
+                    "button": {
+                      "type": "number",
+                      "description": "MouseEvent.button index (0 = left, 1 = middle, 2 = right)"
+                    }
+                  },
+                  "required": [
+                    "type",
+                    "button"
+                  ],
+                  "additionalProperties": false
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "const": "mouse_move",
+                      "description": "Binding kind: raw mouse movement (F2, spec §12 \"Complete Device Backends\"). Feeds a 'pointerDelta'-valueType action with the raw accumulated mouse delta (no deadzone), and can also feed a 'vector2'-valueType action (the same delta, radial-deadzoned + unit-circle-clamped via `deadzone`)."
+                    },
+                    "deadzone": {
+                      "description": "Radial deadzone magnitude applied only when this binding feeds a 'vector2'-valueType action (default 0 — no deadzone; ignored for 'pointerDelta' reads, which are never deadzoned).",
+                      "type": "number"
+                    }
+                  },
+                  "required": [
+                    "type"
+                  ],
+                  "additionalProperties": false
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "const": "gamepad_button",
+                      "description": "Binding kind: a gamepad face/shoulder button"
+                    },
+                    "button": {
+                      "type": "number",
+                      "description": "Standard Gamepad API button index"
+                    }
+                  },
+                  "required": [
+                    "type",
+                    "button"
+                  ],
+                  "additionalProperties": false
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "const": "gamepad_axis",
+                      "description": "Binding kind: a single thresholded gamepad axis"
+                    },
+                    "axis": {
+                      "type": "number",
+                      "description": "Standard Gamepad API axis index"
+                    },
+                    "direction": {
+                      "type": "string",
+                      "enum": [
+                        "positive",
+                        "negative"
+                      ],
+                      "description": "Which side of the deadzone counts as \"pressed\""
+                    },
+                    "deadzone": {
+                      "description": "Deadzone magnitude (default 0.15 if omitted)",
+                      "type": "number"
+                    }
+                  },
+                  "required": [
+                    "type",
+                    "axis",
+                    "direction"
+                  ],
+                  "additionalProperties": false
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "const": "gamepad_axis_pair",
+                      "description": "Binding kind: a coupled (x, y) gamepad axis pair, e.g. a stick used as a 2D vector (look/aim/movement) (F2, spec §12 \"Complete Device Backends\"). Feeds a 'vector2'-valueType action: (xAxis, yAxis) read together, radial-deadzoned + unit-circle-clamped the same way a real analog stick is."
+                    },
+                    "xAxis": {
+                      "type": "number",
+                      "description": "Standard Gamepad API axis index for the X component"
+                    },
+                    "yAxis": {
+                      "type": "number",
+                      "description": "Standard Gamepad API axis index for the Y component"
+                    },
+                    "deadzone": {
+                      "description": "Deadzone magnitude (default 0.15 if omitted)",
+                      "type": "number"
+                    }
+                  },
+                  "required": [
+                    "type",
+                    "xAxis",
+                    "yAxis"
+                  ],
+                  "additionalProperties": false
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "const": "test_axis",
+                      "description": "Binding kind: an injected synthetic scalar value for a 'scalar'-valueType action (InputManager.injectAxis/getScalar) — the \"injected test input\" backend named in F2, built in F1 as the typed scalar value model's testable source."
+                    },
+                    "sourceId": {
+                      "type": "string",
+                      "description": "Names the injected test source this binding reads (InputManager.injectAxis)."
+                    },
+                    "deadzone": {
+                      "description": "1D deadzone magnitude applied to the injected raw value before combine (default 0 — no deadzone). Values below it read as 0; values at/above it rescale from 0 (at the deadzone edge) to ±1 (at |raw| = 1), sign preserved.",
+                      "type": "number"
+                    }
+                  },
+                  "required": [
+                    "type",
+                    "sourceId"
+                  ],
+                  "additionalProperties": false
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "const": "test_vector2",
+                      "description": "Binding kind: an injected synthetic {x,y} value for a 'vector2'-valueType action (InputManager.injectVector2/getVector2) — the \"injected test input\" backend named in F2, built in F1 as the typed Vector2 value model's testable source."
+                    },
+                    "sourceId": {
+                      "type": "string",
+                      "description": "Names the injected test source this binding reads (InputManager.injectVector2)."
+                    },
+                    "deadzone": {
+                      "description": "Radial deadzone magnitude applied to the injected raw {x,y} before combine (default 0 — no deadzone). Vectors whose magnitude is below it read as {0,0}; at/above it, direction is preserved and magnitude rescales the same way the scalar deadzone does, then the result is clamped to the unit circle (magnitude <= 1).",
+                      "type": "number"
+                    }
+                  },
+                  "required": [
+                    "type",
+                    "sourceId"
+                  ],
+                  "additionalProperties": false
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "const": "test_pointer_delta",
+                      "description": "Binding kind: an injected synthetic per-frame {x,y} delta for a 'pointerDelta'-valueType action (InputManager.injectPointerDelta/getPointerDelta) — the \"injected test input\" backend named in F2. No deadzone (deltas are not deadzoned)."
+                    },
+                    "sourceId": {
+                      "type": "string",
+                      "description": "Names the injected test source this binding reads (InputManager.injectPointerDelta)."
+                    }
+                  },
+                  "required": [
+                    "type",
+                    "sourceId"
+                  ],
+                  "additionalProperties": false
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "const": "test_pointer_position",
+                      "description": "Binding kind: an injected synthetic absolute {x,y} position for a 'pointerPosition'-valueType action (InputManager.injectPointerPosition/getPointerPosition) — the \"injected test input\" backend named in F2."
+                    },
+                    "sourceId": {
+                      "type": "string",
+                      "description": "Names the injected test source this binding reads (InputManager.injectPointerPosition)."
+                    }
+                  },
+                  "required": [
+                    "type",
+                    "sourceId"
+                  ],
+                  "additionalProperties": false
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "const": "touch_button",
+                      "description": "Binding kind: a virtual on-screen button for a 'digital' action (InputManager.setTouchButton/isPressed) — edge-tracked (isJustPressed/isJustReleased) the same way a real mouse/keyboard button is."
+                    },
+                    "sourceId": {
+                      "type": "string",
+                      "description": "Names the virtual control zone this binding reads (InputManager.setTouchButton) — a touch-UI-chosen id, not a real device index."
+                    }
+                  },
+                  "required": [
+                    "type",
+                    "sourceId"
+                  ],
+                  "additionalProperties": false
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "const": "touch_stick",
+                      "description": "Binding kind: a virtual on-screen analog stick for a 'vector2' action (InputManager.setTouchStick/getVector2) — radial-deadzoned + unit-circle-clamped the same way a real gamepad stick is."
+                    },
+                    "sourceId": {
+                      "type": "string",
+                      "description": "Names the virtual control zone this binding reads (InputManager.setTouchStick) — a touch-UI-chosen id, not a real device index."
+                    },
+                    "deadzone": {
+                      "description": "Radial deadzone magnitude applied to the raw {x,y} before combine (default 0 — no deadzone).",
+                      "type": "number"
+                    }
+                  },
+                  "required": [
+                    "type",
+                    "sourceId"
+                  ],
+                  "additionalProperties": false
+                }
+              ]
+            },
+            "description": "Bindings that all trigger/feed this action. Digital actions combine via OR (any one binding satisfied is enough). Scalar actions combine via max-magnitude across contributing bindings (ties keep the first-listed binding). Vector2 actions combine by summing contributing {x,y} values then clamping to the unit circle. PointerDelta actions sum contributing deltas. PointerPosition actions use the most-recently-written contributing source (last-write-wins)."
+          }
+        },
+        "required": [
+          "valueType",
+          "bindings"
+        ],
+        "additionalProperties": false
+      },
+      "description": "Named actions, each with a list of bindings (InputManager.loadMap)"
+    }
+  },
+  "required": [
+    "version",
+    "actions"
+  ],
+  "additionalProperties": false
+}

package/schemas/mat.schema.json

@@ -0,0 +1,286 @@
+{
+  "$comment": "AUTO-GENERATED by scripts/generate-schema.ts — do not edit manually",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "version": {
+      "type": "number",
+      "description": "File format version"
+    },
+    "name": {
+      "type": "string",
+      "description": "Human-readable material name"
+    },
+    "material": {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": [
+            "standard",
+            "physical",
+            "basic",
+            "toon",
+            "custom"
+          ],
+          "description": "Material shading model. \"custom\" resolves `def` against the material registry"
+        },
+        "def": {
+          "description": "Registered custom-material name (required when type is \"custom\")",
+          "type": "string"
+        },
+        "uniforms": {
+          "description": "Authored uniform values for a custom material, keyed by uniform name",
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {
+            "anyOf": [
+              {
+                "type": "number"
+              },
+              {
+                "type": "string"
+              },
+              {
+                "type": "boolean"
+              },
+              {
+                "type": "array",
+                "items": {
+                  "type": "number"
+                }
+              }
+            ]
+          }
+        },
+        "color": {
+          "description": "Base color as CSS hex string (e.g. \"#ff0000\")",
+          "type": "string"
+        },
+        "metalness": {
+          "description": "Metalness factor 0–1 (standard/physical only)",
+          "type": "number"
+        },
+        "roughness": {
+          "description": "Roughness factor 0–1 (standard/physical only)",
+          "type": "number"
+        },
+        "map": {
+          "description": "Path to albedo/diffuse texture image",
+          "type": "string"
+        },
+        "normalMap": {
+          "description": "Path to normal map texture image",
+          "type": "string"
+        },
+        "emissive": {
+          "description": "Emissive color as CSS hex string",
+          "type": "string"
+        },
+        "emissiveIntensity": {
+          "description": "Emissive light intensity multiplier",
+          "type": "number"
+        },
+        "emissiveMap": {
+          "description": "Path to emissive map texture image",
+          "type": "string"
+        },
+        "aoMap": {
+          "description": "Path to ambient occlusion map texture image",
+          "type": "string"
+        },
+        "lightMap": {
+          "description": "Path to a baked lightmap texture (uses the mesh's second UV set). Applies the pre-baked GI/shadow result on top of the material.",
+          "type": "string"
+        },
+        "lightMapIntensity": {
+          "description": "Lightmap intensity multiplier (default 1).",
+          "type": "number"
+        },
+        "roughnessMap": {
+          "description": "Path to roughness map texture image",
+          "type": "string"
+        },
+        "metalnessMap": {
+          "description": "Path to metalness map texture image",
+          "type": "string"
+        },
+        "opacity": {
+          "description": "Opacity 0–1. Set transparent: true to enable",
+          "type": "number"
+        },
+        "transparent": {
+          "description": "Enable alpha blending for this material",
+          "type": "boolean"
+        },
+        "side": {
+          "description": "Which face sides to render",
+          "type": "string",
+          "enum": [
+            "front",
+            "back",
+            "double"
+          ]
+        },
+        "flatShading": {
+          "description": "Use flat (faceted) shading instead of smooth",
+          "type": "boolean"
+        },
+        "clearcoat": {
+          "description": "Clearcoat layer (physical only)",
+          "type": "object",
+          "properties": {
+            "clearcoat": {
+              "type": "number",
+              "description": "Clearcoat layer intensity 0–1"
+            },
+            "clearcoatRoughness": {
+              "description": "Clearcoat roughness 0–1",
+              "type": "number"
+            },
+            "clearcoatMap": {
+              "description": "Path to clearcoat intensity map",
+              "type": "string"
+            },
+            "clearcoatRoughnessMap": {
+              "description": "Path to clearcoat roughness map",
+              "type": "string"
+            }
+          },
+          "required": [
+            "clearcoat"
+          ],
+          "additionalProperties": false
+        },
+        "transmission": {
+          "description": "Light transmission (physical only)",
+          "type": "object",
+          "properties": {
+            "transmission": {
+              "type": "number",
+              "description": "Transmission intensity 0–1 (glass, liquid)"
+            },
+            "ior": {
+              "description": "Index of refraction (default 1.5)",
+              "type": "number"
+            },
+            "thickness": {
+              "description": "Volume thickness for refraction",
+              "type": "number"
+            },
+            "attenuationColor": {
+              "description": "Color absorbed over distance",
+              "type": "string"
+            },
+            "attenuationDistance": {
+              "description": "Distance at which attenuation color takes full effect",
+              "type": "number"
+            },
+            "transmissionMap": {
+              "description": "Path to transmission map",
+              "type": "string"
+            }
+          },
+          "required": [
+            "transmission"
+          ],
+          "additionalProperties": false
+        },
+        "sheen": {
+          "description": "Sheen layer (physical only)",
+          "type": "object",
+          "properties": {
+            "sheen": {
+              "type": "number",
+              "description": "Sheen intensity 0–1 (fabric, velvet)"
+            },
+            "sheenColor": {
+              "description": "Sheen tint color",
+              "type": "string"
+            },
+            "sheenRoughness": {
+              "description": "Sheen roughness 0–1",
+              "type": "number"
+            },
+            "sheenColorMap": {
+              "description": "Path to sheen color map",
+              "type": "string"
+            },
+            "sheenRoughnessMap": {
+              "description": "Path to sheen roughness map",
+              "type": "string"
+            }
+          },
+          "required": [
+            "sheen"
+          ],
+          "additionalProperties": false
+        },
+        "iridescence": {
+          "description": "Iridescence thin-film (physical only)",
+          "type": "object",
+          "properties": {
+            "iridescence": {
+              "type": "number",
+              "description": "Iridescence intensity 0–1 (soap bubbles, oil slick)"
+            },
+            "iridescenceIOR": {
+              "description": "Thin-film IOR (default 1.3)",
+              "type": "number"
+            },
+            "iridescenceThicknessRange": {
+              "description": "Min/max thin-film thickness in nm",
+              "type": "array",
+              "prefixItems": [
+                {
+                  "type": "number"
+                },
+                {
+                  "type": "number"
+                }
+              ]
+            },
+            "iridescenceMap": {
+              "description": "Path to iridescence intensity map",
+              "type": "string"
+            },
+            "iridescenceThicknessMap": {
+              "description": "Path to iridescence thickness map",
+              "type": "string"
+            }
+          },
+          "required": [
+            "iridescence"
+          ],
+          "additionalProperties": false
+        },
+        "displacementMap": {
+          "description": "Path to displacement/height map",
+          "type": "string"
+        },
+        "displacementScale": {
+          "description": "Displacement height multiplier",
+          "type": "number"
+        },
+        "displacementBias": {
+          "description": "Displacement offset",
+          "type": "number"
+        }
+      },
+      "required": [
+        "type"
+      ],
+      "additionalProperties": false,
+      "description": "Material definition"
+    }
+  },
+  "required": [
+    "version",
+    "name",
+    "material"
+  ],
+  "additionalProperties": false,
+  "description": "Shared material asset file (.mat.json)"
+}