Animation graph override clips

[shrinktofit]

Re: #

Changelog

---

Continuous Integration

This pull request:

• [ ] needs automatic test cases check.

  Manual trigger with @cocos-robot run test cases afterward.

• [ ] does not change any runtime related code or build configuration

  If any reviewer thinks the CI checks are needed, please uncheck this option, then close and reopen the issue.

---

Compatibility Check

This pull request:

• [ ] changes public API, and have ensured backward compatibility with deprecated features.
• [ ] affects platform compatibility, e.g. system version, browser version, platform sdk version, platform toolchain, language version, hardware compatibility etc.
• [ ] affects file structure of the build package or build configuration which requires user project upgrade.
• [ ] introduces breaking changes, please list all changes, affected features and the scope of violation.

[github-actions[bot]]

Interface Check Report

! WARNING this pull request has changed these public interfaces:

@@ -5676,8 +5676,20 @@
             readonly __brand: "AnimationGraph";
         }
         /**
          * @en
+         * An opacity type which denotes what the animation graph variant seems like outside the engine.
+         * @zh
+         * 一个非透明的类型，它是动画图变体在引擎外部的表示。
+         */
+        export interface AnimationGraphVariantRunTime {
+            /**
+             * @internal
+             */
+            readonly __brand: "AnimationGraphVariant";
+        }
+        /**
+         * @en
          * The animation controller component applies an animation graph
          * to the node which it's attached to.
          * When the controller starts, the animation graph is instantiated.
          * Then you may set variables or query the running statuses of the animation graph instance.
@@ -5691,9 +5703,9 @@
              * 动画控制器所关联的动画图。
              * @en
              * The animation graph associated with the animation controller.
              */
-            graph: AnimationGraphRunTime | null;
+            graph: AnimationGraphRunTime | AnimationGraphVariantRunTime | null;
             /**
              * @zh 获取动画图的层级数量。如果控制器没有指定动画图，则返回 0。
              * @en Gets the count of layers in the animation graph.
              * If no animation graph is specified, 0 is returned.
@@ -5791,8 +5803,31 @@
              * @en Sets the weight of specified layer.
              * @param layer @en Index of the layer. @zh 层级索引。
              */
             setLayerWeight(layer: number, weight: number): void;
+            /**
+             * @zh 覆盖动画图实例中的动画剪辑。
+             * 对于每一对源剪辑、目标剪辑，
+             * 动画图（实例）中的出现的所有源剪辑都会被替换为目标剪辑，就好像动画图中一开始就使用的是目标剪辑。
+             * 不过，动画图当前的运转状态会依然保持不变，例如：
+             *
+             * - 若动作状态涉及的动画剪辑被替换，动作状态的播放进度百分比依然保持不变。
+             *
+             * - 若过渡的周期是相对的，即使在某一刻动画过渡的源头被替换，那么过渡的进度百分比也依然保持不变。
+             *
+             * 不管进行多少次覆盖，源剪辑应该一直指定为原始动画图中的动画剪辑。例如：
+             *
+             * ```ts
+             * // `originalClip` 是原始动画图中的剪辑对象，第一次希望将原剪辑覆盖为 `newClip1`，第二次希望将原剪辑覆盖为 `newClip2`
+             * animationController.overrideClips_experimental(new Map([ [originalClip, newClip1] ])); // 第一次覆盖
+             * animationController.overrideClips_experimental(new Map([ [newClip1, newClip2] ])); // 错误：第二次覆盖
+             * animationController.overrideClips_experimental(new Map([ [originalClip, newClip2] ])); // 正确：第二次覆盖
+             * ```
+             * @en Overrides the animation clips in animation graph instance.
+             * TODO
+             * @experimental
+             */
+            overrideClips_experimental(overrides: ___private._cocos_animation_marionette_graph_eval__ReadonlyClipOverrideMap): void;
         }
         /**
          * @en
          * Runtime clip status of a motion state.
@@ -61517,9 +61552,9 @@
         }
     }
     import { exoticAnimationTag, ExoticAnimation } from "cc/editor/exotic-animation";
     import { EmbeddedPlayer, embeddedPlayerCountTag, getEmbeddedPlayersTag, addEmbeddedPlayerTag, removeEmbeddedPlayerTag, clearEmbeddedPlayersTag } from "cc/editor/embedded-player";
-    import { AnimationMask } from "cc/editor/new-gen-anim";
+    import { AnimationMask, __private as ___private } from "cc/editor/new-gen-anim";
     export { Canvas as CanvasComponent, UIRenderer as RenderComponent, UIRenderer as UIRenderable, UIRenderer as Renderable2D, UITransform as UITransformComponent, Mask as MaskComponent, RichText as RichTextComponent, Sprite as SpriteComponent, UIMeshRenderer as UIModelComponent, LabelOutline as LabelOutlineComponent, Graphics as GraphicsComponent, UIStaticBatch as UIStaticBatchComponent, UIOpacity as UIOpacityComponent, Label as LabelComponent, MeshRenderer as ModelComponent, DirectionalLight as DirectionalLightComponent, Light as LightComponent, SphereLight as SphereLightComponent, SpotLight as SpotLightComponent, SkinnedMeshRenderer as SkinningModelComponent, SkinnedMeshBatchRenderer as BatchedSkinningModelComponent, SkinnedMeshUnit as SkinningModelUnit, Animation as AnimationComponent, AudioSource as AudioSourceComponent, Node as BaseNode, Camera as CameraComponent, ModelRenderer as RenderableComponent, Billboard as BillboardComponent, Line as LineComponent, ParticleSystem as ParticleSystemComponent, SkeletalAnimation as SkeletalAnimationComponent, Button as ButtonComponent, EditBox as EditBoxComponent, Layout as LayoutComponent, ProgressBar as ProgressBarComponent, ScrollBar as ScrollBarComponent, ScrollView as ScrollViewComponent, Slider as SliderComponent, Toggle as ToggleComponent, ToggleContainer as ToggleContainerComponent, Widget as WidgetComponent, PageView as PageViewComponent, PageViewIndicator as PageViewIndicatorComponent, SafeArea as SafeAreaComponent, UICoordinateTracker as UICoordinateTrackerComponent, BlockInputEvents as BlockInputEventsComponent } from "cc";
     import { isCCClassOrFastDefined as _isCCClassOrFastDefined, Details as _Details } from "cc";
     import { CCON } from "cc/editor/serialization";
     export {};