> For the complete documentation index, see [llms.txt](https://morningheartgames.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://morningheartgames.gitbook.io/docs/gameplay-ability-toolkit/subsystems/montage.md). # Montage > Online doc: The Montage subsystem provides montage-style animation authoring for ability timing: animation clips, instruction events, sections, root motion, motion warping, slots, preview tooling, and animation driver backends. ![Practical montage timeline diagram showing tracks, clips, playhead, and preview area.](/files/TPbR14fVzZl02VG1MbIr) ## What It Does Montages let gameplay code and ability recipes react to authored animation timing. A montage can play animation clips, raise instruction events, expose named sections, drive root motion, move toward targets, and choose animation driver backends. ## When To Use It Use Montage when gameplay must line up with authored animation: melee hit windows, cast notifies, dodge timing, upper-body overlays, locomotion loops, or target-facing movement. Use plain Unity animation or direct Animator calls when the animation has no gameplay timing contract. ## Required Assets and Components | Item | Required | Notes | | ----------------------- | -------------- | --------------------------------------------------------------- | | `AnimationMontage` | Yes | Authoring asset with tracks, clips, sections, and instructions. | | `MontagePlayer` | Yes at runtime | Add to actors that play montages. | | `Animator` | Usually | Required by the built-in Unity animation driver. | | `MontageSlotConfig` | Optional | Use for upper-body, additive, or named slot behavior. | | `AnimationDriverConfig` | Optional | Selects Unity, Animancer, Game Creator, or custom backends. | ## Core Types | Type | Responsibility | | ----------------------------------------------------- | ----------------------------------------------------------------------------------- | | `AnimationMontage` | ScriptableObject containing tracks, playback settings, slot, and preview character. | | `MontageTrack` | Base track type. | | `MontageClip` | Base clip/range element. | | `TrackAnimation` | Animation clip playback, blend settings, root motion flag, and loop settings. | | `TrackSection` | Named sections and section jumping. | | `TrackInstructions` | Timed string events such as `Cast`, `Hit Start`, or `Combo End`. | | `TrackMotionWarping` | Move/rotate the actor toward a target during a range. | | `TrackRootMotionPosition` / `TrackRootMotionRotation` | Extract or apply root motion. | | `MontagePlayer` | Runtime player component. One montage can play per slot. | | `MontageSlotConfig` | Maps slot names to masks, additive flags, and explicit layers. | | `AnimationDriverConfig` | Selects the animation backend. | | `IAnimationDriver` | Runtime backend interface used by Unity, Animancer, or Game Creator drivers. | ## Authoring Flow 1. Create an asset with `Assets > Create > Animation > Montage`. 2. Open `Window > Animation > Track Montage Editor`. 3. Add an animation clip on the Animation track. 4. Add instruction clips for gameplay events. 5. Assign a slot if the montage should not use `DefaultSlot`. 6. Optionally assign `Preview Character`. 7. Add `MontagePlayer` to the actor. 8. Play the montage from an ability task, ability runtime, or Game Creator ability recipe. Preview windows: ``` Window > Animation > Track Montage Editor Window > Animation > Montage Preview Viewport ``` ## Playback Model `MontagePlayer` owns runtime state per slot. Starting a montage in a slot replaces only that slot. Other slots keep playing. ```mermaid flowchart LR Ability["Ability runtime or task"] Player["MontagePlayer"] Slot["Slot resolution"] Driver["IAnimationDriver"] Tracks["Montage tracks"] Events["Instructions, sections, clip enter/exit"] Ability --> Player --> Slot --> Driver Player --> Tracks --> Events --> Ability ``` Slot behavior: | Case | Result | | ---------------------- | ------------------------------------------------------------- | | `DefaultSlot` | Full-body base action unless slot config maps it differently. | | Named slot | Uses `MontageSlotConfig` mask/layer when present. | | Same slot starts again | Previous montage in that slot is cancelled and replaced. | | Different slot starts | Existing slot keeps playing. | | Natural completion | Played slot is released and completion callbacks fire. | | Manual stop/cancel | Slot stops with the montage blend-out time. | ## Animation Driver Behavior The built-in Unity driver uses a Playables `AnimationLayerMixerPlayable`. | Driver rule | Result | | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | Actor has an Animator Controller | The controller is kept as mixer layer 0, so controller locomotion can resume after a montage layer stops. | | Actor has no Animator Controller | The montage graph owns the output and destroys itself when no montage layers remain. | | Montage slot layer 0 with controller base | The montage is mapped above the controller base. | | Overlay slots | Use slot masks and additive settings from `MontageSlotConfig`. | | Natural completion | Backends that implement `IAnimationDriverCompletionHandler` can release bookkeeping without adding a second tail blend. | This matters for locomotion. A normal Animator Controller can remain as the base layer. A montage-driven locomotion setup should instead use infinite loop montage clips so the locomotion montage stays alive until replaced. ## Looping Clips `ClipAnimation` has explicit loop settings: | Field | Meaning | | ------------- | --------------------------------------------------- | | `Enable Loop` | Restart the animation clip when it reaches the end. | | `Loop Count` | Number of loop restarts. `-1` means indefinitely. | When `Enable Loop = true` and `Loop Count = -1`, the clip keeps the whole montage alive. `MontagePlayer` does not fire natural completion at `AnimationMontage.GetTotalDuration()` for that montage. The clip remains active and its normalized time repeats. Use this for idle and jog loops: ``` Enable Loop = true Loop Count = -1 ``` Do not use it for attacks, dodges, casts, hit reactions, or deaths unless the ability or gameplay state will stop the montage explicitly. ## Instruction Events Instruction clips are timed string notifies. Ability code can subscribe to `MontagePlayer.OnNotification` or use higher-level tasks and Game Creator events. Common names: | Event | Typical use | | ------------- | --------------------------------------------------- | | `Cast` | Spawn projectile or apply effect at the cast frame. | | `Hit Start` | Open a melee hit window. | | `Hit End` | Close a melee hit window. | | `Combo Start` | Allow the next melee input. | | `Combo End` | Stop accepting combo input. | For Game Creator melee abilities, `Hit Start` and `Hit End` are required. `Combo Start` and `Combo End` are optional but recommended for combo steps. ## Configuration Fields ### AnimationMontage | Field | Meaning | | ------------------------------ | ------------------------------------------------------------------------------------ | | `tracks` | Serialized track array. Defaults include animation, section, and instruction tracks. | | `defaultPlayRate` | Base play rate for the montage. | | `blendInTime` / `blendOutTime` | Default transition times. | | `allowSectionJumping` | Whether runtime can jump sections. | | `slot` | Slot name. Empty resolves to `DefaultSlot`. | | `previewCharacter` | Editor preview target. Empty uses the package-level preview character. | ### ClipAnimation | Field | Meaning | | ---------------------------- | ---------------------------------------------------- | | `Animation Clip` | Unity `AnimationClip` to play. | | `Play Rate` | Per-clip speed multiplier. | | `Avatar Mask` | Clip mask used when the slot has no mask. | | `Blend Mode` | Override or additive. | | `Use Root Motion` | Requests root motion while this clip is active. | | `Blend In` / `Blend Out` | Clip transition times. | | `Enable Loop` / `Loop Count` | Clip restart behavior. `-1` keeps the montage alive. | ### MontagePlayer | Field | Meaning | | -------------- | ----------------------------------------------------------------------------------- | | `driverConfig` | Local animation driver config. Empty uses project default or built-in Unity driver. | | `slotConfig` | Slot to mask/layer mapping. | | `showDebugGUI` | Runtime debug GUI. | ### Slot Config | Field | Meaning | | --------------- | ------------------------------------------ | | `slotName` | Slot such as `DefaultSlot` or `UpperBody`. | | `mask` | AvatarMask for the slot. | | `additive` | Whether playback is additive. | | `explicitLayer` | Layer index override. | ## Melee Timing For new melee content, put timing in montage instruction clips instead of fixed ability fields. Recommended melee authoring: 1. Put the attack animation on the Animation track. 2. Add `Hit Start` when the weapon should begin dealing damage. 3. Add `Hit End` when the weapon should stop dealing damage. 4. Add `Combo Start` and `Combo End` if the montage can chain. 5. Keep these markers close to the actual animation frames. 6. Test by activating the ability and watching damage timing, not only animation timing. This keeps combat timing tied to the animation asset. Changing a montage no longer requires updating separate windup/active/recovery numbers. ## Root Motion And Movement Root motion is requested by active animation clips and forwarded through the driver. The Unity driver recomputes `Animator.applyRootMotion` from active montage layers, then restores the original value when the graph is disposed. For authored gameplay movement such as dodge, you can combine: | Tool | Use | | ----------------------- | ------------------------------------------------------------- | | Movement ability recipe | Gameplay distance, curve, duration, self effects. | | Montage clip | Visual body motion. | | `Scale Time` | Match animation length to gameplay duration. | | Root motion tracks | Extract/apply authored motion when the ability owns movement. | ## Common Mistakes | Mistake | Result | Fix | | ------------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------- | | No `MontagePlayer` on actor | Runtime cannot play montages. | Add `MontagePlayer` to the actor with the `Animator`. | | Slot names differ by spelling | Wrong mask/layer or full-body playback. | Reuse stable slot names and `MontageSlotConfig`. | | Attack montage lacks `Hit Start` / `Hit End` | Game Creator melee cancels or never hits. | Add instruction clips to the montage. | | Locomotion clip loops but montage stops | Jog/idle disappears after one cycle. | Set `Enable Loop = true`, `Loop Count = -1`. | | Infinite loop used on an attack | Ability never naturally completes. | Use finite clips for attacks and casts. | | Depending on optional drivers without package installed | Compile errors or fallback driver. | Confirm integration package, define symbols, and backend registration. | | Preview is blank | No preview target. | Assign `previewCharacter` or confirm default preview assets exist. | ## Troubleshooting * If nothing plays, confirm the actor has `MontagePlayer` and an `Animator`. * If the wrong backend is used, inspect `AnimationDriverConfig` and `GASConfiguration.defaultAnimationDriverConfig`. * If upper-body overlay affects the whole body, inspect slot name and `MontageSlotConfig` mask. * If section jumps fail, confirm `allowSectionJumping`. * If instruction events do not arrive, confirm event names and the code path subscribing to `OnNotification`. * If the final pose hitches before locomotion resumes, confirm natural completion releases the slot and locomotion restarts or loops underneath. ## Extension Points * Implement `IAnimationDriver`. * Implement `IAnimationDriverCompletionHandler` if the backend has custom natural-completion behavior. * Add custom montage tracks and clip drawers. * Use optional [Animancer](/docs/gameplay-ability-toolkit/integrations/animancer.md) or [Game Creator](/docs/gameplay-ability-toolkit/integrations/game-creator.md) drivers. * React to instruction clips from ability runtime, tasks, or Game Creator recipes. ## Examples And Tests Examples: * Arena Demo: melee attacks, dodge, casts, projectile notifies, and locomotion loops. * Game Creator Arena: recipe-authored abilities using the same montage assets and HUD texture set. Tests: ``` DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/Montage/AnimationDriverConfigTests.cs DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/Tasks/MontageTaskTests.cs DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/Regression/MontageCancelClipExitTests.cs DevelopmentTests/GameplayAbilityToolkit/GameCreator.Tests/Editor/GameCreatorIntegrationTests.cs ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://morningheartgames.gitbook.io/docs/gameplay-ability-toolkit/subsystems/montage.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.