@babylonjs/loaders 9.26.2 → 9.27.0

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

@@ -1,12 +1,81 @@
-import { getMappingForDeclaration, getNoOpMappingForDeclaration, ParseDebugLogTemplate } from "./declarationMapper.js";
+import { getMappingForDeclaration, getNoOpMappingForDeclaration, HasDefaultInteractivityFlowInput, NormalizeInteractivityEventDataConfiguration, ParseDebugLogTemplate, } from "./declarationMapper.js";
 import { Logger } from "@babylonjs/core/Misc/logger.js";
 import { RandomGUID } from "@babylonjs/core/Misc/guid.js";
-import { CloneKHRInteractivityGraph, CreateEffectiveKHRInteractivityGraph, gltfTypeToBabylonType } from "./interactivityGraphModel.js";
+import { _CreateKHRInteractivityRuntimeValueSnapshot, CloneKHRInteractivityGraph, CreateEffectiveKHRInteractivityGraph, gltfTypeToBabylonType, KHR_INTERACTIVITY_SPECIFICATION_COMMIT, } from "./interactivityGraphModel.js";
 import { DelayReferencePrefix, EventReferencePrefix } from "./interactivityReferences.js";
 export { gltfTypeToBabylonType } from "./interactivityGraphModel.js";
 function _GetOwnMapping(mapping, key) {
     return mapping && Object.prototype.hasOwnProperty.call(mapping, key) ? mapping[key] : undefined;
 }
+function _CloneMetadataValue(value) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => _CloneMetadataValue(entry));
+    }
+    if (value !== null && typeof value === "object") {
+        const clone = {};
+        for (const [key, entry] of Object.entries(value)) {
+            Object.defineProperty(clone, key, {
+                configurable: true,
+                enumerable: true,
+                value: _CloneMetadataValue(entry),
+                writable: true,
+            });
+        }
+        return clone;
+    }
+    return value;
+}
+function _IsSerializableConfigurationValue(value) {
+    return (value === null ||
+        ["string", "number", "boolean"].includes(typeof value) ||
+        (Array.isArray(value) && value.every(_IsSerializableConfigurationValue)) ||
+        (typeof value === "object" && Object.values(value).every(_IsSerializableConfigurationValue)));
+}
+/**
+ * Captures import-time defaults for unconnected runtime inputs that have no authored KHR socket.
+ * @param flowGraph the fully parsed FlowGraph
+ * @internal
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export function _CaptureKHRInteractivityRuntimeInputDefaults(flowGraph) {
+    for (const block of flowGraph.getAllBlocks()) {
+        const provenance = block.metadata?.khrInteractivity;
+        if (!provenance) {
+            continue;
+        }
+        if (Object.prototype.hasOwnProperty.call(provenance.generatedConfiguration ?? {}, "eventData")) {
+            provenance.generatedConfigurationRuntime || (provenance.generatedConfigurationRuntime = {});
+            if (!Object.prototype.hasOwnProperty.call(provenance.generatedConfigurationRuntime, "eventData")) {
+                Object.defineProperty(provenance.generatedConfigurationRuntime, "eventData", {
+                    configurable: true,
+                    enumerable: true,
+                    value: _CreateKHRInteractivityRuntimeValueSnapshot(NormalizeInteractivityEventDataConfiguration(block.config?.eventData)),
+                    writable: true,
+                });
+            }
+        }
+        for (const input of block.dataInputs) {
+            if (input.isConnected()) {
+                continue;
+            }
+            const socketProvenance = input.metadata?.khrInteractivity;
+            if (socketProvenance) {
+                socketProvenance.runtimeValueSnapshot ?? (socketProvenance.runtimeValueSnapshot = _CreateKHRInteractivityRuntimeValueSnapshot(input._defaultValue));
+                continue;
+            }
+            if (provenance.generatedInputDefaults && Object.prototype.hasOwnProperty.call(provenance.generatedInputDefaults, input.name)) {
+                continue;
+            }
+            provenance.generatedInputDefaults || (provenance.generatedInputDefaults = {});
+            Object.defineProperty(provenance.generatedInputDefaults, input.name, {
+                configurable: true,
+                enumerable: true,
+                value: _CreateKHRInteractivityRuntimeValueSnapshot(input._defaultValue),
+                writable: true,
+            });
+        }
+    }
+}
 /**
  * Parses a KHR_interactivity graph definition (the raw glTF JSON object) into
  * the serialized FlowGraph form consumed by {@link ParseFlowGraphAsync}.
@@ -16,7 +85,7 @@ function _GetOwnMapping(mapping, key) {
  * {@link serializeToFlowGraph}.
  */
 export class InteractivityGraphToFlowGraphParser {
-    constructor(interactivityGraph, _gltf, _animationTargetFps = 60, _graphIndex = 0, _supportedExtensions, _declarationModels) {
+    constructor(interactivityGraph, _gltf, _animationTargetFps = 60, _graphIndex = 0, _supportedExtensions, _declarationModels, canonicalGraph) {
         this._gltf = _gltf;
         this._animationTargetFps = _animationTargetFps;
         this._graphIndex = _graphIndex;
@@ -39,6 +108,7 @@ export class InteractivityGraphToFlowGraphParser {
          * the last block) is not disturbed, then concatenated into the serialized graph.
          */
         this._insertedBlocks = [];
+        this._canonicalGraph = CloneKHRInteractivityGraph(canonicalGraph ?? interactivityGraph);
         this._interactivityGraph = this._declarationModels
             ? CreateEffectiveKHRInteractivityGraph(interactivityGraph, this._declarationModels, this._gltf.nodes?.length ?? 0)
             : CloneKHRInteractivityGraph(interactivityGraph);
@@ -53,20 +123,6 @@ export class InteractivityGraphToFlowGraphParser {
     get _strictValidation() {
         return !!this._declarationModels;
     }
-    _hasDefaultFlowInput(operation) {
-        if (operation === "flow/waitAll") {
-            return false;
-        }
-        return (operation.startsWith("flow/") ||
-            operation.startsWith("animation/") ||
-            operation === "pointer/set" ||
-            operation === "pointer/interpolate" ||
-            operation === "variable/set" ||
-            operation === "variable/interpolate" ||
-            operation === "event/send" ||
-            operation === "event/stopPropagation" ||
-            operation === "flow/log:BABYLON");
-    }
     _getAllowedDynamicValueSockets(operation, node, direction) {
         if ((operation === "debug/log" || operation === "flow/log:BABYLON") && direction === "input") {
             const message = node.configuration?.[operation === "debug/log" ? "message" : "messageTemplate"]?.value?.[0];
@@ -339,6 +395,16 @@ export class InteractivityGraphToFlowGraphParser {
             this._nodes.push({ blocks, fullOperationName: mapping.fullOperationName });
         }
     }
+    _createBlockProvenance(nodeIndex, declarationIndex, operation, role) {
+        return {
+            graphIndex: this._graphIndex,
+            nodeIndex,
+            declarationIndex,
+            operation,
+            role,
+            sourcePath: `/extensions/KHR_interactivity/graphs/${this._graphIndex}/nodes/${nodeIndex}`,
+        };
+    }
     _getEmptyBlock(className, type, nodeIndex, declarationIndex, role) {
         return {
             uniqueId: RandomGUID(),
@@ -352,17 +418,24 @@ export class InteractivityGraphToFlowGraphParser {
             metadata: nodeIndex === undefined
                 ? {}
                 : {
-                    khrInteractivity: {
-                        graphIndex: this._graphIndex,
-                        nodeIndex,
-                        declarationIndex,
-                        operation: type,
-                        role: role ?? 0,
-                        sourcePath: `/extensions/KHR_interactivity/graphs/${this._graphIndex}/nodes/${nodeIndex}`,
-                    },
+                    khrInteractivity: this._createBlockProvenance(nodeIndex, declarationIndex, type, role ?? 0),
                 },
         };
     }
+    _setSocketProvenance(connection, nodeIndex, declarationIndex, operation, role, kind, direction, socket) {
+        connection.metadata = {
+            ...(connection.metadata ?? {}),
+            khrInteractivity: {
+                ...this._createBlockProvenance(nodeIndex, declarationIndex, operation, role),
+                kind,
+                direction,
+                socket,
+            },
+        };
+    }
+    _getBlockRole(blocks, block) {
+        return block.metadata?.khrInteractivity?.role ?? blocks.indexOf(block);
+    }
     _createUnsupportedExtensionBlock(node, nodeIndex, mapping) {
         const block = this._getEmptyBlock("KHR_interactivity/FlowGraphUnsupportedInteractivityBlock", mapping.fullOperationName, nodeIndex, node.declaration, 0);
         const inputFlowSockets = new Set();
@@ -386,16 +459,24 @@ export class InteractivityGraphToFlowGraphParser {
             outputFlowSockets: Object.keys(node.flows ?? {}).sort(),
         };
         for (const socket of block.config.inputValueSockets) {
-            block.dataInputs.push(this._createNewSocketConnection(socket.name));
+            const connection = this._createNewSocketConnection(socket.name);
+            this._setSocketProvenance(connection, nodeIndex, node.declaration, mapping.fullOperationName, 0, "value", "input", socket.name);
+            block.dataInputs.push(connection);
         }
         for (const socket of block.config.outputValueSockets) {
-            block.dataOutputs.push(this._createNewSocketConnection(socket.name, true));
+            const connection = this._createNewSocketConnection(socket.name, true);
+            this._setSocketProvenance(connection, nodeIndex, node.declaration, mapping.fullOperationName, 0, "value", "output", socket.name);
+            block.dataOutputs.push(connection);
         }
         for (const socket of block.config.inputFlowSockets) {
-            block.signalInputs.push(this._createNewSocketConnection(socket));
+            const connection = this._createNewSocketConnection(socket);
+            this._setSocketProvenance(connection, nodeIndex, node.declaration, mapping.fullOperationName, 0, "flow", "input", socket);
+            block.signalInputs.push(connection);
         }
         for (const socket of block.config.outputFlowSockets) {
-            block.signalOutputs.push(this._createNewSocketConnection(socket, true));
+            const connection = this._createNewSocketConnection(socket, true);
+            this._setSocketProvenance(connection, nodeIndex, node.declaration, mapping.fullOperationName, 0, "flow", "output", socket);
+            block.signalOutputs.push(connection);
         }
         return block;
     }
@@ -516,6 +597,7 @@ export class InteractivityGraphToFlowGraphParser {
                 if (!block.signalOutputs.includes(socketOut)) {
                     block.signalOutputs.push(socketOut);
                 }
+                this._setSocketProvenance(socketOut, i, gltfNode.declaration, flowGraphBlocks.fullOperationName, this._getBlockRole(flowGraphBlocks.blocks, block), "flow", "output", flowKey);
                 // get the mapper for the input node - in case it mapped to multiple blocks
                 const inputMapper = this._mappings[this._interactivityGraph.nodes[inputNodeId].declaration]?.flowGraphMapping;
                 if (!inputMapper) {
@@ -541,7 +623,7 @@ export class InteractivityGraphToFlowGraphParser {
                     if (this._strictValidation && allowedDynamicInputs && !allowedDynamicInputs.has(flow.socket ?? "in")) {
                         flowInMapping = undefined;
                     }
-                    if (!flowInMapping && (flow.socket ?? "in") === "in" && this._hasDefaultFlowInput(nodeIn.fullOperationName)) {
+                    if (!flowInMapping && (flow.socket ?? "in") === "in" && HasDefaultInteractivityFlowInput(nodeIn.fullOperationName)) {
                         flowInMapping = { name: "in" };
                     }
                     if (!flowInMapping && !this._isUnsupportedExtensionBlock(nodeIn.blocks[0])) {
@@ -557,6 +639,7 @@ export class InteractivityGraphToFlowGraphParser {
                     socketIn = this._createNewSocketConnection(nodeInSocketName);
                     inputBlock.signalInputs.push(socketIn);
                 }
+                this._setSocketProvenance(socketIn, inputNodeId, this._interactivityGraph.nodes[inputNodeId].declaration, nodeIn.fullOperationName, this._getBlockRole(nodeIn.blocks, inputBlock), "flow", "input", flow.socket ?? "in");
                 // connect the sockets
                 socketIn.connectedPointIds.push(socketOut.uniqueId);
                 socketOut.connectedPointIds.push(socketIn.uniqueId);
@@ -593,6 +676,9 @@ export class InteractivityGraphToFlowGraphParser {
                 if (!block.dataInputs.includes(socketIn)) {
                     block.dataInputs.push(socketIn);
                 }
+                this._setSocketProvenance(socketIn, i, gltfNode.declaration, flowGraphBlocks.fullOperationName, this._getBlockRole(flowGraphBlocks.blocks, block), "value", "input", valueKey);
+                const socketProvenance = socketIn.metadata.khrInteractivity;
+                socketProvenance.sourceValue = _CloneMetadataValue(this._canonicalGraph.nodes?.[i]?.values?.[valueKey] ?? value);
                 // Captured before the connected branch below shadows `valueMapping`. When set and the
                 // value is supplied by a connection, the seconds→frames `dataTransformer` cannot run
                 // (it is parse-time only), so the raw connected value is scaled by a runtime multiply.
@@ -600,6 +686,8 @@ export class InteractivityGraphToFlowGraphParser {
                 if (value.value !== undefined) {
                     const convertedValue = this._parseVariable(value, valueMapping && valueMapping.dataTransformer);
                     context._connectionValues[socketIn.uniqueId] = convertedValue;
+                    socketIn.defaultValue = convertedValue;
+                    socketProvenance.runtimeValue = _CloneMetadataValue(convertedValue.value);
                 }
                 else if (typeof value.node !== "undefined") {
                     const nodeOutId = value.node;
@@ -654,9 +742,10 @@ export class InteractivityGraphToFlowGraphParser {
                         socketOut = this._createNewSocketConnection(socketOutName, true);
                         outBlock.dataOutputs.push(socketOut);
                     }
+                    this._setSocketProvenance(socketOut, nodeOutId, this._interactivityGraph.nodes[nodeOutId].declaration, nodeOut.fullOperationName, this._getBlockRole(nodeOut.blocks, outBlock), "value", "output", nodeOutSocketName);
                     // connect the sockets
                     if (convertConnectedTimeToFrames) {
-                        this._connectWithSecondsToFramesConversion(context, socketOut, socketIn, i, gltfNode.declaration);
+                        this._connectWithSecondsToFramesConversion(context, socketOut, socketIn, i, gltfNode.declaration, flowGraphBlocks.fullOperationName);
                     }
                     else {
                         socketIn.connectedPointIds.push(socketOut.uniqueId);
@@ -685,6 +774,93 @@ export class InteractivityGraphToFlowGraphParser {
                 }
                 flowGraphBlocks.blocks = outputMapper.flowGraphMapping.extraProcessor(gltfNode, declaration, outputMapper.flowGraphMapping, this, flowGraphBlocks.blocks, context, this._gltf);
             }
+            this._ensureMappedSocketProvenance(i, gltfNode, flowGraphBlocks.blocks, outputMapper);
+        }
+    }
+    _ensureMappedSocketProvenance(nodeIndex, node, blocks, mapping) {
+        const ensureConnections = (socketMappings, kind, direction) => {
+            for (const [sourceName, property] of Object.entries(socketMappings ?? {})) {
+                if ((sourceName.startsWith("[") && sourceName.endsWith("]")) || (this._strictValidation && property.compatibilityOnly)) {
+                    continue;
+                }
+                const block = (property.toBlock && blocks.find((candidate) => candidate.className === property.toBlock)) || blocks[0];
+                if (!block) {
+                    continue;
+                }
+                const connections = kind === "value" ? (direction === "input" ? block.dataInputs : block.dataOutputs) : direction === "input" ? block.signalInputs : block.signalOutputs;
+                let connection = connections.find((candidate) => candidate.name === property.name);
+                if (!connection) {
+                    connection = this._createNewSocketConnection(property.name, direction === "output");
+                    connections.push(connection);
+                }
+                this._setSocketProvenance(connection, nodeIndex, node.declaration, mapping.fullOperationName, this._getBlockRole(blocks, block), kind, direction, sourceName);
+            }
+        };
+        ensureConnections(mapping.flowGraphMapping.outputs?.values, "value", "output");
+        ensureConnections(mapping.flowGraphMapping.inputs?.flows, "flow", "input");
+        ensureConnections(mapping.flowGraphMapping.outputs?.flows, "flow", "output");
+        if (HasDefaultInteractivityFlowInput(mapping.fullOperationName)) {
+            const block = blocks[0];
+            if (block) {
+                let connection = block.signalInputs.find((candidate) => candidate.name === "in");
+                if (!connection) {
+                    connection = this._createNewSocketConnection("in");
+                    block.signalInputs.push(connection);
+                }
+                this._setSocketProvenance(connection, nodeIndex, node.declaration, mapping.fullOperationName, this._getBlockRole(blocks, block), "flow", "input", "in");
+            }
+        }
+        for (const [sourceKey, property] of Object.entries(mapping.flowGraphMapping.configuration ?? {})) {
+            const block = (property.toBlock && blocks.find((candidate) => candidate.className === property.toBlock)) || blocks[0];
+            const provenance = block?.metadata?.khrInteractivity;
+            if (!block || !provenance) {
+                continue;
+            }
+            const serializedRuntimeValue = block.config?.[property.name];
+            const runtimeValue = serializedRuntimeValue !== null && typeof serializedRuntimeValue === "object" && Object.prototype.hasOwnProperty.call(serializedRuntimeValue, "value")
+                ? serializedRuntimeValue.value
+                : serializedRuntimeValue;
+            provenance.configuration || (provenance.configuration = {});
+            const configurationProvenance = {
+                sourceValue: _CloneMetadataValue(this._canonicalGraph.nodes?.[nodeIndex]?.configuration?.[sourceKey]?.value),
+                runtimeValue: _CloneMetadataValue(runtimeValue),
+            };
+            Object.defineProperty(provenance.configuration, sourceKey, {
+                configurable: true,
+                enumerable: true,
+                value: configurationProvenance,
+                writable: true,
+            });
+        }
+        for (const block of blocks) {
+            const provenance = block.metadata?.khrInteractivity;
+            if (!provenance) {
+                continue;
+            }
+            const mappedConfigurationNames = new Set(Object.values(mapping.flowGraphMapping.configuration ?? {})
+                .filter((property) => (property.toBlock ? block.className === property.toBlock : provenance.role === 0))
+                .map((property) => property.name));
+            const ignoredConfigurationNames = new Set(["glTF"]);
+            for (const [key, value] of Object.entries(block.config ?? {})) {
+                if (mappedConfigurationNames.has(key) || ignoredConfigurationNames.has(key)) {
+                    continue;
+                }
+                const normalizedValue = key === "eventData"
+                    ? NormalizeInteractivityEventDataConfiguration(value)
+                    : value !== null && typeof value === "object" && Object.prototype.hasOwnProperty.call(value, "value")
+                        ? value.value
+                        : value;
+                if (!_IsSerializableConfigurationValue(normalizedValue)) {
+                    continue;
+                }
+                provenance.generatedConfiguration || (provenance.generatedConfiguration = {});
+                Object.defineProperty(provenance.generatedConfiguration, key, {
+                    configurable: true,
+                    enumerable: true,
+                    value: _CloneMetadataValue(normalizedValue),
+                    writable: true,
+                });
+            }
         }
     }
     _createNewSocketConnection(name, isOutput) {
@@ -709,9 +885,10 @@ export class InteractivityGraphToFlowGraphParser {
      * @param downstreamInput the data input socket that expects the time in frames
      * @param nodeIndex source node receiving the converted value
      * @param declarationIndex source declaration used by the receiving node
+     * @param operation owning KHR operation
      */
-    _connectWithSecondsToFramesConversion(context, upstreamOutput, downstreamInput, nodeIndex, declarationIndex) {
-        const multiplyBlock = this._getEmptyBlock("FlowGraphMultiplyBlock" /* FlowGraphBlockNames.Multiply */, "FlowGraphMultiplyBlock" /* FlowGraphBlockNames.Multiply */, nodeIndex, declarationIndex, -1);
+    _connectWithSecondsToFramesConversion(context, upstreamOutput, downstreamInput, nodeIndex, declarationIndex, operation) {
+        const multiplyBlock = this._getEmptyBlock("FlowGraphMultiplyBlock" /* FlowGraphBlockNames.Multiply */, operation, nodeIndex, declarationIndex, -1);
         // Scalar (float) multiply; matches how the `math/mul` mapping configures the block.
         multiplyBlock.config = { type: "number" /* FlowGraphTypes.Number */ };
         const inputA = this._createNewSocketConnection("a");
@@ -720,7 +897,9 @@ export class InteractivityGraphToFlowGraphParser {
         multiplyBlock.dataInputs.push(inputA, inputB);
         multiplyBlock.dataOutputs.push(output);
         // The second factor is the constant animation target fps.
-        context._connectionValues[inputB.uniqueId] = { type: "number" /* FlowGraphTypes.Number */, value: [this._animationTargetFps] };
+        const frameRateValue = { type: "number" /* FlowGraphTypes.Number */, value: [this._animationTargetFps] };
+        context._connectionValues[inputB.uniqueId] = frameRateValue;
+        inputB.defaultValue = frameRateValue;
         // upstream time output -> multiply.a
         inputA.connectedPointIds.push(upstreamOutput.uniqueId);
         upstreamOutput.connectedPointIds.push(inputA.uniqueId);
@@ -776,6 +955,13 @@ export class InteractivityGraphToFlowGraphParser {
         const allBlocks = this._nodes.reduce((acc, val) => acc.concat(val.blocks), []).concat(this._insertedBlocks);
         return {
             name: this._interactivityGraph.name ?? `Graph ${this._graphIndex + 1}`,
+            metadata: {
+                khrInteractivity: {
+                    graphIndex: this._graphIndex,
+                    specificationCommit: KHR_INTERACTIVITY_SPECIFICATION_COMMIT,
+                    source: CloneKHRInteractivityGraph(this._canonicalGraph),
+                },
+            },
             rightHanded: true,
             allBlocks,
             executionContexts: [context],