babylonjs-serializers 9.26.1 → 9.27.0

package/babylonjs.serializers.d.ts

@@ -182,10 +182,79 @@ declare namespace BABYLON {
     export function OmitDefaultValues<T extends object>(object: T, defaultValues: Partial<T>): T;
 
 
+    /**
+     * Indexed glTF root collections that KHR_interactivity references can target.
+     */
+    export type KhrInteractivityRootCollection = "nodes" | "animations" | "cameras" | "materials" | "meshes" | "textures" | "images" | "samplers" | "skins" | "scenes";
     /**
      * Mesh compression methods.
      */
     export type MeshCompressionMethod = "None" | "Draco";
+    /**
+     * Final entity remapping context exposed to a KHR_interactivity export provider.
+     */
+    export interface IKHRInteractivityExportContext {
+        /**
+         * Gets the final number of glTF nodes.
+         * @returns final glTF node count
+         */
+        getNodeCount(): number;
+        /**
+         * Gets the final glTF node index for a Babylon node.
+         * @param node Babylon node to resolve
+         * @returns final glTF node index, or undefined when the node was not exported
+         */
+        getNodeIndex(node: Node): number | undefined;
+        /**
+         * Gets the final glTF animation index for a Babylon animation group.
+         * @param animation Babylon animation group to resolve
+         * @returns final glTF animation index, or undefined when the animation was not exported
+         */
+        getAnimationIndex(animation: AnimationGroup): number | undefined;
+        /**
+         * Gets the final glTF camera index for a Babylon camera.
+         * @param camera Babylon camera to resolve
+         * @returns final glTF camera index, or undefined when the camera was not exported
+         */
+        getCameraIndex(camera: Camera): number | undefined;
+        /**
+         * Gets the final glTF material index for a Babylon material.
+         * @param material Babylon material to resolve
+         * @returns final glTF material index, or undefined when the material was not exported
+         */
+        getMaterialIndex(material: Material): number | undefined;
+        /**
+         * Gets the final glTF index for an imported Babylon entity in a root collection.
+         * @param collection target glTF root collection
+         * @param entity imported Babylon entity associated with the source entry
+         * @returns final glTF index, or undefined when the entity was not exported uniquely
+         */
+        getRootIndex?(collection: KhrInteractivityRootCollection, entity: object): number | undefined;
+        /**
+         * Writes a companion extension on an already-exported glTF node.
+         * @param nodeIndex final glTF node index
+         * @param extensionName companion extension name
+         * @param value companion extension payload
+         */
+        setNodeExtension(nodeIndex: number, extensionName: string, value: unknown): void;
+    }
+    /**
+     * Supplies a detached canonical KHR_interactivity document to the glTF serializer.
+     */
+    export interface IKHRInteractivityExportProvider {
+        /** Whether KHR_interactivity must be listed in extensionsRequired. */
+        readonly required: boolean;
+        /** Additional operation or companion extensions referenced by the graph. */
+        readonly additionalExtensionsUsed: readonly string[];
+        /** Additional extensions that must be listed in extensionsRequired. */
+        readonly additionalExtensionsRequired: readonly string[];
+        /**
+         * Builds the extension after final glTF entity indices are available.
+         * @param context final serializer remapping context
+         * @returns canonical KHR_interactivity extension payload
+         */
+        build(context: IKHRInteractivityExportContext): BABYLON.GLTF2.IKHRInteractivity;
+    }
     /**
      * Holds a collection of exporter options and parameters
      */
@@ -222,7 +291,8 @@ declare namespace BABYLON {
          */
         exportUnusedUVs?: boolean;
         /**
-         * Remove no-op root nodes when possible. Defaults to true.
+         * Remove no-op root nodes when possible. Defaults to true. No-op roots are preserved when
+         * {@link khrInteractivity} is provided because the graph may reference them.
          */
         removeNoopRootNodes?: boolean;
         /**
@@ -234,6 +304,11 @@ declare namespace BABYLON {
          * Indicates what compression method to apply to mesh data.
          */
         meshCompressionMethod?: MeshCompressionMethod;
+        /**
+         * Canonical KHR_interactivity export provider. The provider is evaluated only after scene
+         * nodes and animations have their final glTF indices.
+         */
+        khrInteractivity?: IKHRInteractivityExportProvider;
     }
     /**
      * Class for generating glTF data from a Babylon scene.
@@ -461,6 +536,7 @@ declare namespace BABYLON {
         readonly _bufferManager: BufferManager;
         private readonly _shouldExportNodeMap;
         private readonly _nodeMap;
+        private readonly _animationGroupMap;
         readonly _materialMap: Map<Material, number>;
         private readonly _camerasMap;
         private readonly _nodesCameraMap;
@@ -490,7 +566,7 @@ declare namespace BABYLON {
         private _loadExtensions;
         constructor(babylonScene?: Nullable<Scene>, options?: IExportOptions);
         dispose(): void;
-        get options(): Required<IExportOptions>;
+        get options(): Required<Omit<IExportOptions, "khrInteractivity">> & Pick<IExportOptions, "khrInteractivity">;
         static RegisterExtension(name: string, factory: (exporter: GLTFExporter) => IGLTFExporterExtensionV2, order?: number): void;
         static UnregisterExtension(name: string): boolean;
         private _generateJSON;
@@ -510,6 +586,18 @@ declare namespace BABYLON {
         private _listAvailableSkeletons;
         private _exportAndAssignSkeletons;
         private _exportSceneAsync;
+        /** @internal */
+        _getNodeIndex(node: Node): number | undefined;
+        /** @internal */
+        _getAnimationIndex(animationGroup: AnimationGroup): number | undefined;
+        /** @internal */
+        _getCameraIndex(camera: Camera): number | undefined;
+        /** @internal */
+        _getMaterialIndex(material: Material): number | undefined;
+        /** @internal */
+        _getRootIndex(collection: KhrInteractivityRootCollection, entity: object): number | undefined;
+        /** @internal */
+        _setNodeExtension(nodeIndex: number, extensionName: string, value: unknown): void;
         private _shouldExportNode;
         private _exportNodesAsync;
         private _collectBuffers;
@@ -633,6 +721,8 @@ declare namespace BABYLON {
          * @param bufferViews
          * @param accessors
          * @param animationSampleRate
+         * @param useRightHanded
+         * @param shouldExportAnimation
          */
         static _CreateNodeAnimationFromNodeAnimations(babylonNode: Node, runtimeGLTFAnimation: BABYLON.GLTF2.IAnimation, idleGLTFAnimations: BABYLON.GLTF2.IAnimation[], nodeMap: Map<Node, number>, nodes: BABYLON.GLTF2.INode[], bufferManager: BufferManager, bufferViews: BABYLON.GLTF2.IBufferView[], accessors: BABYLON.GLTF2.IAccessor[], animationSampleRate: number, useRightHanded: boolean, shouldExportAnimation?: (animation: Animation) => boolean): void;
         /**
@@ -647,6 +737,8 @@ declare namespace BABYLON {
          * @param bufferViews
          * @param accessors
          * @param animationSampleRate
+         * @param useRightHanded
+         * @param shouldExportAnimation
          */
         static _CreateMorphTargetAnimationFromMorphTargetAnimations(babylonNode: Node, runtimeGLTFAnimation: BABYLON.GLTF2.IAnimation, idleGLTFAnimations: BABYLON.GLTF2.IAnimation[], nodeMap: Map<Node, number>, nodes: BABYLON.GLTF2.INode[], bufferManager: BufferManager, bufferViews: BABYLON.GLTF2.IBufferView[], accessors: BABYLON.GLTF2.IAccessor[], animationSampleRate: number, useRightHanded: boolean, shouldExportAnimation?: (animation: Animation) => boolean): void;
         /**
@@ -660,8 +752,11 @@ declare namespace BABYLON {
          * @param bufferViews
          * @param accessors
          * @param animationSampleRate
+         * @param leftHandedNodes nodes that require right-handed conversion
+         * @param shouldExportAnimation optional animation filter
+         * @param animationGroupMap final glTF animation index for each exported Babylon animation group
          */
-        static _CreateNodeAndMorphAnimationFromAnimationGroups(babylonScene: Scene, glTFAnimations: BABYLON.GLTF2.IAnimation[], nodeMap: Map<Node, number>, bufferManager: BufferManager, bufferViews: BABYLON.GLTF2.IBufferView[], accessors: BABYLON.GLTF2.IAccessor[], animationSampleRate: number, leftHandedNodes: Set<Node>, shouldExportAnimation?: (animation: Animation) => boolean): void;
+        static _CreateNodeAndMorphAnimationFromAnimationGroups(babylonScene: Scene, glTFAnimations: BABYLON.GLTF2.IAnimation[], nodeMap: Map<Node, number>, bufferManager: BufferManager, bufferViews: BABYLON.GLTF2.IBufferView[], accessors: BABYLON.GLTF2.IAccessor[], animationSampleRate: number, leftHandedNodes: Set<Node>, shouldExportAnimation?: (animation: Animation) => boolean, animationGroupMap?: Map<AnimationGroup, number>): void;
         private static _AddAnimation;
         /**
          * Create a baked animation
@@ -1625,6 +1720,41 @@ declare namespace BABYLON {
      */
 
 
+    /**
+     * [Specification](https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_interactivity)
+     */
+    export class KHR_interactivity implements IGLTFExporterExtensionV2 {
+        private _exporter;
+        /** The extension name. */
+        readonly name = "KHR_interactivity";
+        /** Whether this extension is enabled for the current export. */
+        readonly enabled: boolean;
+        /** Whether this extension is required for the exported asset. */
+        readonly required: boolean;
+        /**
+         * @param _exporter owning glTF exporter
+         */
+        constructor(_exporter: GLTFExporter);
+        /** @internal */
+        dispose(): void;
+        /** @internal */
+        get wasUsed(): boolean;
+        /** @internal */
+        onExporting(): void;
+    }
+    /**
+     * Registers the KHR_interactivity glTF serializer extension with the {@link GLTFExporter}.
+     * Safe to call multiple times; only the first call has an effect.
+     */
+    export function RegisterKHR_interactivity(): void;
+
+
+    /**
+     * Re-exports the pure implementation and applies the runtime registration side effect.
+     * Import "./KHR_interactivity.pure" for tree-shakeable, side-effect-free usage.
+     */
+
+
     /**
      * [Specification](https://github.com/KhronosGroup/glTF/blob/main/extensions/2.0/Khronos/KHR_draco_mesh_compression/README.md)
      */