@babylonjs/loaders 9.28.0 → 9.30.0

package/glTF/2.0/Extensions/KHR_interactivity/interactivityGraphExporter.d.ts

@@ -129,7 +129,7 @@ export interface IKHRInteractivityExportProvider {
     /**
      * Builds the canonical extension after glTF entity indices are finalized.
      * @param context final serializer remapping context
-     * @returns ratified KHR_interactivity extension payload
+     * @returns KHR_interactivity extension payload
      */
     build(context: IKHRInteractivitySerializerContext): IKHRInteractivity;
 }
@@ -141,6 +141,12 @@ export interface IKHRInteractivityExportOptions {
     document?: IKHRInteractivityDocument;
     /** Loader glTF tree used to resolve original entity references. */
     sourceGLTF?: IGLTF;
+    /**
+     * Whether export patches the retained source document instead of reserializing the scene.
+     * Preserves source entity indices, extension-backed pointers, and imported compatibility flow sockets.
+     * Requires sourceGLTF and buildWithSourceIndices; runtime scene changes are not exported.
+     */
+    preserveSourceDocument?: boolean;
     /** Root default graph index. Defaults to the canonical document selection or zero. */
     defaultGraphIndex?: number;
     /** Target animation frame rate used by imported animation composites. Defaults to 60. */
@@ -171,6 +177,7 @@ export declare class KHRInteractivityExportPlan implements IKHRInteractivityExpo
     private _additionalExtensionsUsed;
     private readonly _rootDiagnostics;
     private _isPreflight;
+    private _sourceIndexContext?;
     /** Whether KHR_interactivity is required in the exported asset. */
     readonly required: boolean;
     /** Additional operation/companion extensions referenced by the exported graphs. */
@@ -195,7 +202,14 @@ export declare class KHRInteractivityExportPlan implements IKHRInteractivityExpo
      * @returns canonical KHR_interactivity payload
      */
     build(context: IKHRInteractivitySerializerContext): IKHRInteractivity;
+    /**
+     * Builds a graph for patching the original glTF document using its existing entity indices.
+     * Companion node extensions are already present in that document and are retained by the patcher.
+     * @returns canonical KHR_interactivity payload with source glTF indices
+     */
+    buildWithSourceIndices(): IKHRInteractivity;
     private _getSourceGraph;
+    private _createSourceIndexContext;
     private _validateBuildWithSourceIndices;
     private _analyzeGraphs;
     private _classifyStandaloneBlock;

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

@@ -401,6 +401,9 @@ export class KHRInteractivityExportPlan {
         this._additionalExtensionsUsed = [];
         this._rootDiagnostics = [];
         this._isPreflight = false;
+        if (_options.preserveSourceDocument && !_options.sourceGLTF) {
+            throw new Error("Source-preserving interactivity export requires the source glTF document.");
+        }
         this.required = _options.required ?? true;
         this.additionalExtensionsRequired = Array.from(new Set(_options.additionalExtensionsRequired ?? [])).sort();
         this._refreshAnalysis();
@@ -463,6 +466,9 @@ export class KHRInteractivityExportPlan {
      * @returns canonical KHR_interactivity payload
      */
     build(context) {
+        if (this._options.preserveSourceDocument && context !== this._sourceIndexContext) {
+            throw new Error("Source-preserving interactivity export must use buildWithSourceIndices().");
+        }
         this._refreshAnalysis();
         if (!this._analysis.representable) {
             throw new KHRInteractivityExportError(this._analysis.diagnostics);
@@ -489,6 +495,17 @@ export class KHRInteractivityExportPlan {
         }
         return source;
     }
+    /**
+     * Builds a graph for patching the original glTF document using its existing entity indices.
+     * Companion node extensions are already present in that document and are retained by the patcher.
+     * @returns canonical KHR_interactivity payload with source glTF indices
+     */
+    buildWithSourceIndices() {
+        if (!this._options.sourceGLTF) {
+            throw new Error("Source glTF data is required to retain entity indices.");
+        }
+        return this.build(this._createSourceIndexContext());
+    }
     _getSourceGraph(graph, graphIndex) {
         const documentGraph = this._options.document?.graphs[graphIndex]?.source;
         if (documentGraph) {
@@ -497,11 +514,13 @@ export class KHRInteractivityExportPlan {
         const provenance = graph.metadata?.khrInteractivity;
         return provenance?.source ? CloneKHRInteractivityGraph(provenance.source) : undefined;
     }
-    _validateBuildWithSourceIndices() {
-        const diagnostics = [];
+    _createSourceIndexContext() {
+        if (this._sourceIndexContext) {
+            return this._sourceIndexContext;
+        }
         const sourceGLTF = this._options.sourceGLTF;
         const indexOrUndefined = (index) => (index !== undefined && index >= 0 ? index : undefined);
-        const context = {
+        return (this._sourceIndexContext = {
             getNodeCount: () => sourceGLTF?.nodes?.length ?? 0,
             getNodeIndex: (node) => indexOrUndefined(sourceGLTF?.nodes?.findIndex((candidate) => candidate._babylonTransformNode === node)),
             getAnimationIndex: (animation) => indexOrUndefined(sourceGLTF?.animations?.findIndex((candidate) => candidate._babylonAnimationGroup === animation)),
@@ -509,7 +528,11 @@ export class KHRInteractivityExportPlan {
             getMaterialIndex: (material) => indexOrUndefined(sourceGLTF?.materials?.findIndex((candidate) => Object.values(candidate._data ?? {}).some((entry) => entry.babylonMaterial === material))),
             getRootIndex: (collection, entity) => this._getSourceRootIndex(collection, entity),
             setNodeExtension: () => { },
-        };
+        });
+    }
+    _validateBuildWithSourceIndices() {
+        const diagnostics = [];
+        const context = this._createSourceIndexContext();
         this._isPreflight = true;
         try {
             for (const analysis of this._graphAnalyses) {
@@ -639,8 +662,9 @@ export class KHRInteractivityExportPlan {
             const declaration = source.declarations?.[sourceNode.declaration];
             const declarationModel = this._options.document?.graphs[graphIndex]?.declarations[sourceNode.declaration];
             const operation = declaration ? _FullOperationName(declaration.op, declaration.extension) : "";
-            const mapping = declaration && declarationModel?.support !== "unsupported-extension" ? getMappingForDeclaration(declaration, false) : undefined;
             const blocks = groups.get(nodeIndex) ?? [];
+            const hasCompatibilityRuntime = this._options.preserveSourceDocument && blocks.some((block) => block.getClassName() !== _UnsupportedBlockClassName);
+            const mapping = declaration && (declarationModel?.support !== "unsupported-extension" || hasCompatibilityRuntime) ? getMappingForDeclaration(declaration, false) : undefined;
             const diagnostics = [];
             let classification = mapping && mapping.blocks.length > 1 ? "inverse-composite" : "exact";
             if (!declaration) {
@@ -653,7 +677,7 @@ export class KHRInteractivityExportPlan {
                     message: `Declaration index ${sourceNode.declaration} is unavailable.`,
                 });
             }
-            else if (declaration.extension === "BABYLON") {
+            else if (declaration.extension === "BABYLON" && !this._options.preserveSourceDocument) {
                 classification = "unsupported";
                 _PushDiagnostic(diagnostics, {
                     code: "BLOCK_UNSUPPORTED",
@@ -1007,7 +1031,7 @@ export class KHRInteractivityExportPlan {
                 });
             }
         }
-        return graph;
+        return this._options.preserveSourceDocument && _JsonEquivalent(graph, analysis.source) ? CloneKHRInteractivityGraph(analysis.source) : graph;
     }
     _rebuildNode(graph, sourceNode, logicalNode, graphAnalysis, context, diagnostics) {
         const node = _CloneJson(sourceNode);
@@ -1178,7 +1202,7 @@ export class KHRInteractivityExportPlan {
                 ? _CloneJson(sourceNode.flows[socket])
                 : { node: provenance.nodeIndex };
             rebuiltFlow.node = provenance.nodeIndex;
-            if (provenance.socket === "in") {
+            if (provenance.socket === "in" && !(this._options.preserveSourceDocument && rebuiltFlow.socket === "in")) {
                 delete rebuiltFlow.socket;
             }
             else {
@@ -1187,7 +1211,11 @@ export class KHRInteractivityExportPlan {
             _SetOwnProperty(rebuiltFlows, socket, rebuiltFlow);
         }
         if (Object.keys(rebuiltFlows).length > 0) {
-            node.flows = rebuiltFlows;
+            node.flows = this._options.preserveSourceDocument
+                ? Object.fromEntries([...new Set([...Object.keys(sourceNode.flows ?? {}), ...Object.keys(rebuiltFlows)])]
+                    .filter((socket) => Object.prototype.hasOwnProperty.call(rebuiltFlows, socket))
+                    .map((socket) => [socket, rebuiltFlows[socket]]))
+                : rebuiltFlows;
         }
         else {
             delete node.flows;
@@ -1304,7 +1332,7 @@ export class KHRInteractivityExportPlan {
             return Object.prototype.hasOwnProperty.call(node.flows ?? {}, socket);
         }
         const fixed = _GetOwn(mappings, socket);
-        if (fixed && !fixed.compatibilityOnly) {
+        if (fixed && (!fixed.compatibilityOnly || (this._options.preserveSourceDocument && Object.prototype.hasOwnProperty.call(node.flows ?? {}, socket)))) {
             return true;
         }
         if (!Object.keys(mappings ?? {}).some((key) => key.startsWith("[") && key.endsWith("]"))) {
@@ -1451,7 +1479,7 @@ export class KHRInteractivityExportPlan {
             const rebuiltReference = _CloneJson(sourceValue);
             delete rebuiltReference.value;
             rebuiltReference.node = provenance.nodeIndex;
-            if (provenance.socket === "value") {
+            if (provenance.socket === "value" && !(this._options.preserveSourceDocument && rebuiltReference.socket === "value")) {
                 delete rebuiltReference.socket;
             }
             else {
@@ -1643,8 +1671,7 @@ export class KHRInteractivityExportPlan {
                 _JsonEquivalent(_GetConfigurationBlock(logicalNode, property)?.config?.[property.name], provenance.runtimeValue) &&
                 !_IsValidConfigurationValue(provenance.sourceValue, property, graph, this._options.sourceGLTF?.nodes?.length);
             if (!preservesFallback && property.indexSource === "assetNodes" && current.length === 1 && typeof current[0] === "number") {
-                const sourceNode = this._options.sourceGLTF?.nodes?.[current[0]]?._babylonTransformNode;
-                const remapped = sourceNode ? context.getNodeIndex(sourceNode) : undefined;
+                const remapped = this._getRemappedRootIndex("nodes", current[0], context);
                 if (remapped === undefined) {
                     _PushDiagnostic(diagnostics, {
                         code: "REFERENCE_UNRESOLVED",
@@ -1687,6 +1714,9 @@ export class KHRInteractivityExportPlan {
                 const rootMatch = typeof rootReference === "string" ? /^\/([^/]+)$/.exec(rootReference) : undefined;
                 collection = rootMatch?.[1] ?? "";
                 if (!_KnownIndexedRootCollections.has(collection)) {
+                    if (this._options.preserveSourceDocument) {
+                        continue;
+                    }
                     _PushDiagnostic(diagnostics, {
                         code: "REFERENCE_UNRESOLVED",
                         graphIndex,
@@ -1712,6 +1742,9 @@ export class KHRInteractivityExportPlan {
                 const socket = node.values?.[indexPlaceholder[1]];
                 const path = `/graphs/${graphIndex}/nodes/${logicalNode.sourceIndex}/values/${indexPlaceholder[1]}`;
                 if (!socket || "node" in socket) {
+                    if (socket && this._options.preserveSourceDocument) {
+                        continue;
+                    }
                     _PushDiagnostic(diagnostics, {
                         code: "REFERENCE_UNRESOLVED",
                         graphIndex,
@@ -1967,7 +2000,7 @@ export class KHRInteractivityExportPlan {
             for (const [socket, value] of Object.entries(node.values ?? {})) {
                 if (!("node" in value) && graph.types?.[value.type]?.signature === "ref" && value.value) {
                     const pointerCollection = this._getPointerReferenceCollection(node, mapping, socket);
-                    if (pointerCollection === null) {
+                    if (pointerCollection === null && !(this._options.preserveSourceDocument && typeof value.value[0] === "string")) {
                         _PushDiagnostic(diagnostics, {
                             code: "REFERENCE_UNRESOLVED",
                             graphIndex,
@@ -2060,6 +2093,9 @@ export class KHRInteractivityExportPlan {
         return undefined;
     }
     _getRemappedRootIndex(collection, sourceIndex, context) {
+        if (this._options.preserveSourceDocument) {
+            return this._options.sourceGLTF?.[collection]?.[sourceIndex] ? sourceIndex : undefined;
+        }
         const indices = new Set(this._getSourceRootObjects(collection, sourceIndex)
             .map((target) => this._getExportedObjectIndex(collection, target, context))
             .filter((index) => index !== undefined));
@@ -2140,11 +2176,7 @@ export class KHRInteractivityExportPlan {
         if (!match || !_KnownIndexedRootCollections.has(match[1])) {
             return this._remapReference(reference, context, diagnostics, graphIndex, nodeIndex);
         }
-        const targets = this._getSourceRootObjects(targetCollection, parseInt(match[2], 10));
-        const targetIndices = new Set(targets
-            .map((target) => this._getExportedObjectIndex(targetCollection, target, context))
-            .filter((index) => index !== undefined));
-        const targetIndex = targetIndices.size === 1 ? targetIndices.values().next().value : undefined;
+        const targetIndex = this._getRemappedRootIndex(targetCollection, parseInt(match[2], 10), context);
         if (targetIndex === undefined) {
             _PushDiagnostic(diagnostics, {
                 code: "REFERENCE_UNRESOLVED",
@@ -2161,8 +2193,22 @@ export class KHRInteractivityExportPlan {
         if (!reference || reference.startsWith("/extensions/KHR_interactivity/events/") || reference.startsWith("/extensions/KHR_interactivity/delays/")) {
             return reference;
         }
-        const extensionCollection = /^\/extensions\/([^/]+)\/[^/]+\/(0|[1-9]\d*)(?:\/|$)/.exec(reference);
+        const extensionCollection = /^\/extensions\/([^/]+)\/([^/]+)\/(0|[1-9]\d*)(?:\/|$)/.exec(reference);
         if (extensionCollection && extensionCollection[1] !== "KHR_interactivity") {
+            if (this._options.preserveSourceDocument) {
+                const collection = this._options.sourceGLTF?.extensions?.[extensionCollection[1]]?.[extensionCollection[2]];
+                if (!Array.isArray(collection) || collection[Number(extensionCollection[3])] === undefined) {
+                    _PushDiagnostic(diagnostics, {
+                        code: "REFERENCE_UNRESOLVED",
+                        graphIndex,
+                        nodeIndex,
+                        path: `/graphs/${graphIndex}${nodeIndex === undefined ? "" : `/nodes/${nodeIndex}`}`,
+                        message: `Reference "${reference}" does not identify an entry in the retained source document.`,
+                    });
+                    return reference;
+                }
+                return reference;
+            }
             _PushDiagnostic(diagnostics, {
                 code: "REFERENCE_UNRESOLVED",
                 graphIndex,
@@ -2196,7 +2242,7 @@ export class KHRInteractivityExportPlan {
     }
     _validateExtensionReferencePreservation(reference, resolvedCollection, diagnostics, graphIndex, nodeIndex, path = `/graphs/${graphIndex}${nodeIndex === undefined ? "" : `/nodes/${nodeIndex}`}`) {
         const nestedExtensions = _GetPointerExtensionNames(reference).filter((extension) => extension !== "KHR_interactivity");
-        if (nestedExtensions.length === 0 || _CanPreserveNestedExtensionPointer(reference, resolvedCollection)) {
+        if (this._options.preserveSourceDocument || nestedExtensions.length === 0 || _CanPreserveNestedExtensionPointer(reference, resolvedCollection)) {
             return true;
         }
         _PushDiagnostic(diagnostics, {
@@ -2294,6 +2340,9 @@ export class KHRInteractivityExportPlan {
         return Array.from(extensions).sort();
     }
     _writeCompanionNodeExtensions(context, diagnostics) {
+        if (this._options.preserveSourceDocument) {
+            return;
+        }
         for (let sourceIndex = 0; sourceIndex < (this._options.sourceGLTF?.nodes?.length ?? 0); sourceIndex++) {
             const sourceNode = this._options.sourceGLTF.nodes[sourceIndex];
             for (const extensionName of _CompanionNodeExtensions) {