@babylonjs/loaders 9.20.0 → 9.21.0

package/glTF/2.0/Extensions/KHR_interactivity/declarationMapper.js

@@ -1,5 +1,12 @@
 import { Logger } from "@babylonjs/core/Misc/logger.js";
 import { getAnimationTypeByFlowGraphType } from "@babylonjs/core/FlowGraph/flowGraphRichTypes.js";
+// Per-block runaway-loop guard for KHR_interactivity for-loops. Interactivity assets may run large
+// finite loops (e.g. the math/random Monte Carlo conformance asset iterates 10k times), so this is
+// set above the FlowGraphForLoopBlock process-wide default while staying low enough that the guard is
+// still meaningful — every iteration runs a full synchronous sub-graph, so a much larger value (and
+// especially nested loops) could lock the main thread before the guard trips. Applied per for-loop
+// block via the flow/for extraProcessor rather than by mutating the shared static.
+const InteractivityForLoopMaxIterations = 20000;
 export function getMappingForFullOperationName(fullOperationName) {
     const [op, extension] = fullOperationName.split(":");
     return getMappingForDeclaration({ op, extension });
@@ -77,6 +84,10 @@ const gltfToFlowGraphMapping = {
     "event/onStart": {
         blocks: ["FlowGraphSceneReadyEventBlock" /* FlowGraphBlockNames.SceneReadyEvent */],
         outputs: {
+            values: {
+                // KHR_interactivity `ref event` output (the event reference).
+                event: { name: "event" },
+            },
             flows: {
                 out: { name: "done" },
             },
@@ -88,6 +99,8 @@ const gltfToFlowGraphMapping = {
         outputs: {
             values: {
                 timeSinceLastTick: { name: "deltaTime", gltfType: "number" /*, dataTransformer: (time: number) => time / 1000*/ },
+                // KHR_interactivity `ref event` output (the event reference).
+                event: { name: "event" },
             },
             flows: {
                 out: { name: "done" },
@@ -118,6 +131,10 @@ const gltfToFlowGraphMapping = {
     "event/receive": {
         blocks: ["FlowGraphReceiveCustomEventBlock" /* FlowGraphBlockNames.ReceiveCustomEvent */],
         outputs: {
+            values: {
+                // KHR_interactivity `ref event` output (the event reference).
+                event: { name: "event" },
+            },
             flows: {
                 out: { name: "done" },
             },
@@ -163,8 +180,26 @@ const gltfToFlowGraphMapping = {
             return serializedObjects;
         },
     },
+    "event/stopPropagation": {
+        blocks: ["FlowGraphStopEventPropagationBlock" /* FlowGraphBlockNames.StopEventPropagation */],
+        inputs: {
+            values: {
+                event: { name: "event" },
+                stopImmediate: { name: "stopImmediate" },
+            },
+            flows: {
+                in: { name: "in" },
+            },
+        },
+        outputs: {
+            flows: {
+                out: { name: "out" },
+            },
+        },
+    },
     "math/E": getSimpleInputMapping("FlowGraphEBlock" /* FlowGraphBlockNames.E */),
     "math/Pi": getSimpleInputMapping("FlowGraphPIBlock" /* FlowGraphBlockNames.PI */),
+    "math/Tau": getSimpleInputMapping("FlowGraphTauBlock" /* FlowGraphBlockNames.Tau */),
     "math/Inf": getSimpleInputMapping("FlowGraphInfBlock" /* FlowGraphBlockNames.Inf */),
     "math/NaN": getSimpleInputMapping("FlowGraphNaNBlock" /* FlowGraphBlockNames.NaN */),
     "math/abs": getSimpleInputMapping("FlowGraphAbsBlock" /* FlowGraphBlockNames.Abs */),
@@ -235,7 +270,57 @@ const gltfToFlowGraphMapping = {
     "math/clamp": getSimpleInputMapping("FlowGraphClampBlock" /* FlowGraphBlockNames.Clamp */, ["a", "b", "c"]),
     "math/saturate": getSimpleInputMapping("FlowGraphSaturateBlock" /* FlowGraphBlockNames.Saturate */),
     "math/mix": getSimpleInputMapping("FlowGraphMathInterpolationBlock" /* FlowGraphBlockNames.MathInterpolation */, ["a", "b", "c"]),
+    // Smooth-step (Hermite interpolation): edges a/b and value c.
+    "math/smoothStep": getSimpleInputMapping("FlowGraphSmoothStepBlock" /* FlowGraphBlockNames.SmoothStep */, ["a", "b", "c"]),
+    // Linear sRGB <-> OkLCh (Oklab polar form). Scalar r/g/b inputs map to l/c/h
+    // outputs (hue in radians) and vice-versa.
+    "math/rgbToOkLCh": {
+        blocks: ["FlowGraphRGBToOkLChBlock" /* FlowGraphBlockNames.RGBToOkLCh */],
+        inputs: {
+            values: {
+                r: { name: "r", gltfType: "number" },
+                g: { name: "g", gltfType: "number" },
+                b: { name: "b", gltfType: "number" },
+            },
+        },
+        outputs: {
+            values: {
+                l: { name: "l" },
+                c: { name: "c" },
+                h: { name: "h" },
+            },
+        },
+    },
+    "math/rgbFromOkLCh": {
+        blocks: ["FlowGraphRGBFromOkLChBlock" /* FlowGraphBlockNames.RGBFromOkLCh */],
+        inputs: {
+            values: {
+                l: { name: "l", gltfType: "number" },
+                c: { name: "c", gltfType: "number" },
+                h: { name: "h", gltfType: "number" },
+            },
+        },
+        outputs: {
+            values: {
+                r: { name: "r" },
+                g: { name: "g" },
+                b: { name: "b" },
+            },
+        },
+    },
+    // Quaternion spherical-linear interpolation. Inputs are two unit
+    // quaternions and an unclamped float coefficient.
+    "math/quatSlerp": getSimpleInputMapping("FlowGraphMathSlerpBlock" /* FlowGraphBlockNames.MathSlerp */, ["a", "b", "c"]),
+    // Vector spherical-linear interpolation (float2/float3). Inputs are two
+    // vectors and an unclamped float coefficient.
+    "math/slerp": getSimpleInputMapping("FlowGraphVectorSlerpBlock" /* FlowGraphBlockNames.VectorSlerp */, ["a", "b", "c"]),
     "math/eq": getSimpleInputMapping("FlowGraphEqualityBlock" /* FlowGraphBlockNames.Equality */, ["a", "b"]),
+    // Reference equality. The spec defines `ref/eq` as: true if both refs are
+    // null, true if both refer to the same object (regardless of whether it
+    // exists), false otherwise. FlowGraphEqualityBlock falls through to a
+    // strict `===` comparison for non-vector/matrix/numeric types, which
+    // already produces the spec-defined behaviour for Babylon object refs.
+    "ref/eq": getSimpleInputMapping("FlowGraphEqualityBlock" /* FlowGraphBlockNames.Equality */, ["a", "b"]),
     "math/lt": getSimpleInputMapping("FlowGraphLessThanBlock" /* FlowGraphBlockNames.LessThan */, ["a", "b"]),
     "math/le": getSimpleInputMapping("FlowGraphLessThanOrEqualBlock" /* FlowGraphBlockNames.LessThanOrEqual */, ["a", "b"]),
     "math/gt": getSimpleInputMapping("FlowGraphGreaterThanBlock" /* FlowGraphBlockNames.GreaterThan */, ["a", "b"]),
@@ -469,6 +554,16 @@ const gltfToFlowGraphMapping = {
                 scale: { name: "scaling" },
             },
         },
+        extraProcessor(_gltfBlock, _declaration, _mapping, _parser, serializedObjects) {
+            var _a;
+            // KHR_interactivity step 4 of the matDecompose algorithm requires a non-decomposable matrix to still
+            // report the extracted translation and the raw column lengths, instead of the type defaults the
+            // FlowGraph block emits by default. The block has no `isValid` output in glTF, so the caller can only
+            // observe those values.
+            (_a = serializedObjects[0]).config || (_a.config = {});
+            serializedObjects[0].config.keepDegenerateComponents = true;
+            return serializedObjects;
+        },
     },
     "math/quatConjugate": getSimpleInputMapping("FlowGraphConjugateBlock" /* FlowGraphBlockNames.Conjugate */, ["a"]),
     "math/quatMul": {
@@ -508,6 +603,40 @@ const gltfToFlowGraphMapping = {
     },
     "math/quatToAxisAngle": getSimpleInputMapping("FlowGraphAxisAngleFromQuaternionBlock" /* FlowGraphBlockNames.AxisAngleFromQuaternion */, ["a"]),
     "math/quatFromDirections": getSimpleInputMapping("FlowGraphQuaternionFromDirectionsBlock" /* FlowGraphBlockNames.QuaternionFromDirections */, ["a", "b"]),
+    "math/quatFromUpForward": {
+        blocks: ["FlowGraphQuaternionFromUpForwardBlock" /* FlowGraphBlockNames.QuaternionFromUpForward */],
+        inputs: {
+            values: {
+                up: { name: "a", gltfType: "float3" },
+                forward: { name: "b", gltfType: "float3" },
+            },
+        },
+        outputs: {
+            values: {
+                value: { name: "value" },
+            },
+        },
+    },
+    // Tait–Bryan intrinsic Euler angles (x/y/z, in radians) to a rotation quaternion. The rotation
+    // order is selected by the `order` configuration string (default `yxz`).
+    "math/quatFromAngles": {
+        blocks: ["FlowGraphQuaternionFromAnglesBlock" /* FlowGraphBlockNames.QuaternionFromAngles */],
+        configuration: {
+            order: { name: "order", defaultValue: ["yxz"] },
+        },
+        inputs: {
+            values: {
+                x: { name: "a", gltfType: "number" },
+                y: { name: "b", gltfType: "number" },
+                z: { name: "c", gltfType: "number" },
+            },
+        },
+        outputs: {
+            values: {
+                value: { name: "value" },
+            },
+        },
+    },
     "math/combine2x2": {
         blocks: ["FlowGraphCombineMatrix2DBlock" /* FlowGraphBlockNames.CombineMatrix2D */],
         inputs: {
@@ -523,13 +652,6 @@ const gltfToFlowGraphMapping = {
                 value: { name: "value" },
             },
         },
-        extraProcessor(_gltfBlock, _declaration, _mapping, _parser, serializedObjects) {
-            var _a;
-            // configure it to work the way glTF specifies
-            (_a = serializedObjects[0]).config || (_a.config = {});
-            serializedObjects[0].config.inputIsColumnMajor = true;
-            return serializedObjects;
-        },
     },
     "math/extract2x2": {
         blocks: ["FlowGraphExtractMatrix2DBlock" /* FlowGraphBlockNames.ExtractMatrix2D */],
@@ -567,13 +689,6 @@ const gltfToFlowGraphMapping = {
                 value: { name: "value" },
             },
         },
-        extraProcessor(_gltfBlock, _declaration, _mapping, _parser, serializedObjects) {
-            var _a;
-            // configure it to work the way glTF specifies
-            (_a = serializedObjects[0]).config || (_a.config = {});
-            serializedObjects[0].config.inputIsColumnMajor = true;
-            return serializedObjects;
-        },
     },
     "math/extract3x3": {
         blocks: ["FlowGraphExtractMatrix3DBlock" /* FlowGraphBlockNames.ExtractMatrix3D */],
@@ -623,13 +738,6 @@ const gltfToFlowGraphMapping = {
                 value: { name: "value" },
             },
         },
-        extraProcessor(_gltfBlock, _declaration, _mapping, _parser, serializedObjects) {
-            var _a;
-            // configure it to work the way glTF specifies
-            (_a = serializedObjects[0]).config || (_a.config = {});
-            serializedObjects[0].config.inputIsColumnMajor = true;
-            return serializedObjects;
-        },
     },
     "math/extract4x4": {
         blocks: ["FlowGraphExtractMatrixBlock" /* FlowGraphBlockNames.ExtractMatrix */],
@@ -866,6 +974,11 @@ const gltfToFlowGraphMapping = {
             const serializedObject = serializedObjects[0];
             serializedObject.config || (serializedObject.config = {});
             serializedObject.config.incrementIndexWhenLoopDone = true;
+            // KHR_interactivity assets may run large finite loops (e.g. the math/random Monte Carlo
+            // conformance asset iterates 10k times), well above the block's conservative default guard.
+            // Raise the cap for interactivity for-loops only, per block, instead of mutating the
+            // process-wide FlowGraphForLoopBlock.MaxLoopIterations that every other FlowGraph relies on.
+            serializedObject.config.maxLoopIterations = InteractivityForLoopMaxIterations;
             return serializedObjects;
         },
     },
@@ -938,10 +1051,22 @@ const gltfToFlowGraphMapping = {
             flows: {
                 err: { name: "error" },
             },
+            values: {
+                // New spec renames this output to `lastDelay` (ref). Internally we still produce a
+                // FlowGraphInteger; the index is unique per delay so it acts as the opaque handle.
+                lastDelay: { name: "lastDelayIndex" },
+            },
         },
     },
     "flow/cancelDelay": {
         blocks: ["FlowGraphCancelDelayBlock" /* FlowGraphBlockNames.CancelDelay */],
+        inputs: {
+            values: {
+                // New spec renames this input to `delay` (ref). The underlying block reads an int
+                // from `delayIndex`; when a ref-string flows in we coerce it via the path converter.
+                delay: { name: "delayIndex" },
+            },
+        },
     },
     "variable/get": {
         blocks: ["FlowGraphGetVariableBlock" /* FlowGraphBlockNames.GetVariable */],
@@ -1088,6 +1213,7 @@ const gltfToFlowGraphMapping = {
     },
     "pointer/get": {
         blocks: ["FlowGraphGetPropertyBlock" /* FlowGraphBlockNames.GetProperty */, "FlowGraphJsonPointerParserBlock" /* FlowGraphBlockNames.JsonPointerParser */],
+        validation: ValidateJsonPointerTemplate,
         configuration: {
             pointer: { name: "jsonPointer", toBlock: "FlowGraphJsonPointerParserBlock" /* FlowGraphBlockNames.JsonPointerParser */ },
         },
@@ -1132,6 +1258,7 @@ const gltfToFlowGraphMapping = {
     },
     "pointer/set": {
         blocks: ["FlowGraphSetPropertyBlock" /* FlowGraphBlockNames.SetProperty */, "FlowGraphJsonPointerParserBlock" /* FlowGraphBlockNames.JsonPointerParser */],
+        validation: ValidateJsonPointerTemplate,
         configuration: {
             pointer: { name: "jsonPointer", toBlock: "FlowGraphJsonPointerParserBlock" /* FlowGraphBlockNames.JsonPointerParser */ },
         },
@@ -1184,6 +1311,7 @@ const gltfToFlowGraphMapping = {
     "pointer/interpolate": {
         // interpolate, parse the pointer and play the animation generated. 3 blocks!
         blocks: ["FlowGraphInterpolationBlock" /* FlowGraphBlockNames.ValueInterpolation */, "FlowGraphJsonPointerParserBlock" /* FlowGraphBlockNames.JsonPointerParser */, "FlowGraphPlayAnimationBlock" /* FlowGraphBlockNames.PlayAnimation */, "FlowGraphBezierCurveEasing" /* FlowGraphBlockNames.BezierCurveEasing */],
+        validation: ValidateJsonPointerTemplate,
         configuration: {
             pointer: { name: "jsonPointer", toBlock: "FlowGraphJsonPointerParserBlock" /* FlowGraphBlockNames.JsonPointerParser */ },
         },
@@ -1280,8 +1408,18 @@ const gltfToFlowGraphMapping = {
             values: {
                 animation: { name: "index", gltfType: "number", toBlock: "FlowGraphArrayIndexBlock" /* FlowGraphBlockNames.ArrayIndex */ },
                 speed: { name: "speed", gltfType: "number" },
-                startTime: { name: "from", gltfType: "number", dataTransformer: (time, parser) => [time[0] * parser._animationTargetFps] },
-                endTime: { name: "to", gltfType: "number", dataTransformer: (time, parser) => [time[0] * parser._animationTargetFps] },
+                startTime: {
+                    name: "from",
+                    gltfType: "number",
+                    convertConnectedTimeToFrames: true,
+                    dataTransformer: (time, parser) => [time[0] * parser._animationTargetFps],
+                },
+                endTime: {
+                    name: "to",
+                    gltfType: "number",
+                    convertConnectedTimeToFrames: true,
+                    dataTransformer: (time, parser) => [time[0] * parser._animationTargetFps],
+                },
             },
         },
         outputs: {
@@ -1355,7 +1493,12 @@ const gltfToFlowGraphMapping = {
         inputs: {
             values: {
                 animation: { name: "index", gltfType: "number", toBlock: "FlowGraphArrayIndexBlock" /* FlowGraphBlockNames.ArrayIndex */ },
-                stopTime: { name: "stopAtFrame", gltfType: "number", dataTransformer: (time, parser) => [time[0] * parser._animationTargetFps] },
+                stopTime: {
+                    name: "stopAtFrame",
+                    gltfType: "number",
+                    convertConnectedTimeToFrames: true,
+                    dataTransformer: (time, parser) => [time[0] * parser._animationTargetFps],
+                },
             },
         },
         outputs: {
@@ -1491,6 +1634,70 @@ function ValidateTypes(gltfBlock) {
     }
     return { valid: true };
 }
+/**
+ * Returns whether a literal path segment has an odd number of consecutive occurrences of any bracket character.
+ * Brackets used literally inside a path segment must be doubled, so an odd run means the segment is malformed.
+ * @param segment the literal path segment
+ * @returns true when the segment contains an odd run of brackets
+ */
+function HasOddBracketRun(segment) {
+    for (let index = 0; index < segment.length; index++) {
+        const character = segment[index];
+        if ("[]{}".indexOf(character) === -1) {
+            continue;
+        }
+        let runLength = 1;
+        while (segment[index + runLength] === character) {
+            runLength++;
+        }
+        if (runLength % 2 !== 0) {
+            return true;
+        }
+        index += runLength - 1;
+    }
+    return false;
+}
+/**
+ * Validates the `pointer` configuration value of a `pointer/*` operation, following the JSON Pointer Template
+ * Parsing steps of the KHR_interactivity specification. A template parameter must span an entire path segment, so
+ * a template such as `/materials/{materialRef}pbrMetallicRoughness/...` is a syntax error, and the specification
+ * requires the whole behavior graph to be rejected.
+ * @param gltfBlock the glTF interactivity node
+ * @returns the validation result
+ */
+function ValidateJsonPointerTemplate(gltfBlock) {
+    const pointer = gltfBlock.configuration?.pointer?.value?.[0];
+    if (typeof pointer !== "string") {
+        return { valid: false, error: "A pointer operation requires a string `pointer` configuration value" };
+    }
+    // A JSON Pointer (RFC 6901) is either empty or a sequence of `/`-prefixed reference tokens.
+    if (pointer.length !== 0 && pointer[0] !== "/") {
+        return { valid: false, error: `The JSON Pointer Template "${pointer}" is not a syntactically valid JSON Pointer` };
+    }
+    const invalid = (reason) => ({ valid: false, error: `The JSON Pointer Template "${pointer}" is invalid: ${reason}` });
+    const socketIds = new Set();
+    for (const segment of pointer.split("/")) {
+        const isIntegerParameter = segment[0] === "[" && segment[1] !== "[";
+        const isReferenceParameter = segment[0] === "{" && segment[1] !== "{";
+        if (!isIntegerParameter && !isReferenceParameter) {
+            if (HasOddBracketRun(segment)) {
+                return invalid(`the path segment "${segment}" contains an odd number of consecutive brackets`);
+            }
+            continue;
+        }
+        const closingBracket = isIntegerParameter ? "]" : "}";
+        const body = segment.substring(1, segment.length - 1);
+        if (segment.length < 3 || segment[segment.length - 1] !== closingBracket || /[[{]/.test(body) || /[\]}]/.test(body)) {
+            return invalid(`the template parameter path segment "${segment}" is malformed`);
+        }
+        const socketId = body.replace(/~1/g, "/").replace(/~0/g, "~");
+        if (socketIds.has(socketId)) {
+            return invalid(`the template parameter "${socketId}" is used more than once`);
+        }
+        socketIds.add(socketId);
+    }
+    return { valid: true };
+}
 export function getAllSupportedNativeNodeTypes() {
     return Object.keys(gltfToFlowGraphMapping);
 }
@@ -1660,7 +1867,7 @@ export function getAllSupportedNativeNodeTypes() {
    - Effective JSON Pointer Generation (`pointer/set`) [FlowGraphBlockNames.SetProperty, FlowGraphBlockNames.JsonPointerParser]
    - Pointer Get (`pointer/get`) [FlowGraphBlockNames.GetProperty, FlowGraphBlockNames.JsonPointerParser]
    - Pointer Set (`pointer/set`) [FlowGraphBlockNames.SetProperty, FlowGraphBlockNames.JsonPointerParser]
-   - Pointer Interpolate (`pointer/interpolate`) [FlowGraphBlockNames.ValueInterpolation, FlowGraphBlockNames.JsonPointerParser, FlowGraphBlockNames.PlayAnimation, FlowGraphBlockNames.Easing]
+   - Pointer Interpolate (`pointer/interpolate`) [FlowGraphBlockNames.ValueInterpolation, FlowGraphBlockNames.JsonPointerParser, FlowGraphBlockNames.PlayAnimation, FlowGraphBlockNames.BezierCurveEasing]
 
 ### Animation Control Nodes
 1. **Animation Play** (`animation/start`) FlowGraphBlockNames.PlayAnimation