@vgai/engine 0.4.1 → 0.5.0-canary.20260719.0

package/schemas/prefab.schema.json

@@ -250,19 +250,20 @@
                     "plane",
                     "cylinder",
                     "capsule",
-                    "gltf"
+                    "gltf",
+                    "splat"
                   ],
-                  "description": "Mesh primitive type, or \"gltf\" for an external 3D model"
+                  "description": "Renderable type: a built-in mesh primitive, \"gltf\" for an external 3D model, or \"splat\" for a native Gaussian-splat asset"
                 },
                 "args": {
-                  "description": "Geometry constructor args — box: [w,h,d], sphere: [radius], cylinder: [rTop,rBot,h], capsule: [radius,length], plane: [w,h]",
+                  "description": "Geometry constructor args — box: [w,h,d], sphere: [radius], cylinder: [rTop,rBot,h], capsule: [radius,length], plane: [w,h,widthSegments,heightSegments]",
                   "type": "array",
                   "items": {
                     "type": "number"
                   }
                 },
                 "src": {
-                  "description": "Path to GLTF/GLB model file. Required when type is \"gltf\"",
+                  "description": "Path to the external render asset. Required for \"gltf\" (GLTF/GLB) and \"splat\" (SPZ)",
                   "type": "string"
                 },
                 "node": {
@@ -273,56 +274,8 @@
                   "description": "Path to an instance-transform asset (.instances.json: an array of [posX,posY,posZ, quatX,quatY,quatZ,quatW, scaleX,scaleY,scaleZ] tuples). Renders one THREE.InstancedMesh (one draw call). Bulk transform data is referenced as an asset, never inlined — keeps vscn thin.",
                   "type": "string"
                 },
-                "instancer": {
-                  "description": "Registered instancer name. When set, the mesh renders as a single THREE.InstancedMesh (one draw call) with code-generated per-instance transforms instead of one THREE.Mesh",
-                  "type": "string"
-                },
-                "instancerParams": {
-                  "description": "Params for the instancer (e.g. count, spacing), keyed by name",
-                  "type": "object",
-                  "propertyNames": {
-                    "type": "string"
-                  },
-                  "additionalProperties": {
-                    "anyOf": [
-                      {
-                        "type": "number"
-                      },
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "type": "boolean"
-                      }
-                    ]
-                  }
-                },
-                "generator": {
-                  "description": "Registered geometry-generator name (e.g. \"Terrain\"). When set, the mesh geometry is produced procedurally in code instead of from `type`/`args`. Pairs with a \"trimesh\" collider for matching physics.",
-                  "type": "string"
-                },
-                "generatorParams": {
-                  "description": "Params for the geometry generator (e.g. width, segments, amplitude)",
-                  "type": "object",
-                  "propertyNames": {
-                    "type": "string"
-                  },
-                  "additionalProperties": {
-                    "anyOf": [
-                      {
-                        "type": "number"
-                      },
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "type": "boolean"
-                      }
-                    ]
-                  }
-                },
                 "lod": {
-                  "description": "Per-entity Level-of-Detail: distance-keyed glTF sub-nodes swapped by camera distance (THREE.LOD). gltf-only. Gated by the environment.rendering.lod master toggle — when off, only the closest level renders. Cannot combine with node/instances/instancer.",
+                  "description": "Per-entity Level-of-Detail: distance-keyed glTF sub-nodes swapped by camera distance (THREE.LOD). gltf-only. Gated by the environment.rendering.lod master toggle — when off, only the closest level renders. Cannot combine with node/instances.",
                   "type": "array",
                   "items": {
                     "type": "object",
@@ -359,40 +312,9 @@
                     "standard",
                     "physical",
                     "basic",
-                    "toon",
-                    "custom"
+                    "toon"
                   ],
-                  "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"
-                        }
-                      }
-                    ]
-                  }
+                  "description": "Material shading model"
                 },
                 "color": {
                   "description": "Base color as CSS hex string (e.g. \"#ff0000\")",
@@ -5322,19 +5244,20 @@
                     "plane",
                     "cylinder",
                     "capsule",
-                    "gltf"
+                    "gltf",
+                    "splat"
                   ],
-                  "description": "Mesh primitive type, or \"gltf\" for an external 3D model"
+                  "description": "Renderable type: a built-in mesh primitive, \"gltf\" for an external 3D model, or \"splat\" for a native Gaussian-splat asset"
                 },
                 "args": {
-                  "description": "Geometry constructor args — box: [w,h,d], sphere: [radius], cylinder: [rTop,rBot,h], capsule: [radius,length], plane: [w,h]",
+                  "description": "Geometry constructor args — box: [w,h,d], sphere: [radius], cylinder: [rTop,rBot,h], capsule: [radius,length], plane: [w,h,widthSegments,heightSegments]",
                   "type": "array",
                   "items": {
                     "type": "number"
                   }
                 },
                 "src": {
-                  "description": "Path to GLTF/GLB model file. Required when type is \"gltf\"",
+                  "description": "Path to the external render asset. Required for \"gltf\" (GLTF/GLB) and \"splat\" (SPZ)",
                   "type": "string"
                 },
                 "node": {
@@ -5345,56 +5268,8 @@
                   "description": "Path to an instance-transform asset (.instances.json: an array of [posX,posY,posZ, quatX,quatY,quatZ,quatW, scaleX,scaleY,scaleZ] tuples). Renders one THREE.InstancedMesh (one draw call). Bulk transform data is referenced as an asset, never inlined — keeps vscn thin.",
                   "type": "string"
                 },
-                "instancer": {
-                  "description": "Registered instancer name. When set, the mesh renders as a single THREE.InstancedMesh (one draw call) with code-generated per-instance transforms instead of one THREE.Mesh",
-                  "type": "string"
-                },
-                "instancerParams": {
-                  "description": "Params for the instancer (e.g. count, spacing), keyed by name",
-                  "type": "object",
-                  "propertyNames": {
-                    "type": "string"
-                  },
-                  "additionalProperties": {
-                    "anyOf": [
-                      {
-                        "type": "number"
-                      },
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "type": "boolean"
-                      }
-                    ]
-                  }
-                },
-                "generator": {
-                  "description": "Registered geometry-generator name (e.g. \"Terrain\"). When set, the mesh geometry is produced procedurally in code instead of from `type`/`args`. Pairs with a \"trimesh\" collider for matching physics.",
-                  "type": "string"
-                },
-                "generatorParams": {
-                  "description": "Params for the geometry generator (e.g. width, segments, amplitude)",
-                  "type": "object",
-                  "propertyNames": {
-                    "type": "string"
-                  },
-                  "additionalProperties": {
-                    "anyOf": [
-                      {
-                        "type": "number"
-                      },
-                      {
-                        "type": "string"
-                      },
-                      {
-                        "type": "boolean"
-                      }
-                    ]
-                  }
-                },
                 "lod": {
-                  "description": "Per-entity Level-of-Detail: distance-keyed glTF sub-nodes swapped by camera distance (THREE.LOD). gltf-only. Gated by the environment.rendering.lod master toggle — when off, only the closest level renders. Cannot combine with node/instances/instancer.",
+                  "description": "Per-entity Level-of-Detail: distance-keyed glTF sub-nodes swapped by camera distance (THREE.LOD). gltf-only. Gated by the environment.rendering.lod master toggle — when off, only the closest level renders. Cannot combine with node/instances.",
                   "type": "array",
                   "items": {
                     "type": "object",
@@ -5428,40 +5303,9 @@
                     "standard",
                     "physical",
                     "basic",
-                    "toon",
-                    "custom"
+                    "toon"
                   ],
-                  "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"
-                        }
-                      }
-                    ]
-                  }
+                  "description": "Material shading model"
                 },
                 "color": {
                   "description": "Base color as CSS hex string (e.g. \"#ff0000\")",

package/schemas/scn2d.schema.json

@@ -8,7 +8,7 @@
       "type": "number"
     },
     "name": {
-      "description": "Scene name. REJECTED at parse (T4.1): declared but has no runtime reader — authoring this field throws. Do not author.",
+      "description": "Scene name shown in the native 2D document hierarchy and inspector",
       "type": "string"
     },
     "surface": {
@@ -17,7 +17,7 @@
       "const": "world2d"
     },
     "gravity": {
-      "description": "World gravity [x, y] in px/s^2. Default [0, 980]",
+      "description": "World gravity [x, y] in px/s^2. Default [0, 9.8 * pixelsPerMeter] ([0, 980] at the default scale)",
       "type": "array",
       "prefixItems": [
         {
@@ -28,6 +28,11 @@
         }
       ]
     },
+    "pixelsPerMeter": {
+      "description": "Authored pixels per physics meter. Configures native Rapier World.lengthUnit and scales default gravity. Default 100",
+      "type": "number",
+      "exclusiveMinimum": 0
+    },
     "background": {
       "description": "Background color hex string. Default '#10101a'",
       "type": "string"
@@ -70,7 +75,7 @@
           "type": "boolean"
         },
         "locked": {
-          "description": "Prevent selection and editing in the scene editor. REJECTED at parse (T4.1): declared but has no runtime reader — authoring this field throws. Do not author.",
+          "description": "Prevent selection and editing in the native 2D scene editor",
           "type": "boolean"
         },
         "tags": {
@@ -149,7 +154,13 @@
             },
             "frame": {
               "description": "Spritesheet frame/sub-texture name when `texture` is a spritesheet atlas",
-              "type": "string"
+              "type": "string",
+              "minLength": 1
+            },
+            "animation": {
+              "description": "Named spritesheet animation from `texture` (PIXI.Spritesheet.animations); mutually exclusive with `frame`",
+              "type": "string",
+              "minLength": 1
             },
             "anchor": {
               "description": "Normalized anchor [x, y] (0..1). Default [0.5, 0.5]",
@@ -204,15 +215,14 @@
                 "desaturate"
               ]
             },
-            "animationFrames": {
-              "description": "If set, build an AnimatedSprite cycling N generated tinted frames",
-              "type": "integer",
-              "minimum": -9007199254740991,
-              "maximum": 9007199254740991
-            },
             "fps": {
               "description": "AnimatedSprite playback speed in frames/sec. Default 8",
-              "type": "number"
+              "type": "number",
+              "exclusiveMinimum": 0
+            },
+            "loop": {
+              "description": "Whether the named spritesheet animation loops. Default true",
+              "type": "boolean"
             }
           },
           "additionalProperties": false
@@ -255,16 +265,24 @@
           "description": "2D tilemap (CompositeTilemap)",
           "type": "object",
           "properties": {
-            "tileSize": {
-              "type": "number",
-              "description": "Tile width/height in pixels"
-            },
-            "palette": {
+            "frames": {
+              "minItems": 1,
               "type": "array",
               "items": {
-                "type": "string"
+                "type": "string",
+                "minLength": 1
               },
-              "description": "Hex colors; one generated tile texture per entry (index → color)"
+              "description": "Ordered Pixi spritesheet frame names used as tile indices"
+            },
+            "texture": {
+              "type": "string",
+              "minLength": 1,
+              "description": "URL or project path to a Pixi spritesheet JSON asset"
+            },
+            "tileSize": {
+              "type": "number",
+              "exclusiveMinimum": 0,
+              "description": "Positive square tile width/height in pixels"
             },
             "tiles": {
               "type": "array",
@@ -276,12 +294,13 @@
                   "maximum": 9007199254740991
                 }
               },
-              "description": "Row-major grid of palette indices (each row is an array of tile indices)"
+              "description": "Row-major grid of frame indices; -1 is an empty cell (each row is an array of tile indices)"
             }
           },
           "required": [
+            "frames",
+            "texture",
             "tileSize",
-            "palette",
             "tiles"
           ],
           "additionalProperties": false
@@ -298,7 +317,7 @@
                 "kinematicVelocity",
                 "kinematicPosition"
               ],
-              "description": "Rapier 2D rigid-body type"
+              "description": "Rapier 2D rigid-body type. A body of any type nested below a dynamic or kinematic body is rejected: Rapier has no parent/child body relationship. Nesting below a fixed or physics-less transformed parent is supported for fixed bodies. Dynamic and kinematic bodies additionally require a conformal parent chain (uniform scale plus rotation/reflection), because later body rotation cannot round-trip through non-uniform parent scale without shearing the Pixi visual."
             },
             "collider": {
               "oneOf": [
@@ -308,7 +327,7 @@
                     "shape": {
                       "type": "string",
                       "const": "cuboid",
-                      "description": "Axis-aligned box collider"
+                      "description": "Box collider aligned to the rigid-body rotation"
                     },
                     "halfExtents": {
                       "type": "array",
@@ -373,7 +392,7 @@
                   "additionalProperties": false
                 }
               ],
-              "description": "Collider shape attached to the body"
+              "description": "Collider shape attached to the body. Its pose and dimensions use the composed parent transform at spawn. Cuboids support non-uniform scale; ball/capsule colliders reject non-uniform scale because Rapier cannot represent an ellipse."
             },
             "sensor": {
               "description": "If true, a sensor (trigger) collider — overlaps fire onTriggerEnter/Exit, no solid response",

package/schemas/vgai-game.schema.json

@@ -369,6 +369,40 @@
       "required": [
         "seededRandom"
       ]
+    },
+    "budget": {
+      "description": "Performance budget (W3d, F11 perf regression gates) asserted by `vgai perf --assert-budget`: a seeded, fixed-step headless run samples the engine profiler and fails (nonzero exit) when any metric here is exceeded. Only headlessly-measurable metrics are budgetable; real GPU frame time is not (SwiftShader).",
+      "type": "object",
+      "properties": {
+        "frameCpuMsP95": {
+          "description": "Maximum allowed p95 of per-frame CPU time (ms) across the measured frames of a `vgai perf` seeded headless run. CPU-side only: headless runs rasterize under SwiftShader, so this is main-thread frame cost, NOT real GPU frame time. Machine-dependent — prefer the baseline-diff tolerance band for regression gating and use this as a coarse absolute ceiling.",
+          "type": "number",
+          "exclusiveMinimum": 0
+        },
+        "physicsMsP95": {
+          "description": "Maximum allowed p95 of the profiler's `physics` phase time (ms) per fixed-step frame in a `vgai perf` run. Same CPU-timing caveats as frameCpuMsP95.",
+          "type": "number",
+          "exclusiveMinimum": 0
+        },
+        "maxEntities": {
+          "description": "Maximum allowed entity-tagged scene-graph nodes (nodes carrying userData.entityId) summed across the game's threejs/pixijs worlds at the end of a `vgai perf` run. Exact and deterministic under a seed — no tolerance band.",
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        "maxDrawCalls": {
+          "description": "Maximum allowed renderer draw calls in any measured frame of a `vgai perf` run (the profiler's per-frame render.drawCalls, from renderer.info). Exact and deterministic under a seed.",
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "maximum": 9007199254740991
+        },
+        "maxTriangles": {
+          "description": "Maximum allowed rendered triangles in any measured frame of a `vgai perf` run (the profiler's per-frame render.triangles, from renderer.info). Exact and deterministic under a seed.",
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "maximum": 9007199254740991
+        }
+      }
     }
   },
   "required": [