Animation Editor

The Animation Editor is the central interface in MSMotion for authoring and editing character animations in edit mode. It provides a visual timeline-based environment for directly modifying native Unity Animation Clips (.anim files) with complete Undo/Redo support, real-time Scene view previews, and advanced keyframe manipulation tools.

Unlike Unity's built-in Animation window, which is object-centric and requires setting up Animators and recording states, the MSMotion Animation Editor is asset-first. You load and edit the animation asset directly, previewing the results against any compatible character model in the scene.

Editor Interface Layout

When you open the Animation Editor (Tools > Maharaja Studio > MsMotion > Animation Editor), the interface is divided into three main functional zones:

+-----------------------------------------------------------------------------+
|                               Top Toolbar                                   |
+-----------------------------------------------------------------------------+
|                     |                                                       |
|                     |                                                       |
|                     |                   Timeline Ruler                      |
|                     +-------------------------------------------------------+
|    Left Sidebar     |                                                       |
|       Panels        |                   Scrubber & Tracks                   |
|                     |                                                       |
|                     |                                                       |
|                     |                                                       |
+---------------------+-------------------------------------------------------+

Figure 1: Overview of the Animation Editor Workspace

1. Top Toolbar

The top toolbar contains global controls for preview setup, play/pause clock manipulation, and undo/redo functions:

• Preview Root: A field to assign a character GameObject from the Scene. This character is used to preview the animation changes in real time.
• Play / Stop / Loop: Playback controls to run or halt the animation in edit mode.
• Reset Root: A toggle that forces the character to snap back to its original coordinate origin when the animation loop starts over.
• Auto-Key: Toggles automatic recording of keyframes when character bones are transformed in the Scene view.
• Offset Mode: When active alongside Auto-Key, transforming a bone shifts the entire animation curve by that amount as a constant offset, rather than overwriting only the current frame.
• Undo / Redo: Quick buttons to step backward or forward through your edits.
• Live Link (Sync-to-Composition): Evaluates the full Composition context (IK, Masks, FX) live in the Scene view instead of just the raw animation clip.
• Ghost Preview: Shows a semi-transparent "ghost" of the full composition context blended in the background while you edit the raw clip.
• Export Pose: Bakes the current pose of the preview character into a new, single-frame Animation Clip asset.
• Settings (⚙): Opens the settings window to customize colors, row heights, and layout scales.

2. Left Sidebar Panels

An accordion-style container of collapsible sections containing settings and action buttons:

• Clip: Load assets, extract editable copies of read-only clips, and manage the clipboard.
• Range: Perform crop, delete, shift, stretch, snap, and bake operations across selected time regions.
• Curves: Search, filter, select, and delete animated property bindings.
• Key Editor: Detailed numerical control over a single selected keyframe's time, frame, value, and mathematical tangents.
• Advanced Tools: Panels for Mirror Pose, Tween Machine, Keyframe Optimizer, Keyframe Smoothing, and Extract Root Motion.
• Viewport: Toggle bone overlay shapes, colors, and name tags.
• IK / FK Solver: Controls for locking IK targets and blending procedural IK chains with base skeletal poses.
• Animation Events: Visual list of runtime event markers triggered by the clip.

3. Timeline Scrubber & Tracks

The main workspace where keyframes are visualized and manipulated:

• Timeline Ruler: Shows time in seconds or frames, and hosts event markers.
• Scrubber: The red vertical line indicating the current preview time. Drag the scrubber handle to scrub time.
• Tracks: Horizontal rows displaying keyframes for selected curves. Keys are colored by curve type (blue for floats, orange for object references).

Keyboard Shortcuts

The Animation Editor supports the following hotkeys to speed up your editing workflow. Make sure the editor window is in focus when using these shortcuts:

Playback & Navigation

Editing Actions

Viewport & Tools

Getting Started

Follow this guide to install the MSMotion Animation Editor and perform your first animation editing pass.

System Requirements

• Unity Version: Unity 2022.3 LTS or newer.
• UI Toolkit: Compatible with projects using Unity's modern UI Toolkit styling.
• Dependencies: Requires a character GameObject with an Animator component in the scene to enable active Scene view previews and IK solvers.

Installation

The Animation Editor is distributed as a Unity Package Manager (UPM) package. Add it to your project using one of the following methods:

Method A: Install via Git URL (Recommended)

1. In Unity, open Window > Package Manager.
2. Click the + button in the top-left corner of the Package Manager window.
3. Select Add package from git URL... from the dropdown menu.
4. Enter the package URL provided with your repository access or purchase:

   https://github.com/maharajastudio/com.maharajastudio.animation-editor.git

5. Click Add. Unity will download and import the package.

Method B: Install via Local Tarball

1. Download the package tarball file (.tgz) to your computer.
2. Open Window > Package Manager.
3. Click the + button in the top-left corner and select Add package from tarball...
4. Browse to and select the downloaded .tgz file.
5. Click Open to import.

Quick Start Tutorial: Your First Edit

Follow these steps to load a character model and modify an existing walk animation clip:

1. Open the Animation Editor

Open the editor window from the main Unity menu:
Go to Tools > Maharaja Studio > MsMotion > Animation Editor.

2. Set Up the Preview Character

1. Open or set up a Unity scene containing your character model.
2. Ensure the character GameObject has an Animator component.
3. In the Animation Editor's top toolbar, click the object picker next to Preview Root (or drag the character GameObject from the Hierarchy directly into the Preview Root field).

3. Load an Animation Clip

1. In the Project window, find a walk or idle Animation Clip asset (.anim).
2. Drag and drop the Animation Clip asset directly into the Animation Clip field in the sidebar's Clip panel.
3. Alternatively, select the character in the Hierarchy, make sure it has an Animator playing a clip, and click Load Selection in the editor sidebar to automatically populate the root and clip fields.

4. Play and Scrub

• Click ► Play in the toolbar to preview the animation running in edit mode.
• Drag the red Scrubber line horizontally across the timeline to inspect the pose frame-by-frame.
• Adjust the Loop and Reset Root toggles to control how the character loops.

5. Modify a Bone Pose (Auto-Key)

1. Turn on the Auto-Key toggle in the toolbar.
2. Move the timeline scrubber to the frame you want to edit (e.g. Frame 15).
3. In the Scene view, select one of the character's arm bones (e.g., shoulder or elbow).
4. Use Unity's standard rotation handle to rotate the arm.
5. Release the mouse. The timeline will register a red marker on that frame for the modified bone, saving your pose change directly into the animation clip.
6. Press Ctrl + Z to undo the change if needed.

Timeline & Range Operations

The timeline is where you navigate your animation, select time regions, and execute structural edits across ranges of keyframes.

Timeline Navigation

Navigating the timeline is simple and fluid:

• Scrubbing: Click and drag the red playhead line left or right across the ruler to scrub through time.
• Playback Shortcuts: Use the navigation buttons in the timeline toolbar:
  • First Frame (⏮): Snaps the playhead to the beginning (0.0s).
  • Previous Frame (⏪): Steps backward by one frame.
  • Play / Pause (⏯): Starts or pauses playhead movement.
  • Next Frame (⏩): Steps forward by one frame.
  • Last Frame (⏭): Snaps the playhead to the end of the clip.
• Zooming: Hover your mouse over the track area and hold Ctrl (or Alt) while scrolling the wheel. Zooming allows you to expand the timeline horizontally to see individual frame markings or contract it to see the entire clip.

Time and Frame Formats

You can view and enter time in two formats:

• Seconds: Entered numerically (e.g., 0.75 seconds).
• Frames: Entered as integers (e.g., Frame 45). The editor converts time using the clip's frame rate. For example, at a frame rate of 60 FPS, Frame 30 corresponds to 0.5 seconds.
• FPS Setting: Located in the sidebar's Range section. Change this value to adjust the grid density for snapping and baking actions.

Creating Selection Ranges

To select a specific segment of the animation:

1. Hover your cursor over the ruler track area.
2. Click and drag horizontally. A blue highlighted box will cover the selected time region.
3. To adjust the boundaries, hover over the left or right edges of the blue selection box until the cursor changes, then drag the handle.
4. The numerical boundaries will update in the Start and End fields in the sidebar. You can also type frame numbers directly in the Start Frame and End Frame fields to set an exact range.

Range Editing Actions

Once you have set a selection range, you can perform structural actions from the sidebar:

Copy, Cut, Paste, and Delete

• Copy Range: Copies only the keyframes within the selected range into the clipboard.
• Cut Range: Copies the keyframes in the selection and deletes them from the clip.
• Paste Range: Pastes the clipboard keyframes at the current playhead time.
• Delete Range: Clears all keyframes within the selection range.
• Ripple delete/cut: A toggle in the Range sidebar. When enabled, deleting or cutting a range automatically shifts all keyframes to the right of the selection leftward, closing the gap. When disabled, the space is left empty (holding the last pose).

Paste Modes

Select a mode from the Paste Mode dropdown before pasting:

• Overwrite: Clears any existing keyframes in the target time region and drops in the clipboard keys.
• Merge: Keeps existing keys and overlays the clipboard keys on top of them.
• Insert: Moves all subsequent keyframes to the right by the duration of the clipboard data to make room, then inserts the copied range.

Advanced Range Transformations

• Crop Clip: Destructive action that discards all animation before the selection start and after the selection end, keeping only the selected range.
• Trim Head: Instantly deletes all keyframes before the selection start.
• Trim Tail: Instantly deletes all keyframes after the selection end.
• Extract Range: Saves the selected segment as a brand-new standalone .anim file.
• Reverse: Flips the keyframe sequence in the selection backwards in time (great for reversing loops or walkcycles).
• Scale: Multiplies the timing of keys in the range by the value in the Scale field. For example, a scale of 2.0 doubles the duration (slowing it down), while 0.5 cuts the duration in half (speeding it up). Subsequent keys are shifted (rippled) to match.
• Snap: Aligns all keyframes in the range to the nearest frame grid interval defined by your FPS setting, removing sub-frame jitter.
• Bake: Samples the curves and generates a keyframe on every single frame grid line within the selection. Useful for freezing procedural overlays or preparing data for export.

Curve & Keyframe Editing

The Animation Editor provides detailed control over curves and individual keyframe coordinates. This guide explains how to isolate animated properties, modify key values, adjust tangents, and edit object reference tracks.

The Curves Panel

The Curves panel lists all animated properties contained within the clip. It allows you to isolate and operate on specific parts of your model:

• Filter Search: Type search terms (e.g., shoulder or rotation) into the search bar at the top of the panel to filter the list of curves.
• Operate on Selected Curves Only: When this toggle is enabled, range operations (such as Delete Range, Scale Range, or Snap Keys) affect only the curves you have highlighted in the list. Unselected curves remain untouched.
• Select All / Clear Selection: Quick buttons to highlight all visible curves or clear selection.
• Delete Selected: Removes the selected property curves entirely from the animation clip.
• Clear Scene Bones: Rather than manually searching for curves, you can highlight bones directly in the Scene view and click Clear Scene Bones:
  • Clear Selected Bones Only: Deletes animated curves for the selected bones.
  • Clear Selected Bones & Children: Deletes animated curves for the selected bones and their entire hierarchy (e.g., clearing an entire arm from the shoulder down). This tool automatically maps humanoid muscle properties and generic transform paths.

Single-Key Editor

When you select exactly one curve in the Curves list, the Key Editor panel activates, listing every keyframe on that curve.

Selecting Keyframes

• Scroller List: Select a keyframe from the scrollable list. Each entry displays its index, frame number, time in seconds, and value.
• Timeline Clicks: Click a keyframe marker directly in the timeline tracks.
• Select Nearest: Click the Nearest button to automatically highlight the keyframe closest to the playhead time.

Editing Keyframe Coordinates

To edit a keyframe:

1. Select a keyframe. Its coordinates will populate the editable fields.
2. Modify any of the following parameters:
   • Time: Change the keyframe's position in seconds.
   • Frame: Change the keyframe's frame position.
   • Value: Set the numerical value (for float curves like translation, rotation, or scale).
   • Tangents (Incoming / Outgoing): Adjust the numerical slope of the curve entering and leaving the keyframe to control acceleration.
3. Click Apply Key to save the changes.

Key Editing Toolbar Actions

• Add Key: Creates a new keyframe on the active curve at the time and value entered in the fields.
• Delete Key: Removes the selected keyframe.
• Nudge Buttons (-1 Frame / +1 Frame): Shifts the selected keyframe backward or forward in time by exactly one frame.
• Key Current: Samples the preview character's current pose and writes a keyframe onto all selected curves at the playhead time.
• Delete Current: Deletes any keyframes that sit on the current frame for all selected curves.

Working with Object Reference Curves

Some animation tracks drive object changes (such as swapping sprites, activating audio clips, or replacing materials) rather than numeric values:

• Visual Indicators: Object reference keyframes appear on the timeline tracks as orange diamond markers (instead of standard blue float markers).
• Object Picker: The Value field in the Key Editor converts into an Object Value field. Clicking this opens a selection popup displaying all assets in your project of that object type. Choose an asset to bind it to that keyframe.
• No Tangents: Because object changes are instantaneous swaps rather than gradients, tangent controls and the curve graph are automatically disabled when editing an object reference curve.

Animation Events

Animation Events allow you to trigger runtime visual effects, audio clips, camera shakes, or custom scripts at precise moments during an animation clip's playback (e.g., spawning dust particles on a footstep or playing a weapon swing sound).

Figure 7: Animation Events Timeline and Editor Panel

Visualizing Events on the Timeline

Events are represented visually on the timeline ruler:

• Event Markers: Small gold-colored diamond markers appearing along the bottom edge of the Timeline Ruler.
• Selection: Click a gold marker to highlight the event. The playhead snaps to the event's trigger time, and the Animation Events panel in the sidebar updates to display the event's settings.
• Dragging: Click and drag an event marker horizontally along the ruler to adjust its trigger time.

The Event Editor Panel

When you select an event, you can configure its parameters in the Animation Events panel at the bottom of the sidebar:

1. Identity & Timing

• Display Name: The human-readable label shown in the editor (e.g. FootstepLeft or Slash).
• Trigger Time: The precise time in seconds when the event fires.
• Duration: Set to 0.0 for one-shot events (like playing a sound once). Set to a value greater than 0.0 for sustained events (like keeping a particle emitter active or looping a sound over a range).
• Loop / Blend: Set fade-in and fade-out times to smoothly blend effects (such as audio volume or light brightness).

2. Socket Targets

• Target Bone: Enter the name of a character joint to attach the spawned effect to (e.g. Foot_L or Hand_R). Leave this empty to spawn the effect at the character's root position.

3. Transform Overrides

Specify local offset coordinates relative to the target bone:

• Position Offset: Shifts the effect's starting coordinates (e.g. offsetting a dust particle slightly below the foot joint).
• Rotation Override: Rotates the effect relative to the bone's orientation.
• Scale Override: Scales the size of the spawned effect.

4. Property Overrides

The editor allows you to dynamically set component parameters on the spawned effect at runtime (such as changing a Light component's intensity or calling custom script variables):

• Click the Property Override fields to target specific components and write value changes.
• Allow Editor Preview Overrides: Toggles whether these property overrides run inside the Unity Editor preview. Enable this with caution, as previewing scripts can modify scene assets.

Event Workflows

How to Create an Event

1. Move the timeline playhead to the frame where the event should occur.
2. Right-click on the timeline ruler.
3. Select Add Event (or click the Add Event button in the sidebar panel).
4. A new gold marker will appear, and you can customize its function and parameters in the sidebar.

How to Adjust Event Timing

• Click and drag the gold event marker on the ruler.
• Alternatively, enter the exact value in the Trigger Time field in the sidebar.

How to Delete an Event

1. Click the gold marker to select it.
2. Click the Delete button in the sidebar panel.

Bone Overlay & IK/FK Solver

Posing characters by navigating hierarchical bone structures can be tedious. The Animation Editor features a visual Bone Overlay and an interactive IK/FK Solver to pose models directly in the Scene view.

The Viewport Bone Overlay

The Viewport panel in the sidebar overlays a visual skeleton on top of your character in the Scene view, making it easy to see joint relationships and identify animated parts:

Overlay Toggles

• Show Bones: Draws the character's skeleton in the Scene view.
• Animated Bones Only: Hides non-animated bones, drawing only the bone paths that have active keyframes in the loaded clip.
• Bone Names: Draws text labels next to the joints in the viewport.

Visual Configurations (⚙ Settings Window)

You can customize the appearance of the bone wireframe:

• Bone Shape: Choose between wire Lines, Diamonds, or Boxes.
• Bone Size & Width: Scale sliders to match different character sizes (e.g. tiny creatures vs. giants).
• Color Schemes: Distinct colors for standard bones, animated bones, and currently selected bones.

Viewport Action Buttons

• Focus Root: Frames the Scene view camera directly onto the character.
• Use Selected Bone: Select a bone transform in the Scene view, then click this button. The editor will automatically locate that bone's animation curves in the Curves panel and filter the timeline to show only that bone's tracks.

IK / FK Solver Integration

The editor includes a real-time edit-mode Inverse Kinematics (IK) rig solver that runs inside the Scene view, allowing you to drag end-effectors (like hands or feet) and have the limb joints bend naturally:

Visualizing IK Handles

When an IK rig is assigned in the IK / FK Solver sidebar panel, colored handle markers appear in the Scene view at the active IK targets:

• Posing limbs: Click and drag an IK target handle (e.g., a hand control circle) in the Scene view. The elbow and shoulder joints bend in real time to follow your hand.
• Stable Pole Vectors: Limbs bend consistently based on pole vector configurations.
• Procedural Scales: The solver supports stretch-and-scale calculations, automatically adjusting bone lengths if the target is pulled beyond the limb's reach.

IK Auto-Keying Workflow

To prevent drag latency and handle loss, the editor handles pose calculations in two distinct steps:

1. Interactive Dragging: While dragging a handle, the character's limbs adjust visually in real time. The editor does not write keyframes mid-drag.
2. Keyframe Baking: When you release the mouse button, the solver calculates the final rotation and position values for all bones in the limb chain. If Auto-Key is enabled, it bakes these solved values as keys into the animation clip at the current playhead frame.

Transition & Bridging

When editing motion capture or cleaning up sequences, you often need to remove a bad segment (such as a glitch, pop, or idle gap) and blend the remaining ends together. The Remove + Bridge tool handles this process automatically.

How Bridging Works

Bridging performs two operations in sequence:

1. It deletes all keyframes within your selected time range.
2. It calculates the pose of the character immediately before the deleted range and the pose immediately after it.
3. It generates new transition keyframes across the gap to blend smoothly between those two boundary poses over a designated duration.

Original:    [--- Pose A ---] [======= Glitchy Segment =======] [--- Pose B ---]
Cut:         [--- Pose A ---]                                   [--- Pose B ---]
Bridged:     [--- Pose A ---] \____ Transition Blend (Bridge) _/ [--- Pose B ---]

Bridging Controls

Configure these controls in the sidebar's Range section before running the operation:

Transition Duration

Set the blend length in seconds in the Transition field.

• A short duration (e.g., 0.1s) creates a fast, sudden snap.
• A long duration (e.g., 0.5s) creates a slow, soft blend.
• The duration cannot exceed the total length of the removed segment.

Transition Mode

Choose how the editor interpolates values between the boundary poses:

Step-by-Step Workflows

Method 1: Bridge and Edit the Loaded Clip Directly

Use this method to modify your active animation in place:

1. Scrub to locate the segment you want to remove.
2. Drag on the ruler to highlight the range, or type the boundary times in the Start and End fields.
3. In the sidebar, set your desired blend length in the Transition field.
4. Choose Smooth or Linear from the Transition Mode dropdown.
5. Click Remove + Bridge.
6. The editor deletes the segment, ripples subsequent keys leftward, and inserts smooth blending keyframes across the transition window.

Method 2: Export a Bridged Copy

Use this method to generate a new file, leaving your source animation untouched:

1. Define the range, set the Transition duration, and choose the Transition Mode as described above.
2. Click Export Bridged in the sidebar.
3. A standard Unity save file dialog will open. Name the new asset (e.g. walk_cycle_bridged.anim) and choose a location.
4. The editor generates and saves the new, bridged clip without altering the loaded asset.

Advanced Editorial Tools

The Animation Editor includes seven advanced tools located in the Advanced Tools sidebar foldout. These tools streamline editing tasks like mirroring poses, blending keys, cleaning up noise, extracting root motion, removing root motion, and non-linear time warping.

1. Mirror Pose

The Mirror Pose tool flips the animation data across the character's center axis. This is useful for copying poses from the left arm to the right, or mirroring entire walk cycles.

Settings

• Target Options:
  • Current Frame Only: Mirrors only the pose at the current playhead time.
  • Selected Time Range: Mirrors animation keys falling within your active selection range.
  • Selected Keys: Mirrors only the specific keyframes highlighted in the timeline.
  • Entire Clip: Mirrors the animation across the full length of the clip.
• Limit to Selected Curves: When enabled, the mirror action only affects the curves highlighted in the Curves list (e.g. mirroring only the arm curves while leaving the legs untouched).

How it Works

• Humanoid Characters: The editor uses Unity's humanoid joint mapping to swap muscle values (e.g., Left Shoulder Twist to Right Shoulder Twist) and automatically inverts values to maintain visual symmetry.
• Generic Characters: The editor uses naming rules to swap curve paths (e.g., swapping paths containing Left, L , or _L_ with Right, R , or _R_). Numeric translation and rotation coordinates are inverted on the appropriate axes.

2. Tween Machine

The Tween Machine allows you to interactively blend the pose at the current frame using the preceding and succeeding keyframes as anchors.

How to Use

1. Select one or more property curves in the Curves list.
2. Move the playhead to a frame between two keyframes.
3. Drag the Blend slider left or right:
   • Dragging Left (0.0) blends the pose toward the previous keyframe's value.
   • Dragging Right (1.0) blends the pose toward the next keyframe's value.
   • Leaving it in the Center (0.5) creates an equal blend.
4. Release the slider to bake the interpolated value as a keyframe at the playhead time.

3. Keyframe Optimizer

Raw animations (especially motion capture or baked animations) often contain keys on every single frame, resulting in large asset file sizes. The Keyframe Optimizer removes redundant keys without changing the overall shape of the motion.

Settings

• Position Tol.: The threshold (in units) for discarding translation keyframes.
• Rotation Tol.: The threshold (in degrees) for discarding rotation keyframes.
• Algorithm: The editor analyzes each curve. If a keyframe's value deviates less than the tolerance from a straight line drawn between the preceding and succeeding keys, it is deleted.

4. Keyframe Smoothing

The Keyframe Smoothing tool filters jitter, noise, and abrupt spikes from animation curves.

Settings

• Target Bone: Choose a specific bone curve path to smooth, or select All Bones to filter the entire clip.
• Filter Type:
  • Median: Removes isolated spikes and sudden noise pops while preserving sharp motion transitions.
  • Average: Smooths general noise by calculating a flat average of neighboring frames.
  • Gaussian: Applies a weighted average to create smooth, organic motion profiles.
• Window Size: The frame range (3 to 51 frames) used for the smoothing calculations. Larger windows create smoother, slower motion.
• Iterations: The number of filtering passes (1 to 5) to run.
• Auto Tangents: Automatically adjusts tangent slopes for the modified keyframes to maintain smooth curves.
• Limit Range: Confines the smoothing filter to the time window specified in the Range (s) fields.

5. Extract Root Motion

Root motion moves the character's physical coordinate origin in the game world based on the animations. The Extract Root Motion tool isolates movement from a character bone and transfers it to the animation's Root Node.

Typical Workflow

1. Select the bone that contains the forward motion (typically the Hips, Pelvis, or the root-most moving bone).
2. Configure extraction settings:
   • Target is Humanoid: Enable this if working on a humanoid character.
   • Pos (X/Y/Z) / Rot (X/Y/Z): Choose which motion axes to extract. For standard locomotion, position X and Z (horizontal movement) and rotation Y (turning direction) are typically extracted, leaving position Y (jumping height) on the hips.
3. Click Extract Root Motion. The editor strips translation and rotation from the hips bone and writes it directly onto the clip's root transform curves.

6. Remove Root Motion

The Remove Root Motion tool deletes existing root transform animations from a clip, converting animations from root-motion to in-place locomotion.

Settings

• Remove Position: Strips translation data from the root node.
• Remove Rotation: Strips rotation data from the root node.
• Flatten to First Frame: Keeps a single keyframe at time 0.0 locked to the original starting pose instead of deleting the curves entirely. This prevents the character from snapping back to (0,0,0) if the animation was authored with an offset.

7. Time Warper

The Time Warper is an advanced retiming system that allows you to non-linearly speed up, slow down, or hold specific parts of an animation without shifting hundreds of keyframes manually.

How it Works

The Time Warper remaps the animation's timing using a Warp Curve (Input Time vs. Output Time). A straight diagonal line maintains normal speed, a steep slope speeds the motion up, and a flat slope slows it down.

• Global Warp Curve: Defines baseline timing changes for the clip. Includes built-in presets: Linear, Ease In, Ease Out, Snappy (fast impact), and Anticipate.
• Per-Bone Overrides: By clicking + Add Bone Override, individual bones receive custom timing curves. For Humanoid rigs, the Time Warper automatically consolidates hundreds of directional muscle curves into logical bone names (e.g. Left Arm, Spine).
• Push to All Overrides: Instantly copies the Global Warp Curve to every bone with an active override as a starting baseline.
• Bake FPS: Configurable target frame rate used when re-baking dense warped keyframe curves.
• Destructive vs. Export: Apply the warp directly to the active clip (with full Undo support) or click Export Warped Copy to save a new .anim asset file.

Clip & Asset Management

The Animation Editor operates directly on animation assets. This guide explains how to manage animation clips, convert read-only animations, and utilize the clip clipboard.

Loading Animations

You can load animations into the editor using three methods:

1. Drag and Drop: Drag any Animation Clip asset from your Project window and drop it anywhere inside the Animation Editor window.
2. Object Picker: Click the small circle icon next to the Animation Clip field in the sidebar and choose a clip from the list.
3. Load Selection: Highlight a character in the scene hierarchy or click an Animation Clip asset in the Project view, then click the Load Selection button in the sidebar. The editor will automatically hook up the character and the clip.

Understanding Editable vs. Read-Only Clips

Unity separates animations into two categories, and the editor displays safety warnings based on the loaded asset type:

Extracting Read-Only Animations

To edit an imported model animation, you must create a writeable copy. The editor provides an Extract Editable Copy button in the sidebar's Clip panel to automate this:

• Standalone Mode: If you are editing a clip outside a layout composition, clicking Extract Editable Copy opens a standard Unity save file dialog. Choose a folder in your project to save the writeable .anim file.
• Composition Mode: If the clip is loaded inside a Layout Composition, clicking Extract Editable Copy automatically extracts the clip and embeds it directly inside the composition asset as a sub-asset, avoiding folder clutter.

Asset Panel Controls

The Clip panel in the sidebar contains actions to manage files and copy data:

File Commands

• Duplicate: Creates a direct clone of the currently loaded Animation Clip asset. It prompts for a new filename and loads the clone.
• Save: Forces Unity to write all cached in-memory keyframe changes back to the physical .anim file on your disk.

Clipboard Commands

The editor features a dedicated animation clipboard separate from the operating system clipboard. This allows you to transfer animations between clips:

• Copy Clip: Copies the entire loaded animation (all curves, keys, and events) into the clipboard buffer.
• Replace: Replaces the loaded animation's contents with the animation currently held in the clipboard. This is a destructive operation and supports Undo.
• Paste New: Extracts the animation from the clipboard buffer and saves it as a brand-new standalone .anim asset.
• Cut Asset: Copies the loaded animation to the clipboard, then prompts you to delete the source asset from the project files entirely.

Safety Safeguards

To prevent accidental data loss, the editor includes several built-in safety features:

• Status Readout Warning: A status label at the bottom of the Clip panel turns red and displays a detailed description whenever you attempt to write keyframes to a read-only FBX file.
• Destructive Confirmations: Prompts are shown before deleting assets or overwriting files (e.g., when clicking Cut Asset or Replace).
• Empty Selections: Operations that require selections (like copying keyframes) display status prompts if nothing is highlighted, preventing silent failures.

Editor Settings

The MSMotion Settings window acts as a central hub for configuring your workspace preferences, timeline rendering options, snapping mechanics, viewport overlays, and undo buffers.

To open the Settings window, click the Settings (Gear Icon) on the composition top toolbar or choose Tools > Maharaja Studio > MsMotion > Setting from the Unity menu bar.

Figure 8: MSMotion Settings Panel

1. General Category

• Default Frame Rate: The frame rate applied to newly created compositions (presets: 24, 30, 60, 120 FPS).
• Default Layer Blend Mode: The default mixing mode assigned when adding a new layer (Override or Additive).
• Ripple Delete: When enabled, deleting a timeline block automatically shifts all subsequent blocks on that same layer to the left, closing the gap.

2. Timeline & Playback Category

• Default Zoom (px/s): Pixels-per-second zoom scale applied when opening a composition (range: 20 to 800 px/s).
• Default Waveform Display: The visual waveform drawn on clip nodes (First Curve or Energy Bars).
• Time Display Format: The format of the timeline ruler and time fields (Seconds, Frames, or SMPTE).
• Enable Loop Region by Default: Automatically activates a loop region across the entire duration when a composition is first opened.
• Default Preview Time Scale: The starting playback speed (range: 0.1× to 4.0×). Only affects editor previews.
• Horizontal Scroll Sensitivity: Mouse wheel multiplier when scrolling horizontally through tracks.
• Playhead Auto-Scroll Margin (px): How close the playhead can get to the track boundary before the view automatically pans.

3. Interaction & Workflow Category

• Slot Snap Mode: Snapping behavior when dragging clips (None, Frame, SlotBoundaries, Markers, or All).
• Snap Tolerance (px): Distance threshold in pixels where snapping occurs (range: 1 to 50 px).
• Trim Handle Width (px): Size of the interactive edge drag handles on timeline blocks (range: 4 to 20 px).
• Auto-Select New Slots: Automatically selects a timeline node in the inspector as soon as it is created.
• Default New Slot Duration (s): Duration in seconds for newly created blank or override slots (range: 0.1s to 10.0s).

4. Undo / Redo Category

• Max History Count: The maximum number of undo steps stored in memory per composition.
• Grouping Window (s): Microsecond threshold where continuous adjustments are merged into a single undo command instead of creating individual entries.
• Clear All Undo History: Erases the active session undo/redo stack for all open compositions.

5. Visuals & Viewport Category

• Show Bone Overlay by Default: Automatically activates skeleton drawing when opening a composition.
• Animated Bones Only: Restricts skeletal outlines to bones that contain active animation curves.
• X-Ray (Draw Over Mesh): Renders the skeletal bone overlays on top of the character's geometry.
• Show Local Axes: Renders three-axis coordinate gizmos on each bone.
• Show Bone Names: Draws text label tags next to each joint.
• Joint Size / Bone Shape / Bone Width: Configures bone geometry representation.
• Onion Skinning: Renders semi-transparent ghost poses of past and future frames to help visualize the motion curve.

6. Export Workflow Category

Configures default paths, one-click bypass behaviors, companion asset packaging, and global multi-actor export rules:

• Default Export Directory: The default folder where baked Animation Clips, FBX files, and companion assets are created.
• Bypass Save Prompt: When enabled, clicking one-click export immediately writes to the Default Export Directory without displaying an OS file save dialog.
• Companion Assets (Config, Manifest & Interaction): Controls where auto-generated companion assets are saved relative to the exported animation clip (NextToClip, Subfolder, or CustomDirectory) for:
  • MSMotionAnimationConfig (_config.asset)
  • MSMotionFXManifest (_fx.asset)
  • MSMotionInteractionConfig (_interaction.asset)
• Multi-Actor Export Defaults Panel:
  • Default Export Scope: AllActorsSeparateClips, ActiveActorOnly, or CustomSelection.
  • Filename Suffix Style: ActorDisplayName (e.g. Walk_Hero.anim) or ActorId (e.g. Walk_actor_0.anim).
  • Auto-Generate Interaction Config: Automatically generates and links an MSMotionInteractionConfig asset binding all participant tracks, relative offsets, and alignment data.
  • Isolate FX Manifest Per Actor: Filters companion FX manifest events so each participant actor's manifest only contains FX nodes assigned to that character.
  • Reset Actors To Origin On Export: Restores participant preview actors to canonical origins before and after each bake pass to prevent coordinate drift.
• Humanoid Root Motion Defaults Panel: Sets default bake flags for humanoid clips (Loop Time, Loop Pose, Cycle Offset, Root Transform Rotation, Root Transform Position Y, Root Transform Position XZ, and Mirror).

Animation Clip Node

An Animation Clip Node is the fundamental building block of a composition layer. It represents a specific segment of time on the timeline during which a native Unity Animation Clip (.anim) plays back on the preview character.

Visual Timeline Blocks

Animation Clip Nodes are shown as colored horizontal blocks on the timeline tracks. You can customize the **Waveform Mode** to display curves:

• First Curve: Draws the first animated float curve of the clip.
• Energy Bars: Computes the root-mean-square (RMS) velocity energy of the curves.

Positioning and Resizing

• Move: Click and drag the middle of a block to shift its start time.
• Resize: Click and drag the left or right edges of the block to change its duration.
• Resize Modes:
  • Trim: Playback speed remains constant. Stretching the block reveals more of the source clip; shrinking it cuts the end.
  • Scale: The entire source animation is stretched or compressed to fit the visual block bounds.

Inspector Parameters

• Clip: The Unity Animation Clip asset.
• Is Embedded: Physically saved inside this Composition asset (embedded PSD style) or referenced externally.
  Tip: Embedded clips are fully portable—copying the composition asset copies the clips inside it. You can extract them at any time.
• Clip Offset: The start offset (in seconds) from the beginning of the source clip.
• Playback Speed / Speed Curve: Static or curve-driven speed multipliers. Negative values play the animation backward.
• Extrapolation Mode: Controls behavior when node duration exceeds the clip length (Hold, Loop, PingPong, or None).

Advanced Event Rules

Allows fine-grained control over Unity Animation Events in looped or stretched clips:

• Mute Events: Completely silences all events inside this specific block.
• Event Max Loop Count: Restricts event triggers to a specific number of loop iterations.
• Event Start Loop Index: Delays event triggers until the clip has looped a certain number of times.
• Event Time Offset: Shifts the execution of all events by a constant offset.
• Event Loop Interval Delay: Inserts a custom pause delay between loops before events repeat.

Pose Node

A Pose Node is a specialized timeline block that grabs a single, frozen frame from a source Animation Clip and holds that static pose across the node's entire duration. Unlike standard animation clips, it acts as a pose hold.

Workflows and Common Uses

• Hit-Stop / Impact Freezes: Temporarily pausing a character in an impact pose when a weapon strikes an enemy.
• Idle Stance Adjustments: Freezing a frame from a dynamic movement to serve as a custom, static standing stance.
• Transition Bridging: Smoothly blending a moving character into a static frozen pose to bridge two incompatible animations.

Inspector Parameter Reference

• Clip: The source Animation Clip asset from which the pose is extracted.
• Is Embedded: Toggles whether the clip asset is physically saved inside this Composition asset.
• Pose Time: The exact timestamp (in seconds) of the frame you want to extract from the source clip. Use the slider to scrub through the clip length.
• Transition In / Out Duration: Eases the transition into and out of the frozen pose.
• Transition Curve: Selects the mathematical interpolation shape (Linear, EaseIn, EaseOut, EaseInOut, or Smooth) used to blend the pose in and out.

Foot IK Node

The Foot IK Node is a procedural constraint that aligns a character's feet to the terrain slope and height in real time, preventing hovering, clipping, and foot sliding. By analyzing the character's movement phase, the system automatically transitions limbs between free swing animation and locked ground contact.

Capabilities and Real-Time Calibration

• Terrain Alignment: Casts rays downward from the ankles and toes to detect slope normal orientations.
• Auto-Calibration: Automatically measures bone distances in the character's rest pose to prevent floating feet.
• Pelvis Drop: Automatically pulls the hips down if the ground is too low, keeping the character grounded without popping joints.

Inspector Parameter Reference

Leg Configuration & Bones

• Use Humanoid Bones: Automatically identifies thigh, calf, ankle, and toe bones from the Animator.
• Left/Right Leg Config: If humanoid bones are disabled, manually specify the bone paths for Hip, Knee, Foot, Toe, and Knee Hint.

Raycasting & Step Limits

• Raycast Mask: Selects which Physics layers represent the walkable ground.
• Max Step Up / Max Step Down: Height boundaries (in meters) representing the maximum terrain steps or drops the legs can resolve.
• Foot Height Offset: Fine-tune offset added to the ankle height.

Pelvis Drop

• Enable Pelvis Drop / Pelvis Drop Weight: Configures hip pull-down behavior.

Settings & Limits

• Foot Rotation Weight: Controls how strongly the ankle rotates to match the terrain normal.
• Smooth Speed: Controls the transition speed of height changes.
• Soft IK Ratio: Sets the ratio (0.80 to 1.00) at which the solver softens leg stretching to prevent knee popping. Recommended: 0.98.

Gait Phase & Foot Locking

Gait Phase (Swing Control)

To prevent the solver from fighting walking or running animations while a leg is off the ground:

• Enable Gait Phase: Automatically dampens the IK weight while a foot is swinging forward.
• Swing Velocity Threshold: The vertical speed (m/s) at which the system considers the foot to be airborne.
• Gait Phase Blend Speed: Speed at which swing damping engages and disengages.

Foot Locking (Anti-Slide)

To eliminate foot sliding when a foot makes contact with the ground:

• Enable Foot Locking: Captures the foot's world coordinates at the moment of landing and freezes the ankle position in place.
• Lock IK Threshold: The minimum weight required before the foot lock can engage.
• Unlock Velocity Threshold: The upward velocity at which a locked foot is released to swing.
• Lock Blend Speed: Easing speed for engaging/disengaging the world coordinates lock.

IK Override Node

An IK Override Node is a timeline block that modulates limb positioning using Inverse Kinematics (IK) over a set time range. It allows you to overlay custom hand/foot placements, joint targets, and posture adjustments on top of base animation clips.

Capabilities and Visual Handles

• Scene View Handles: Visual manipulators appear in the Scene view at the positions of the configured IK targets. You can drag these handles directly to pose the character.
• Transition Blending: Timing sliders allow you to fade the IK solver influence in and out, smoothly capturing the limbs.

Inspector Parameter Reference

Timing & Transitions

• Start Time / Duration: The timeline bounds of the block.
• Transition In / Out Duration: Easing times (in seconds) over which the limbs transition.
• Transition Curve: Easing curve driving the fade.

Weights & Automations

• Use Weight Curve / Weight Curve: Drives the IK solver's global influence dynamically over the node's duration.

Masking & Blending Options

• Apply Root Motion: Projects the solver's root modifications back onto the character's root trajectory.
• Preserve Transform: Locks the limb's world-space position relative to the moving root.
• Slot Mask: A specific AvatarMask that restricts which parts of the skeleton are affected.

Timeline Keyframe Authoring & Path Tools

You can author multi-point trajectories for effectors directly in the Scene View using the floating MSMotion IK Tools HUD overlay. The HUD panel displays the following controls:

• Local Time / Global Time: Keyframe timings.
• Add / Remove Node: Manages path nodes.
• Align Rotation to Normal: Aligns the effector orientation to match the slope angles of terrain/meshes.
• Effector to Ground: Raycasts downwards and snaps the target position directly to the ground surface.
• Pole to Ground: Snaps the knee/elbow pole-vector target directly to the ground.
• Effector to Cursor (Mesh): Performs a viewport raycast and places the selected effector at the exact mesh surface point directly under your mouse pointer.
• Snap to Transform: Shifts the keyframe node coordinates to that object's bounding center.
• Reset Nodes to FK Pose: Rebinds all keyframe coordinates to match the underlying base Forward Kinematics (FK) values.
• Mirror X (World / Root): Flips the coordinates of the selected nodes along the world or root X-axis.
• Reverse Path Time: Flips the normalized timeline coordinates of the path nodes, reversing the execution order.
• Bake FK to IK Path: Samples the base animation over the node's duration and records the joint paths into keyframe nodes.

Advanced IK Locks

IK Locks allow you to pin multiple joints (e.g., both hands or feet) to specific world-space coordinates while the rest of the body continues to animate dynamically. Under the IK Locks tab in the IK Override Node:

• Click + Add IK Lock to attach a new lock modifier.
• Target Bone: Choose the bone to freeze in place.
• Lock Position/Rotation: Check to freeze translation, rotation, or both.
• World Space Constraints: You can provide a specific transform target to stick the limb to an object during the override duration.

Squash & Stretch and Joint Scale Overrides

For advanced stylized animations, character rigs can utilize squash and stretch behaviors dynamically:

• Interactive Scale Handles: Selecting a single keyframe node in the Scene View displays a **light-blue cone scale handle** at the effector position. Drag this handle to scale the **Stretch Scale** multiplier.
• Squash & Stretch Overrides: Under the **Override Structural Settings** checkbox in the Scene View HUD, override the global rig defaults (Allow Stretch, Stretch Limit, Stretch Axis, Preserve Volume, Compensate Parent Scale).
• Joint Scale Overrides: Under the **Override Joint Scales** checkbox in the HUD, configure manual scaling factors (Vector3 Fields) for each individual joint in the IK chain (e.g., shoulder, elbow, wrist).

IK Rig Configuration

The Rig Config window allows you to define and adjust Inverse Kinematics (IK) Chains and constraints for your preview character. The editor uses these rig definitions to solve limb targets, handle ground grounding, and calculate physical modifications in real time.

Figure 3: Rig Config Editor Window

To open the Rig Config window, click the Rig Config (🦴 Icon) on the composition top toolbar.

1. Rig Global Settings

When no specific chain is selected in the left list, the right pane displays global settings:

• Enable Full-Body IK (Root Pull): Toggles full-body IK solver reactions. When enabled, pulling hand or foot targets beyond the character's natural limb length will drag the hips and body towards the target instead of letting the limb hyper-extend.
• Base FBIK Settings: Configure the FBIK Weight and FBIK Root Bone (usually the hips or pelvis).

2. Left Pane: Chains & Presets

Manage joint chains in the list using the toolbar buttons:

• + Custom / + Preset: Adds a blank chain or instantiates templates (Left/Right Arm, Left/Right Leg, Spine, Tail).
• Auto-Detect: Scans the preview character to construct chains automatically using humanoid bones or generic heuristics.

3. Right Pane: Chain Configuration

Selecting a chain in the left list displays its properties in the details pane:

• Solver Type:
  • Two Bone Analytic: Highly optimized solver restricted to exactly three joints (Root, Mid, Tip) like shoulder-elbow-wrist.
  • FABRIK: A heuristic solver that supports chains of any bone count (such as tails or tentacles).
• Soft IK Ratio: A slider (0.0 to 0.5) that prevents limbs from aggressively popping when extending straight.
• Use Pole Vector: Toggles custom pole target alignment to direct joint hinge bends.
• Squash & Stretch: Toggles bone lengthening when targets are pulled beyond the natural limb span (Allow Stretch, Max Stretch Multiplier, Stretch Axis, Preserve Volume, Compensate Parent Scale).
• Twist Distribution (Roll Solvers): Prevents "candy wrapper" twisting artifacts on character limbs (such as forearms and upper arms) by distributing the source bone's twist rotation across multiple twist target bones (Enable Twist Distribution, Twist Source Bone, Twist Axis, Twist Target Bones list).
• Bone Paths: Defines the joints included in the solver.
• Per-Joint Scale Overrides: Manually compress or extend specific bones inside the chain.

4. FABRIK Joint Limits

When using the **FABRIK** solver type, you can assign physical limits to individual joints:

• Stiffness (FK Bias): A slider (0.0 to 1.0) defining joint resistance.
• Constraint Type:
  • None: Free rotation.
  • Hinge: Restricts rotation to a single local axis (Hinge Axis, Min/Max Angle).
  • Cone: Restricts rotation to a conical range (Cone Center, Cone Angle Limit).
• Scene View Visualization: Active constraints display interactive overlays in the Scene View. You can adjust limit angles and axis directions directly using handles.

Look-At Constraint Node

The Look-At Constraint Node forces a character's spine, head, and eyes to track and look at one or more targets in 3D space. This is essential for character focus, conversation behaviors, and combat aiming.

Visual Scene View Handles

When you select a Look-At node, a visual crosshair handle representing the look-at target appears in the Scene View. Dragging this handle moves the target position dynamically, causing the character to twist their spine and head to follow in real time.

Inspector Parameter Reference

Target Selection

Configure targets in the **Targets** list. If multiple targets are active, the look-at direction is computed as a weighted average.

• Target Mode:
  • Transform: Follows a specific Unity Transform GameObject.
  • FX Event: Dynamic tracking that locks onto a temporary object spawned by an FX node.
  • Local Offset: Follows a coordinate offset relative to the character.
• Weight / Local Offset: Mixes target influences and offsets.

Bones & Weights

• Use Humanoid Bones: Automatically detects head, spine, and eye bones.
• Head Bone Path / Spine Base Bone Path: Fields to manually assign bone paths.
• Head Weight / Spine Weight: Sets how much of the rotation is applied to the neck/head and absorbed by the spine.

Eye Tracking & Biological Jitter

• Left / Right Eye Bone Path: Fields to assign eye bones.
• Eyes Weight: Controls the focus strength of the eye bones.
• Saccade Jitter: Simulates biological eye movement by injecting minor, high-frequency micro-jitter into the eyes' tracking vector (0.0 = static gaze, 1.0 = high activity).

Limits & Easing Speed

• Max Angle: The absolute rotation boundary (0 to 180 degrees) the character is allowed to twist.
• Soft Limit Angle: Eases and slows down head turning as the target approaches the Max Angle, preventing visual popping.
• Smooth Speed: The tracking acceleration.
• Forward Axis / Up Axis: Coordinate mapping dropdowns to match the head bone's local forward alignment.

Jiggle Physics Node

The Jiggle Physics Node applies secondary spring-mass physics to chains of bones (such as hair, capes, tails, ears, or loose accessories). The physics simulation reacts dynamically to the character's primary animations and movement.

Spring-Mass Core Mechanics

The physics simulation is driven by a spring-mass solver configured in the Inspector:

• Stiffness: How strongly the bones try to return to their original animated poses (0.01 to 1.00).
• Damping: How much energy is lost per frame (0.00 to 1.00). Prevents endless oscillations.
• Mass: The resistance of the bones to motion (0.1 to 5.0). Higher mass creates more inertia and overshoot.
• Simulate in Local Space: When enabled, the simulation is computed within the character's local coordinates rather than world space.
  Workflow Tip: Enable local space simulation for extremely fast-moving characters (such as characters teleporting or riding mounts) to prevent the physics from stretching or breaking during sudden displacements.
• Falloff Curves (Root-to-Tip Modulation):
  • Stiffness / Damping Falloff: Standard curves where the X-axis is the index along the bone chain (0.0 = root, 1.0 = tip) and the Y-axis is the property multiplier.
  • Stiffness/Damping Time Curves: Modulates properties over the absolute duration of the timeline slot.

Environment & External Forces

• Gravity / Gravity Multiplier: Direction vector and scale multiplier for gravity.
• Use Local Gravity: When active, gravity is calculated relative to the character's rotation.
• Centrifugal Multiplier: Multiplies the outward centrifugal force applied during sharp rotations.
• Wind Strength / Wind Direction: Constant wind pressure and direction vector.
• Turbulence Speed / Frequency: Generates noise in the wind force to create organic, fluttering motions.

Volume Preservation (Squash & Stretch)

To prevent jiggling chains from looking like rigid rods when stretched, you can enable volume preservation:

• Enable Squash & Stretch: Toggles procedural scale deformation.
• Max Stretch: The maximum elongation factor allowed.
• Squash Multiplier: Determines how much the bones shrink along their perpendicular axes when stretched, maintaining visual volume.

Colliders & Collision Shapes

To prevent jiggle bones from clipping through the character's body or the environment, define custom collider shapes inside the **Colliders** panel:

Figure 4: Configuring Jiggle Physics colliders in the Inspector and Scene View

Collision Properties

• Enable Colliders: Globally enables or disables collider interactions.
• Enable Self Collision / Self Collision Radius: Prevents bones in the jiggle chain from passing through each other.

Custom Collider Shapes

Each custom collider is attached to a Parent Bone Path and positioned using a Local Offset matrix.

Trajectory Override Node

The Trajectory Override Node replaces a character's root motion animation curves with a custom Bezier spline trajectory. This is ideal for steering characters along exact paths (such as combat rolls, leaps, wall runs, or scripted cinematics).

Figure 5: Bezier spline path and tangents in the Scene View

Spline Editing in the Scene View

When you select a Trajectory Override Node, visual spline controls appear in the Scene View:

• Bezier Nodes: White boxes indicating spline points. Click and drag nodes to shift the pathway.
• Tangents: Pink handles protruding from each node. Drag these to define the curve's exit and entry angles.
• Adding/Deleting Nodes: Right-click on the spline to add a new Bezier node, or select a node and press **Delete** to remove it.
• Tangent Modes: Right-click a node to set its tangent calculations:
  • Auto: Calculates smooth curves automatically based on neighboring nodes.
  • Split: Allows left and right tangent handles to be rotated independently to create sharp corners.

Inspector Parameter Reference

Space Configurations

• Space:
  • Relative: Spline coordinates are relative to the character's starting position at the node's start time.
  • Absolute: The spline is locked to absolute world-space coordinates. The character will snap to the exact world coordinates regardless of their previous location.

Speed & Easing

• Easing Curve: Drives timing along the spline. The X-axis represents normalized timeline time; the Y-axis represents progress along the spline length (0.0 = start, 1.0 = end).

Rotation & Banking

• Rotation Blend Weight: Blends the character's orientation between the animation clip's original rotation (0.0) and the spline's direction vector (1.0).
• Use Banking / Bank Multiplier: When enabled, the character procedurally leans/banks left or right into curves.

Ground Snapping (Terrain Conformance)

• Ground Layer Mask / Ground Snap Offset: Physics layers representing walkable terrain and vertical offset.
• Align to Ground Normal: Automatically rotates the character to match the slope inclination of the ground beneath the spline nodes.

Loop Options

• Is Closed Loop: Connects the final node back to the initial node, transforming the trajectory into a continuous loop track.

Visual HUD & Debug Settings

Turn these options on in the Inspector to show overlays in the Scene View:

• Show Speed Heatmap: Colors the spline path (gradient from green to red) to visually display where the character will accelerate or decelerate based on the easing curve.
• Show Path Length HUD: Displays a text box indicating the total length of the spline in meters.
• Show Per-Node Time: Prints the execution time (in seconds) next to each Bezier node.
• Show Preview Playhead: Renders a silhouette of the character at the current scrubber time along the spline path.

Workflow: Spline Sub-Path Extraction

If you need to crop the duration of a trajectory node without destroying the shape of the spline curve, click the Extract Sub-Path button in the details panel. This uses a de Casteljau subdivision algorithm to mathematically calculate new control points and tangents so the cropped segment preserves the exact visual shape of the original path.

Bone Subdivision Node (Exp)

The Bone Subdivision node allows you to dynamically divide existing bones into multiple virtual segments. This is useful for creating flexible, bendy, or elongated motions (like a stretchy neck, tail, or tentacle) without requiring the original rig to be authored with extra bones.

At export time, mesh weights are automatically redistributed, and the virtual bones are baked into the resulting animation clip.

Adding the Node

1. Open the Composition Editor.
2. Right-click on any layer track in the timeline.
3. Select Constraints > Bone Subdivision (Exp).

Once added, select the node in the timeline to view and configure its settings in the Details panel.

Node Settings

The Bone Subdivision node can be authored entirely inline (within the composition timeline) or via a reusable Descriptor Asset to share configurations across multiple animations.

General Configuration

• Descriptor Asset: (Optional) Drag a MSMotionBoneSubdivisionDescriptor ScriptableObject here. When assigned, the node uses the asset's settings and ignores inline fields.
• Config Label: A custom name for this node configuration (e.g., "Bendy Neck Setup").

Chain Topology

• Subdivision Mode:
  • Fixed Count: Creates an exact, fixed number of virtual bones per source bone.
  • Density: Creates virtual bones dynamically based on the physical length of the source bone, ensuring spatial resolution regardless of stretch.
• Subdivisions Per Bone: (Fixed Count mode) The exact number of virtual bones injected into each source bone.
• Bone Spacing (cm): (Density mode) Physical distance between each virtual bone in centimeters.

Deformation & Weighting

• Weight Falloff Curve: Defines how original bone skin weights distribute across virtual bones (X-axis: 0 = root, 1 = tip; Y-axis: relative influence). A linear curve (0,1 to 1,1) provides even distribution.
• Preserve Volume: Applies perpendicular scale compensation when the chain stretches, maintaining character volume without thinning artifacts.

Source Bones

• Source Bone Chain: A list of bones to subdivide, ordered from Root to Tip (e.g., Spine → Chest → Neck).
  • Humanoid Rigs: Select HumanBodyBones enum mapping (e.g., Neck).
  • Generic Rigs: Set dropdown to LastBone and enter the transform hierarchy path manually.

Advanced / Solver Settings

• Propagated Tip Children: Explicitly forces child bones to detach from source bones and re-attach to the tip of the subdivided chain. (Smart Auto-Propagation automatically measures distance to re-parent tip and base children).
• FABRIK Iterations: Maximum solver iterations allowed per frame.
• FABRIK Tolerance: Distance threshold (in meters) for solver convergence.

FX Nodes Overview

FX Nodes are timeline blocks dedicated to triggering runtime events (such as playing sound effects, spawning particles, projecting surface decals, instantiating prefabs, animating attachments, or firing custom scripts) rather than animating skeletal bones.

Unlike motion nodes, FX nodes do not bake curve data into the exported Animation Clip. Instead, they are compiled into a companion FX Manifest asset which is read by runtime playback components.

The 8 FX Node Types

Shared Parameter Reference

Every FX Node type inherits a common set of properties for timing, positioning, and socket attachment:

Timing & Loop Settings

• Event Name: A user-friendly label to organize this event.
• Loop / Blend In / Blend Out: Configures looping and fade-in/fade-out times (in seconds).

Socket Target & Attachment

• Target Human Bone: A dropdown list of standard Humanoid bones.
• Target Bone: A text field to enter a manual bone name if the character is generic.
• Transform Space: Controls how the spawned FX tracks character movement:
  • Follow Target: The FX attaches as a child of the bone, translating and rotating with it.
  • Spawn and Stand: Spawns at the bone's coordinates at the trigger time, but remains stationary.
  • World Space: Spawns at absolute world coordinates.

Transform Overrides

• Override Position / Rotation / Scale: Custom offsets relative to the socket bone coordinate system.

Workflow: Property Overrides

The Property Overrides workflow allows you to dynamically customize public variables, fields, or component properties of the spawned effect prefab or the character's bone hierarchy directly from the composition timeline. This is ideal for altering effects per event without duplicating prefabs.

Figure 6: Dynamic Property Overrides and Method Invocation

To manage overrides, open the fourth tab in the FX node editor details panel.

• Target Selection: Select where the property modification should be applied (Root, SpawnedObject, CustomTargetBone).
• Trigger Time Configuration: Define the exact timestamp (normalized or composition time) at which the override is executed.
• Action Types & Method Invocation: Choose between **Set Property** (directly modifies a variable) or **Invoke Method** (executes a C# function).
• Target Component & Member Mappings: Map the override to a specific component (e.g. Light, ParticleSystem) and enter the exact field/method name. Use the **Auto-Picker (▼)** to scan the target GameObject for quick assignment.
• Dynamic Value & Argument Editors: The input field automatically adapts to the data type (string, int, float, bool, Vector3, Color, Enum, or Object asset).

Editor Preview Safety

By default, some dynamic effects (like custom scripts or scene property overrides) are blocked in edit mode:

To test preview-safe actions, ensure the top toolbar's **Safety Toggle (FX Indicator)** is enabled.

Cross-Actor Handover & Socket Retargeting

In multi-actor compositions (such as partner dancing, acrobatic duets, martial arts disarms, or weapon exchanges), physical props or visual effects often need to transfer from one participant character to another during the animation. MSMotion provides Cross-Actor Handover capabilities across all visual and object-spawning FX nodes (Spawn FX, Particle FX, VFX Graph, and Decal FX).

Parameter Reference

Enable the Handover section in the FX details panel:

• Handover Enabled: Activates cross-actor tracking and retargeting for this event slot.
• Receiver Actor ID: The target participant character who receives the object (e.g. partner, victim, actor_1).
• Receiver Human Bone: Standard Humanoid bone on the receiving character to attach to (e.g. RightHand, LeftHand, Spine).
• Receiver Bone Path: Hierarchy path if the receiving character is a Generic rig.
• Receiver Local Offset / Euler: Spatial position and rotation offsets relative to the receiver's socket bone.
• Handover Time: The normalized timestamp (0.0 to 1.0) along the slot duration at which the handover initiates.
• Transition Duration: Normalized duration over which the object travels from the source socket to the receiver socket.
• Transition Mode:
  • Smooth Interpolation: Glides smoothly from source bone to receiver bone using Hermite interpolation.
  • Instant: Snaps immediately to the receiver socket at the handover timestamp.
  • Follow Trajectory: Follows an authored Bezier spline trajectory curve from source to receiver before parenting.
• Retain on End: Keeps the object parented to the receiving character after the composition completes (ideal for weapon disarms or persistent item exchanges).

Visual Scene View Gizmos & Catch Alignment

To ensure physical props, weapons, and spell effects align naturally in the receiving character's hand or socket, MSMotion provides a dedicated Phase-Aware Scene View Gizmo and Auto-Keying workflow:

[Source Actor Bone] (Cyan 🔘) --------(Transit Arc)--------> [Receiver Catch Bone] (Amber 🎯)

• 1. Phase-Aware Target Switching: The Scene View gizmo automatically tracks the state of the handover based on your timeline playhead:
  • Source Socket Phase (t < HandoverTime): Gizmo anchors to the source actor's bone socket in Cyan. Manipulating handles adjusts Local Position and Local Rotation.
  • Receiver Catch Phase (t >= HandoverTime): Gizmo transitions to the receiving actor's bone socket in Warm Amber/Gold. Manipulating handles interactively adjusts Receiver Local Offset and Receiver Local Rotation Euler.
  • In-Flight Visualizer: An amber dotted line connects source origin to receiver destination socket in the Scene View.
• 2. Floating Scene View HUD Bar: When an FX slot with Handover enabled is selected, a pill toolbar floats at the top-center of the Scene View with controls: 🔘 Source Socket, 🎯 Receiver Catch, Auto, Src, Rec, and ⏱️ Catch Frame (jumps timeline to exact catch frame).
• 3. Real-Time Auto-Keying (🔑): With Auto-Key enabled, moving the spawned prop in the Scene View automatically detects source vs receiver phase and records offsets into the corresponding properties with full Undo/Redo.
• 4. Catch Alignment Inspector Utilities: Includes [⏱️ Scrub to Catch Frame], [📋 Copy from Source], [🔄 Reset Offsets], and manual Vector3 offset fields with instant Scene View repainting.

FX Path Tools Scene Panel

When editing a spline trajectory on an FX node, a floating overlay panel titled FX Path Tools appears in the Scene View, providing three tabs:

• Node Tab: Context-sensitive properties based on viewport selection (adjust Local/Global Time, Tangent Mode, and manage path nodes).
• Presets Tab: Generate complex motion paths in one click (Parabolic Arc, Straight Line, Bounce, Zig-Zag, Ribbon, Lasso, Circle, Ellipse, Helix, Figure-8, Spirals, Sine Wave, Spring).
• Edit Tab: Utilities to reverse path direction, smooth tangents, normalize timing, subdivide segments, or mirror coordinates along local axes.

Audio FX Node

The Audio FX Node triggers audio playback at a specific timeline mark. It is commonly used for sound effects like footstep rustles, sword slashes, impact thuds, or character vocalizations.

Inspector Parameter Reference

Audio Asset & Playback Properties

• Clip: The Unity AudioClip asset played by this node.
• Volume / Pitch: Base parameters.
• Pitch Variance: Adds random pitch variance (0.0 to 1.0) to every trigger.
  Workflow Tip: Set Pitch Variance to a low value (e.g. 0.05 to 0.10) for repetitive sounds like footsteps. This minor variation prevents the sound from feeling mechanical.
• Stereo Pan: Constant panning between left and right speakers. Only active when Spatial Blend is set to 2D.

Spatialization (3D vs. 2D)

• Spatial Blend: Smoothly interpolates the sound source type (0.0 = 2D global, 1.0 = 3D world-space point source).
• Min Distance / Max Distance: The distance (in meters) governing volume roll-off.

Volume & Pitch Automation

You can fade audio parameters dynamically over the node's timeline duration:

• Use Volume/Pitch Transition In / Out: Enables fading or modulating the parameters using custom Animation Curves (Y-axis = value, X-axis = normalized time).

Camera Shake FX Node

The Camera Shake FX Node triggers procedural screen shake events (for dramatic actions like ground stomps, heavy landing impacts, spell explosions, or boss roar screens).

Cinemachine Integration

The Camera Shake node interfaces directly with Unity's Cinemachine package (using Cinemachine Impulse):

• Impulse Source Prefab: Assign a Cinemachine Impulse Source prefab. The system will instantiate this prefab at the target socket bone to fire camera shake signals directly into Cinemachine cameras.

Inspector Parameter Reference

Shake Core Properties

• Amplitude / Frequency: Scale multipliers governing shake intensity and speed of oscillations.
• Impulse Direction: A direction vector (default: 0, 1, 0) defining the primary axis of the shake impact.
• Use Character Forward: When checked, rotates the Impulse Direction vector to align with the character's forward direction at the trigger time. Useful for recoil slide shakes.
• Propagation Radius: The distance (in meters) within which cameras are affected by this shake.

Amplitude & Frequency Transitions

You can automate shake intensity decay dynamically over the timeline duration:

• Use Amplitude/Frequency Transition In / Out: Enables modulating the shake strength and speed over the node duration using curves.

Particle FX Node

The Particle FX Node spawns particle systems (like dust clouds, sparks, magical bursts, or fire trails) at specific socket targets.

Inspector Parameter Reference

Particle Spawn & Playback Settings

• Prefab: The particle system prefab asset.
• Play Mode:
  • OneShot: Spawns the prefab and fires a single burst of particles.
  • Continuous: Instantiates the particle system and keeps it emitting particles for the entire duration of the timeline slot.
• Emit Count: The number of particles emitted during a OneShot burst trigger.
• Scale Multiplier: A scale multiplier to adjust the particle size.
• Attach to Bone: Parents the instantiated particle GameObject directly to the socket bone.
• Wait for Completion: Delays the destruction of the spawned particle GameObject until all active particles have naturally decayed, preventing ugly popping.

Emission & Scale Transitions

You can automate particle intensity and dimensions dynamically over the timeline block using custom curves:

• Use Emission/Scale Transition In / Out: Automates emission rate and physical transform size over time.

Spline Trajectory Path

• Trajectory: Expand the Trajectory foldout to configure a local Bezier spline path. You can edit control points to make particles travel along exact paths away from the character. See the **FX Path Tools** section for details.

VFX Graph FX Node

The VFX Graph FX Node triggers visual effects authored with Unity's Visual Effect Graph (VFX Graph). It provides controls for parameter bindings and spawning offsets.

Inspector Parameter Reference

Asset & Attachment Settings

• VFX Asset: The Unity Visual Effect Graph asset to trigger.
• Attach to Bone: Parents the instantiated VFX GameObject directly under the target socket bone.
• Stop at Duration End: If checked, halts the VFX system or destroys its instance as soon as the timeline block ends.

Parameter Bindings & Overrides

• Parameter Overrides: A list of property bindings. You can target specific properties inside the visual effect asset (such as float parameters, integers, or color variables) and override their values directly.

Property and Scale Transitions

To fade or scale effects dynamically, you can automate values using curves:

Easing a VFX Property

• Transition Property Name: Enter the exact string name of the float parameter inside the VFX Graph (e.g. SpawnRate or Intensity).
• Use Property Transition In / Out / Curves: Drives the named property using custom Animation Curves.

Easing VFX Local Scale

• Use Scale Transition In / Out / Curves: Enables automating the visual effect's transform size.

Trajectory Spline Path

• Trajectory: Configure a Bezier spline path to make the VFX Graph system travel along a specified vector path relative to the character.

Decal FX Node

The Decal FX Node projects visual decals (such as blood splatters, footstep dirt, scorch marks, magic runes, skid marks, or bullet impacts) directly onto scene geometry at a designated timestamp during animation playback.

Decals are projected via directional raycasts originating from a skeletal bone or socket, automatically conforming to terrain, floors, walls, and dynamic scene obstacles.

Inspector Parameter Reference

Configure decal projection, materials, dimensions, and pooling in the node details panel:

Decal Source

Select how the decal graphic is defined:

• Decal Prefab / Prefabs: Assign one or more prefab assets. When multiple prefabs are provided, the system randomly selects one per trigger.
• Decal Material / Materials: Assign one or more material assets for direct projection.

Surface Raycasting

Controls the raycast query that detects surfaces to receive the decal:

• Raycast Direction: The local or world direction along which the surface detection ray is cast (e.g., (0, -1, 0) to project downward onto the floor).
• Max Ray Distance: The maximum search distance (in meters) from the socket origin to look for receiving geometry.
• Surface Normal Acceptance Angle: The maximum allowed slope angle between the ray direction and the hit surface normal (default: 75°). Surfaces steeper than this threshold reject the decal, preventing unnatural stretching on vertical cliffs or walls.
• Layer Mask: Specifies which physics layers are eligible to receive projected decals (e.g. Default, Ground, Environment).

Size & Dimensions

Fine-tune the projected decal's scale and footprint:

• Decal Size (m): Base footprint dimension in meters.
• Scale Multiplier: A uniform scale factor applied on top of the base decal size.
• Non-Uniform Scale: Toggle to independently control the width (X) and length (Y) of the decal on the surface plane. Ideal for directional skid marks, slash stains, angled weapon impacts, and blood drips.

Attachment & Lifetime

• Attach to Hit Object: When checked, parents the spawned decal to the hit surface GameObject. This ensures decals stay planted on moving platforms, elevators, or dynamic vehicles.
• Fade In: Smoothly ramps the decal opacity/alpha from 0 to full on spawn.
• Fade Out: Smoothly fades the decal out at the end of its duration before removal.
• Max Active Decals: Sets the maximum number of concurrent decals permitted for this event slot. When the limit is reached, the oldest decal is automatically recycled (0 = unlimited).
• Use Pool: Recycles decal GameObjects using the internal object pool instead of instantiating and destroying them. Always keep this enabled for high-frequency events to maintain zero runtime garbage collection.

URP Decal Projector Settings

When using Universal Render Pipeline (URP) Decal Projector components:

• Normal Blend: A slider from 0.0 (flat decal projection) to 1.0 (full surface normal interaction), controlling how the decal interacts with underlying surface normal maps and lighting.

Scene View Gizmos

• Show Decal Gizmos: Displays an interactive projection cone, surface detection ray, and hit boundary circle in the Scene View for visual alignment.
• Gizmo Color / Ray Color / Normal Color: Customizable viewport colors for the projection bounds, ray path, and surface normal indicator.

Spawn FX Node

The Spawn FX Node instantiates a custom GameObject prefab at a specified socket target. This is useful for temporary props (like drawing a sword, spawning a shield, dropping a footstep dust-cloud decal, or shooting a projectile model).

Inspector Parameter Reference

Spawning & Pooling Settings

• Prefab: The Unity GameObject prefab asset spawned by this node.
• Attach to Bone: Parents the spawned prefab GameObject directly under the target socket bone.
• Destroy on End: If checked, the spawned GameObject is automatically destroyed as soon as the timeline block ends.
• Use Pool: When enabled, the runtime system utilizes an object pooling manager rather than performing expensive Instantiate and Destroy operations.
  Workflow Tip: Always enable Use Pool for frequent visual effects (like weapon impact sparks or footprint decals) to maintain smooth frame rates.

Scale Transitions

You can fade the spawned GameObject's scale in and out dynamically over the block's timeline range:

• Use Scale Transition In / Out / Curves: Enables animating scale using custom curves.

Trajectory Spline Path

• Trajectory: Configure a Bezier spline path to make the spawned object travel along a specified vector path.

Cross-Actor Handover & Socket Retargeting

Spawn FX nodes fully support transferring instantiated props (swords, shields, torches, or shared props) between participants in multi-actor compositions:

• Enable Handover in the details panel.
• Assign the Receiver Actor ID and Receiver Human Bone (or Generic bone path).
• Set Handover Time and Transition Duration.
• Select Transition Mode (SmoothInterpolation, Instant, or FollowTrajectory).
• Check Retain on End if the prop should stay attached to the receiver after the sequence completes.

Script Event FX Node

The Script Event FX Node triggers custom code callbacks, invokes scripting methods, or broadcasts messages at specific timeline points. This allows you to integrate custom game logic (such as deducting player mana on a spellcast frame, calling a custom combat script, or toggling weapon colliders).

Inspector Parameter Reference

Event Tag & Target Context

• Script Event Tag: A string identifier representing this event type. Your game logic scripts can listen for this specific tag to execute custom code.
• Context Target Mode: Defines which GameObject receives the scripting callback (Root, Custom Bone).
• Custom Context Human Bone / Bone Name: Specifies the target bone.

Parameter Payloads

A list of key-value parameters passed along with the script trigger. You can define arguments directly on the timeline:

• Key / Type / Value: Set variable name, type (String, Int, Float, Bool), and the value passed to the receiving script.

Method Invocation (Unity SendMessage)

You can invoke specific component methods directly:

• Use SendMessage: If checked, utilizes Unity's standard SendMessage API.
• SendMessage Method: Enter the exact name of the C# function to execute. The runtime will look for any active script component containing this method name on the target context GameObject and execute it.

Transform FX Node

The Transform FX Node dynamically alters the position, rotation, or scale of a target bone or socket transform. It is commonly used for procedurally scaling weapon models, offsetting limb coordinates during climbs, or twisting attachments dynamically without modifying the underlying clip assets.

Inspector Parameter Reference

Drive Targets

You can selectively toggle which components of the target bone's transform are modified:

• Drive Position: Toggles modifying bone position (Target Local Position, Position Curves).
• Drive Rotation: Toggles modifying bone rotation (Target Local Euler, Rotation Curves).
• Drive Scale: Toggles modifying bone scale (Target Local Scale, Scale Curves).

Space & Mode Settings

• Mode:
  • Snap: Instantly overwrites the target bone's coordinates at the trigger start.
  • Interpolate: Blends coordinates over the node's duration.
• World Space: If checked, coordinates are processed in world space relative to the scene root. If unchecked, offsets are calculated relative to the parent bone's local coordinate system.
• Preserve Previous Transform: If checked, the target bone preserves its final overridden transform state when the timeline block ends, preventing it from snapping back.

Transition Blending

To prevent sudden bone pops, you can automate easing transitions:

• Use Position / Rotation / Scale Transition In / Out: Enables transition weight curves.

3D Bezier Spline Flight Trajectories

Transform FX nodes support authored 3D Bezier spline curves with interactive tangent handles in the Scene View and preset generation via the FX Path Tools HUD.

Actor Roster & Dynamic Alignment Window

The Actor Roster & Alignment Window is the central management hub for multi-character animations, choreography duets, dynamic summons, and procedural motion warping in MSMotion.

Open the window from the Composition Editor top toolbar by clicking either:

• 👥 Actors: Opens the Character Roster tab.
• ⚡ Alignment: Opens the Dynamic Alignment tab.

Tab 1: Character Roster

The Character Roster tab configures all participants involved in the composition — from primary heroes and dance partners to combat adversaries and temporary summons.

Managing Participant Characters

• + Add Participant Character: Appends a new character definition to the composition roster.
• Search & Filter: Quickly locate participants by display name, role, or skeletal rig type.
• Expand All / Collapse All: Toggles the display state of all actor cards for convenient inspection.

Participant Properties

Each character card exposes the following settings:

Dynamic / Temporary Actors (Summons & Ephemeral Entities)

When Actor Type is switched to Dynamic, the character represents an ephemeral entity — such as a summoned dragon, phantom weapon, spectral beast, or Stand avatar — that spawns, animates, and despawns automatically during the sequence:

• Dynamic Prefab: The prefab asset to instantiate for this entity.
• Spawn Time: Choose when the entity appears. Select from quick presets (0.0, 0.25, 0.5, 0.75, 1.0) or choose Custom.
• Destroy Time: Choose when the entity despawns and recycles back to the object pool (0.0, 0.25, 0.5, 0.75, 1.0, or Custom).
• Attachment Mode:
  • Caster Bone Socket: Snaps to a designated bone on the primary character (e.g. RightHand, Spine).
  • Caster Root Relative: Tracks the caster's root position with an authored spatial offset.
  • World Sync Offset: Spawns relative to the global interaction sync anchor.
• Custom Timeline Nodes: When spawn or destroy time is set to Custom, click + Add Spawn Node or + Add Destroy Node to place precise Spawn Actor and Destroy Actor blocks directly on the composition timeline.

Timeline Slot Routing & Visual Indicators

1. Assigning Slots: Select any timeline block (animation clip, FX node, or procedural solver). In the details panel, select the desired actor from the Target Character dropdown, or right-click any block and choose Assign to Actor > [Character Name].
2. Visual Badges: Slots assigned to secondary actors display a colored badge pill with the character's role and a matching tinted accent stripe along the top of the block.
3. Synchronized Scrubbing: Moving the timeline playhead scrubs all participant characters simultaneously in the Scene View with zero frame drift.

Tab 2: Dynamic Alignment (Motion Warping)

In real gameplay, characters rarely start at the exact relative positions and rotations required for a synchronized sequence. The Dynamic Alignment system bridges arbitrary starting distances dynamically: secondary actors travel smoothly to their sync spots, dynamically scaling their locomotion speed to match travel distance, before seamlessly crossfading into the synchronized interaction.

Pre-Interaction Entry Phase

Dynamic Alignment functions as an asynchronous Pre-Interaction Entry Phase rather than eating fixed time on the composition timeline. The composition timeline itself remains strictly focused on the synchronized choreography starting at t = 0.

Configuration Settings

• Enable Dynamic Alignment: Master switch enabling runtime approach warping and scene view visualization.
• Approach Locomotion Clip: The walking, jogging, or running animation played while characters travel toward their authored spots.
• Waiting / Idle Clip: The idle animation played if a character reaches their spot early while waiting for others to arrive.
• Primary Actor Waiting Clip: The idle animation played by the lead character (Actor 0) while waiting for secondary characters to approach.
• Min / Max Time (s): The minimum and maximum allowable approach duration in seconds (e.g. 0.5s to 4.0s).
• Min / Max Speed Multiplier: Playback speed bounds (e.g. 0.5x to 2.0x) preventing unnatural fast-forwarding or foot sliding.
• Natural Stride Speed (m/s): The character's authentic locomotion speed. Click Auto Stride to automatically analyze the locomotion clip's root motion curves and calculate the exact velocity.
• Arrival Threshold (m): Distance tolerance (e.g. 0.1m) within which a character is considered to have arrived at their spot.
• Adapt to Terrain: Enables ground raycasting during the approach path to keep feet planted on slopes, steps, or uneven ground.

Scene View Visualizer & Testing Tools

When Dynamic Alignment is active, the Scene View displays real-time alignment feedback:

• Sync Spot Discs: Cyan boundary rings marking each actor's authored arrival point and facing direction.
• Lead Anchor: A gold coordinate pivot highlighting the interaction sync origin.
• Trajectory Lines & Readouts: Dotted lines connecting each character's current position to their target spot, showing live distance, travel time, and calculated playback speed.
• Snap to Sync Spots: A quick-action button in the Scene HUD that snaps all preview characters to their authored interaction origins.
• Test Approach Offsets: Temporarily displaces secondary characters by several meters in the viewport so you can visually test and preview approach speeds without entering Play Mode.

Dynamic Actor Lifecycle Nodes

Dynamic Actor Lifecycle Nodes control the precise moment, spatial placement, entry transitions, and pool recycling of temporary or summoned actors (such as weapons, familiars, dragons, or Stand avatars) directly on the composition timeline.

To add lifecycle nodes to the timeline:

• Right-click on an FX or Actor track and choose Actor > Add Spawn Actor Node Here or Actor > Add Destroy Actor Node Here.
• Or click + Add Spawn Node / + Add Destroy Node inside the Actor Roster Window when a dynamic actor's timing preset is set to Custom.

1. Spawn Actor Node

The Spawn Actor Node triggers the instantiation and visual entry of a dynamic actor.

+-------------------------------------------------------+
|  [Spawn Actor]  Duration: 0.20s                       |
+-------------------------------------------------------+

Parameter Reference

• Attachment Mode:
  • World Sync Offset: Spawns relative to the shared composition sync anchor.
  • Caster Root Relative: Tracks the caster's root position while maintaining an authored offset.
  • Caster Bone Socket: Attaches as a child of a specific bone on the caster character (e.g., RightHand, Spine, Head).
• Attach Socket Bone: Name of the target socket bone when using socket attachment mode.
• Position Offset: Local Vector3 spatial offset applied relative to the attachment target.
• Rotation Offset Euler: Local rotation angles applied relative to the attachment target.
• Scale Offset: Initial scale factor applied to the spawned entity (default: 1, 1, 1).

Entry Transitions & Blending

• Use Scale Transition In: Enables an animated scale curve over the node's duration.
• Scale Transition Curve: Custom animation curve defining scale growth from spawn time (e.g. popping up from 0 to 1, or overshooting for a dynamic impact).
• Fade In Duration: Time (in seconds) over which material alpha or visual intensity ramps up smoothly.
• Show Gizmo: Displays an interactive position/rotation handle in the Scene View to visually position the spawn location.

2. Destroy Actor Node

The Destroy Actor Node handles the graceful despawn, fade-out, and pool recycling of a dynamic actor when its action completes.

+-------------------------------------------------------+
|  [Destroy Actor]  Duration: 0.25s                     |
+-------------------------------------------------------+

Parameter Reference

• Fade Out Duration: Time (in seconds) over which the entity fades out or dissolves before removal.
• Use Scale Transition Out: Enables an animated exit scale curve.
• Scale Transition Curve: Custom animation curve controlling how the entity shrinks or collapses before recycling.
• Return to Pool: When enabled, recycles the actor's GameObject back to the internal object pool rather than destroying it. Always keep this checked for smooth gameplay performance and zero runtime heap allocations.

Workflow: Authoring a Familiar or Weapon Summon

1. Open the Actor Roster Window (👥 Actors on the top toolbar).
2. Click + Add Participant Character and set its Actor Type to Dynamic.
3. Assign the entity's prefab and set its spawn and destroy timing to Custom.
4. In the timeline, move the playhead to where the character begins summoning and add a Spawn Actor Node.
5. Position the spawn handle in the Scene View (or choose a socket bone like RightHand).
6. Add animation clip blocks on the dynamic actor's track to drive its motion during the sequence.
7. Move the playhead to the end of the action and place a Destroy Actor Node with a 0.2s fade-out and Return to Pool checked.
8. Scrub the timeline to preview the summon appearing, animating, and despawning smoothly!

Interaction Overrides Preset Inspector

The Interaction Overrides Preset Inspector is a dedicated editor workspace for configuring post-export customization presets (MSMotionInteractionOverrides assets). It allows animators and designers to tailor multi-character choreographies for diverse gameplay situations—such as adapting body spacing for differing creature sizes, swapping character reaction clips, fine-tuning approach locomotion and pathfinding bounds, and redirecting prop handovers—without altering baked interaction configs or writing code.

Accessing & Creating Overrides Presets

1. In the Unity Project window, right-click and choose Create > Maharaja Studio > MsMotion > Interaction Overrides.
2. Select the created asset to inspect it in the Inspector window.
3. In the Target Interaction Config field, assign the baked choreography config asset (e.g. Takedown_Config or SalsaDuet_Config).

Interface Layout & Sections

+-----------------------------------------------------------------------------------+
| MSMotion Interaction Overrides (Banner)                                           |
| Target Interaction Config: [ S_Duet_Exported_Config                     (⊙) ]     |
+-----------------------------------------------------------------------------------+
| Detected Roles in Config                                                          |
| Participants: 2 | Dynamic Entities: 1 | Handovers: 2 | Duration: 4.37s | Loop: False |
| [ [Participant] partner (Actor_1) ▼ ]  [ Add Override ]                           |
| [               Populate All               ]  [             Sync from Config             ] |
+-----------------------------------------------------------------------------------+
| ▼ Interaction FX Registry (Global)                                                |
|   [✓] Global FX Registry Override: [ FXRegistry_DarkFlame                 (⊙) ]   |
+-----------------------------------------------------------------------------------+
| ▼ Participant Role Overrides (2)                                                  |
|   ...                                                                             |
| ▼ Dynamic Actor Overrides (1)                                                     |
|   ...                                                                             |
| ▼ Terrain Raycast Ground LayerMask                                                |
|   ...                                                                             |
| ▼ Live Runtime PlayMode Tools                                                     |
|   ...                                                                             |
+-----------------------------------------------------------------------------------+

1. Detected Roles in Config (Toolbar)

• Summary Readout: Displays total counts of detected participant roles, dynamic summons, cross-actor handovers, sequence duration, and looping state.
• Role Dropdown: Lists all detected participant and dynamic roles.
• Add Override: Adds a custom override card for the selected role.
• Populate All: Auto-generates override cards for every participant character and dynamic summon.
• Sync from Config: Refreshes all existing override cards with authored baseline values without resetting your active checkboxes.

2. Interaction FX Registry (Global)

• Global FX Registry Override: Checkbox + object picker (MSMotionFXRegistry). Swaps audio, particles, decals, and transforms across all participating characters without creating duplicate animation configs.

3. Participant Role Overrides

Each participant role card provides granular control over that specific character's animation, spacing, and approach locomotion:

• Animation Config / Animation Clip: Swaps out the character's entire playback package or individual core performance clip.
• FX Registry (Direct Role Override): Direct role-level FX registry override, taking precedence over the global interaction FX registry.
• Spatial Spacing (Offset): Position and rotation fields with override toggles. Offsets the character relative to the sync point at frame 0. Features dedicated [Copy] and [Paste] buttons.
  Monster & Scale Compensation: When executing a human grapple on a large Orc or Troll, enable Spatial Spacing and adjust the Z-offset to separate the characters and eliminate body mesh clipping.
• Speed Multiplier: Slider (0.0 - 5.0x) to scale playback speed independently (ideal for hit-stop pauses or heavy monster reaction delays).

4. The 4 Dynamic Alignment Approach Foldouts

Collapsible foldout sections with individual field toggles and active counter badges:

• 🎬 Locomotion & Gaits: Gait Mode (AutomaticWalkRun, WalkOnly, RunOnly, TeleportSnap), walk/run clips, threshold velocity/distance, crossfade durations, arrival downshifting, and waiting idle clip.
• 🧭 Pathfinding & Navigation: Navigation Mode (NoneLinear, SimpleObstacleAvoidance, NavMeshAgent, NavMeshPathfinding), capsule clearance radius, obstacle layer mask, corner smoothing radius, moving target tracking, and terrain raycasting.
• 🔄 Steering & Arrival Rotation: Angular turning speed (°/s), arrival alignment radius, orientation matching, and pivot-in-place thresholds.
• ⏱ Timing, Stride & Speed Bounds: Natural stride speed (with ⚡ Auto Stride root-motion extraction button), arrival stop distance, min/max duration clamps, min/max playback speed multipliers, acceleration rates, and custom velocity curves.

Productivity features: Right-click category headers to Enable All / Disable All, and use dedicated [Copy] / [Paste] buttons.

5. Dynamic Actor Overrides (Summons & Props)

• Prefab Override: Swaps the summoned object's prefab (e.g. skin variants or elemental weapons).
• Socket Override: Retargets the attachment bone on the caster character (e.g. RightHand, Spine2).
• Local Offset & Scale: Spatial adjustments and scale multipliers.
• Spawn & Destroy Timing: Overrides normalized timeline moments (0.0 - 1.0).

6. Live Runtime PlayMode Tools

When entering Unity Play Mode with an interaction running:

• Displays active session status and elapsed duration.
• Apply Overrides to Active Session button hot-reloads inspector changes directly into the running scene session without restarting playback!

Export Options

The Export Options window is used to bake a multi-layer composition, including its procedural solvers, physics modifiers, and event triggers, into a single, optimized Animation Clip or FBX asset.

To open the Export Options window, click the Export (💾 Icon) on the composition top toolbar.

Figure 9: Export Options Window

1. General Tab

Contains parameters for the core baking algorithms, formats, and post-export actions:

• Exporter:
  • Humanoid Pose Snapshot: Recommended for humanoid characters. Captures poses in normalized muscle coordinates, maintaining body scale independence.
  • Generic Transform Snapshot: Directly bakes the position, rotation, and scale of every individual bone transform. Required for non-humanoid rigs.
• Frame Rate: The sample rate in frames per second (FPS) for the baked clip (range: 1 to 240 FPS).
• Format: The output asset file type (AnimClip or FBX). FBX requires the Unity FBX Exporter package.
• After Export: Post-export action (PingAsset, OpenInAnimationWindow, ApplyToFirstAnimatorState).
• Tangent Mode: Defines the slope interpolation tangent type for the output curves (ClampedAuto, Auto, Linear).

2. Timeline Tab

Allows you to bake a specific segment of the timeline rather than the full composition duration:

• Custom Range / Start / End: Configure timeline range cropping. A highlighted blue segment on the visual bar indicates the cropped sub-range.

3. Actors Tab (Multi-Actor System)

Controls which participant characters are baked and how individual actor animation files and companion interaction configs are generated:

• Export Scope:
  • All Actors as Separate Clips: Bakes every actor present in the composition into an individual animation clip (e.g. Attack_Hero.anim, Attack_Boss.anim).
  • Active Actor Only: Bakes only one chosen participant actor into a single animation clip.
  • Custom Selection: Displays an interactive checklist allowing you to pick an arbitrary subset of actors to bake.
• Target Actor: When Scope is set to Active Actor Only, selects the specific character from the composition to bake.
• Filename Suffix Style: ActorDisplayName (e.g. _Hero, _Partner) or ActorId (e.g. _actor_0, _actor_1).
• Isolate FX Per Actor: Filters companion FX manifest events so each actor's companion manifest only contains FX nodes assigned to that specific character.
• Reset Origin On Export: Restores participant preview instances to their canonical origins before and after each bake pass to prevent spatial coordinate drift.

4. Root Motion Tab

Configures how the character's overall movement and root coordinates are processed and baked:

• Export Mode (Base Mode):
  • Standard: Bakes root movement exactly as solved on the timeline.
  • InPlaceXZ: Strips horizontal movement. Vertical root movement (Y) is preserved.
  • InPlaceFull: Strips all root displacement, forcing the root to remain locked to the starting origin.
• Per-Axis Strip: Additive overrides to lock specific channels (Strip Position X, Y, Z, and Yaw).
• Root Driver / World Space Baking: Configures what drives root motion and toggles world-space coordinates.

5. Filtering Tab

Filters which bones and properties are written to the final output file to minimize file size:

• Mask Asset: Restricts the export to a subset of character joints using an AvatarMask asset.
• Property Filter: Toggles to include or exclude Position (POS), Rotation (ROT), and Scale (SCL) curves.

6. Output Tab

Controls quality compression, event integration, and runtime manifest generation:

• Bake Events / Baking Mode: Embeds custom animation events.
• Bake Timeline Markers: Embeds custom markers from the timeline ruler as standard events.
• Rotation Mode: Quaternion (recommended) or Euler.
• Float Compression / Decimal Places: Quantizes values to clean precision noise.
• Keyframe Optimization: Removes redundant keyframes within tolerance limits (Position, Rotation, and Scale Error).
• Create Animation Config & Master Interaction Config: Automatically generates an MSMotionAnimationConfig asset linking the clip, metadata, and FX manifest. In multi-actor exports, this also generates the master MSMotionInteractionConfig asset binding all participant tracks, initial relative offsets, and dynamic alignment data.
• Runtime FX (MSMotion FX Layer):
  • Generate FX Manifest: Exports a custom FX manifest asset alongside the clip.
  • Embed FX Trigger Events: Embeds a single event wrapper (OnFXTrigger) per FX node on the clip.

Batch Export Queue

The Batch Export Queue is a pipeline optimization tool that allows you to queue multiple animation composition bakes and process them sequentially in a single batch. This prevents the editor from locking up repeatedly during iterative bakes.

Figure 10: Batch Export Queue Window

Accessing the Batch Queue

There are two primary ways to open the Batch Export Queue window:

1. Menu Bar: Choose Window > MSMotion > Batch Export Queue.
2. Export Window: Click the View Queue button in the footer of the Export Options window.

Adding Jobs to the Queue

Rather than exporting a composition immediately, you can queue it:

1. Open your composition and click the **Export** icon.
2. Configure your settings.
3. Click **Add to Queue** in the bottom footer. The window closes, and the job is added to the background queue.

Managing Queued Jobs

Inside the Batch Export Queue window, pending exports are listed as cards showing Job Index, Asset Output Name, Source Composition, Range Description, Exporter, and Target Output Path.

• Removing Jobs: Click the red cross button on the right side of any card, or click **Clear Queue** to empty the list.

Processing the Batch

Once you have added all desired compositions to the queue, click Process All Jobs in the bottom-right corner. The editor will sequentially load, solve, and bake each asset, displaying a progress tracker. When finished, the status bar will display All jobs processed successfully.

Metadata Manager

The Metadata Manager is a project utility that allows you to scan, hide, show, or permanently delete embedded **IK Stretch & Joint Scale Metadata** sub-assets across all Animation Clips in your Unity project.

Figure 11: Metadata Manager Window

What is MSMotion Metadata?

When you bake animations that utilize procedural IK or scaling modifications, MSMotion embeds specialized **Clip Metadata** sub-assets directly into the generated .anim files. These sub-assets contain scale calibration matrices and joint-length proportions. While required for correct runtime playback:

• They are normally hidden sub-assets inside the .anim files.
• Retiring old rigs or deleting compositions can leave orphaned metadata files inside the project database.
• Unused metadata sub-assets can accumulate over time, increasing file sizes.

Accessing the Metadata Manager

To open the utility window, choose Tools > Maharaja Studio > MsMotion > Metadata Manager from the Unity editor menu bar.

Scanning the Project

1. Click **Scan Project** in the toolbar.
2. A progress bar will display while the utility scans the Unity Asset Database for all .anim assets.
3. Upon completion, the list displays all Animation Clips containing embedded MSMotion metadata.

List Controls

Each detected clip card displays:

• Clip Icon & Title / Asset Folder Path: Identifies the clip.
• Visibility State: Displays whether the sub-asset is VISIBLE or HIDDEN in the Project window.
• Show / Hide Button: Instantly toggles the hierarchy visibility.
• Delete: Permanently removes the metadata sub-asset from the parent .anim file.
  Caution: Deleting a clip's metadata permanently removes its cached IK stretch and joint scale proportions. The clip will lose stretch calculations during solver playbacks.

Global Toolbar Operations

• Hide All / Show All: Bulk visibility toggles.
• Delete All: Deletes all embedded metadata from all scanned clips.
  Caution: This operation permanently deletes all IK/scale proportions from all clips. This action is irreversible.
• Search Bar: Type a clip name to filter the list instantly.

MSMotion Runtime System

MaharajaStudio MSMotion features a high-performance, modular runtime framework designed to drive characters using Unity's modern PlayableGraph API. By bypassing the rigid, memory-heavy Mecanim state machine controller model, MSMotion provides developers with direct, code-driven control over skeletal animation, visual and audio effects execution, Inverse Kinematics (IK), and real-time bone-stretching calculations.

Why MSMotion Runtime Matters

For studios and developers building performance-critical projects, the MSMotion runtime provides clear, production-tested advantages:

• Zero GC Allocations on Hot Paths: Once initialized, all play, crossfade, and event tick operations run entirely allocation-free to prevent frame-rate stuttering and GC spikes.
• On-Demand Layer Management: Mixers and playable inputs are allocated dynamically as animations play, ensuring minimal memory footprint for characters with large asset pools.
• Decoupled Procedural Solvers: FX spawning, rigging constraints, and bone scaling are split into clean, modular components that run in a single coordinate-compensated LateUpdate tick.
• Designer-Authored, Code-Driven: Designers use visual editor tools to package clips, overrides, events, and IK parameters into unified MSMotionAnimationConfig assets. Programmers play them with a single, clear line of C#.

System Architecture

The runtime framework is divided into dedicated managers that run alongside the standard Unity Animator. When multiple components are present on the same GameObject or across multiple characters, they coordinate automatically.

+-----------------------------------------------------------------------------------+
|                                  Gameplay Code                                    |
|     (Triggers Play, CrossFade, Stops, or MSMotionInteraction Choreography)        |
+-----------------------------------------------------------------------------------+
             |                                                  |
             v                                                  v
+------------------------------------+         +------------------------------------+
|         MSMotionAnimator           |         |       MSMotionInteraction          |
| (Drives PlayableGraph & Mixers)    |         | (Multi-Actor Orchestration Engine) |
+------------------------------------+         +------------------------------------+
       /          |          \                          |                    \
      v           v           v                         v                     v
+------------+ +------------+ +------------+   +-------------------+  +-------------------+
|  FXPlayer  | |  Stretch   | |    Rig     |   | Dynamic Summons & |  |    Interaction    |
| (Audio/VFX | | Applicator | | Controller |   | Actor Object Pool |  | Overrides Presets |
|   Pool)    | | (Scaling)  | |   (IK)     |   | (MSMotionActorPool)| | (Body Spacing/Gait)|
+------------+ +------------+ +------------+   +-------------------+  +-------------------+

Core Components

1. MSMotionAnimator: The central driver. It manages the core PlayableGraph, handles blending layers, and triggers fades and crossfades.
2. MSMotionInteraction: Multi-actor interaction and choreography runner. Coordinates synchronized multi-character playback, dynamic departure, and cross-actor partner targeting with 0ms frame drift.
3. MSMotionInteractionOverrides: Post-export preset system for multi-actor choreography. Manages granular field-level overrides, body spacing compensation, 4-category dynamic alignment foldouts, dynamic summons, and prop handovers.
4. MSMotionFXPlayer: Listens to the timeline playhead and schedules visual effects, particles, surface decals, sound, camera shakes, and custom script callbacks.
5. MSMotionRigController: Interfaces with Unity's Animation Rigging constraints, enabling dynamic procedural aiming, foot planting, and bone offsets.
6. MSMotionStretchApplicator: Applies procedural Squash & Stretch overrides directly to bones using baked keyframe curves.

Package Integration & Requirements

The runtime framework relies on the following configurations:

• Namespace: MaharajaStudio.MSMotion.Runtime
• Assembly Definition: MaharajaStudio.MSMotion.Runtime.asmdef

Dependency Compatibility

The runtime is designed to automatically compile and scale its capabilities depending on what packages are present in your project:

Installation

MSMotion's runtime framework compiles inside your standard Unity package hierarchy:

1. Open your project in Unity 2021.3 LTS or newer.
2. Import the package:
   • UPM (recommended): Add the package via git URL or from disk using the Unity Package Manager window.
   • Unity Package: Double-click the downloaded .unitypackage asset.
3. Click Import on the pop-up dialogue. All runtime scripts are compiled into Assets/com.maharajastudio.animation-editor/Runtime/ (or package folder).
4. The editor will compile and automatically define compile-time symbols based on your project's active packages.

Quick Start Guide

This guide gets your character animated and executing effects using the MSMotion runtime framework in under 5 minutes.

1. Character Component Setup

To use MSMotion runtime, attach the core components to your character's GameObject (the same GameObject hosting the Unity Animator component):

1. Select your character GameObject in the Hierarchy.
2. Add the MSMotion Animator component (MSMotionAnimator):
   • This component automatically finds and references the Unity Animator component.
   • Legacy Controller (Layer 0): Optionally assign your standard locomotion RuntimeAnimatorController. If left empty, the character will default to a rest pose on Layer 0.
3. Add the FX Player component (MSMotionFXPlayer):
   • Registry: Assign your project-wide MSMotionFXRegistry asset.
   • The FX Player automatically links with the MSMotionAnimator to tick and schedule visual/sound effects on active layers.
4. Add the Stretch Applicator component (MSMotionStretchApplicator):
   • This handles real-time Squash & Stretch scaling driven by exported animation metadata curves.
5. Add the Rig Controller component (MSMotionRigController):
   • Only required if your animations use IK constraint overrides.
   • Register your character's IK constraints under the Named Constraints list.

2. Authoring Animation Configs

MSMotion does not use string-based transition triggers or complex Animator Controller states. Instead, each animation is stored as a self-contained ScriptableObject asset:

1. Right-click in the Project window and select Create > Maharaja Studio > MsMotion > Animation Config.
2. Name the asset (e.g. SwordAttack_1.asset).
3. In the Inspector, configure the following:
   • Clip: Assign your native .anim Animation Clip.
   • Manifest: Assign the corresponding .asset manifest generated by the MSMotion Exporter.
   • Metadata: Assign the scale/stretch metadata asset (typically embedded inside or exported next to the clip).
   • Layer: Assign the PlayableGraph layer index (e.g., 1 for upper body, 2 for full-body overrides).
   • Fade In / Fade Out: Set custom blend durations in seconds (or leave at 0 for auto-computation based on 10% of the clip's length).

3. Scripting Playback

To trigger animations from your gameplay code, reference the MSMotionAnimator and your config assets, then call CrossFade() or Play():

using UnityEngine;
using MaharajaStudio.MSMotion.Runtime;

public class CharacterController : MonoBehaviour
{
    [Header("MSMotion References")]
    [SerializeField] private MSMotionAnimator _animator;

    [Header("Animation Config Assets")]
    [SerializeField] private MSMotionAnimationConfig _idleConfig;
    [SerializeField] private MSMotionAnimationConfig _slashConfig;

    private void Update()
    {
        // 1. Smoothly transition to a heavy slash animation on Layer 1
        if (Input.GetKeyDown(KeyCode.E))
        {
            // Crossfade will blend out whatever is currently playing on the config's layer
            _animator.CrossFade(_slashConfig);
        }

        // 2. Play then automatically transition back
        if (Input.GetKeyDown(KeyCode.Q))
        {
            // Queue Q after E sequentially
            _ = _animator.PlayThenCrossFade(_slashConfig, _idleConfig);
        }

        // 3. Immediately halt playback
        if (Input.GetKeyDown(KeyCode.Space))
        {
            _animator.Stop(_slashConfig);
        }
    }
}

4. Overriding FX Parameters at Runtime

To change sounds or particle prefabs dynamically (for example, playing different impacts based on weapon type or floor material), use Runtime FX Overrides.

These override containers are passed to MSMotionFXPlayer and apply overrides safely without modifying your ScriptableObject assets on disk:

using UnityEngine;
using MaharajaStudio.MSMotion.Runtime;

public class DynamicWeaponFX : MonoBehaviour
{
    [SerializeField] private MSMotionFXPlayer _fxPlayer;
    [SerializeField] private AudioClip _heavyMetalImpactClip;
    [SerializeField] private GameObject _fireSparkPrefab;

    public void ApplyHeavyWeaponOverrides()
    {
        // Override the audio clip for event "WeaponSlashSFX"
        var audioOverride = new MSMotionAudioFXOverride
        {
            EventId = "WeaponSlashSFX",
            OverrideClip = true,
            Clip = _heavyMetalImpactClip,
            OverrideVolume = true,
            Volume = 1.0f,
            OverridePitch = true,
            Pitch = 0.75f // deeper pitch for heavy weapon
        };

        // Override the particle prefab for event "SlashVFX"
        var particleOverride = new MSMotionParticleFXOverride
        {
            EventId = "SlashVFX",
            OverridePrefab = true,
            Prefab = _fireSparkPrefab,
            OverrideScaleMultiplier = true,
            ScaleMultiplier = 1.5f
        };

        // Apply to player - these immediately take priority
        _fxPlayer.SetRuntimeOverride(audioOverride);
        _fxPlayer.SetRuntimeOverride(particleOverride);
    }

    public void ClearWeaponOverrides()
    {
        _fxPlayer.ClearAllOverrides();
    }
}

Core Animation System

At the center of MSMotion's execution pipeline is the core animation playback system. Driven by Unity's low-level PlayableGraph API, this system replaces standard Animator Controllers with code-directed blending, dynamic layer allocation, and strict allocation-free runtime updates.

PlayableGraph Architecture

MSMotionAnimator constructs a custom PlayableGraph at runtime. The root of this graph is an AnimationLayerMixerPlayable.

• Layer 0 (Base Layer): Dedicated to locomotion. It can evaluate a standard Unity RuntimeAnimatorController or fallback to a default idle clip.
• Layer 1+ (Override/Action Layers): Created on demand. As you play animations on higher indexes, the graph dynamically grows to accommodate new mixer inputs, ensuring zero overhead for unused layers.

       [AnimationPlayableOutput]
                  |
    [AnimationLayerMixerPlayable] (Root)
       /          |          \
   [Layer 0]   [Layer 1]   [Layer 2] ...
    (Locomotion) (Attack)    (Emote)

The 2-Input Layer Mixer Pattern

To prevent skeletal popping and zero-transform squashing (where an empty or uninitialized track evaluates transforms to 0,0,0 and crushes the model), MSMotion implements two runtime layer configurations:

1. Mixer Mode (Idle Fallback)

If a layer has a default idle clip assigned (via _defaultIdleClips in the Inspector), the allocator binds an AnimationMixerPlayable sub-mixer to that layer slot.

• Input 0: The looping default/idle clip.
• Input 1: The active overriding action clip.
• The root layer weight is kept at 1.0, and crossfading transitions interpolate the weights inside this sub-mixer (e.g. fading Input 1 from 0 to 1 while fading Input 0 from 1 to 0).

2. Direct Mode (No Idle Fallback)

If no idle clip is declared for a layer, creating a sub-mixer would squash the character when no clip is playing.

• Instead, the AnimationClipPlayable is connected directly to the root AnimationLayerMixerPlayable.
• The root layer's weight starts at 0.0 and is faded up dynamically by MSMotionAnimator.

MSMotionAnimator API Reference

MaharajaStudio.MSMotion.Runtime.MSMotionAnimator : MonoBehaviour

The primary playback driver component. Must reside on the same GameObject as the Unity Animator.

Inspector Configuration Fields

• RuntimeAnimatorController _legacyController (locomotion): Locomotion blend controller assigned to Layer 0.
• AnimationClip[] _defaultIdleClips (per layer): Default clip played on each layer when no animation is active (e.g. index 0 = Layer 0 fallback, index 1 = Layer 1 fallback).
• MSMotionFXPlayer _fxPlayer: References the FX player. Automatically retrieved from the same GameObject if left unassigned.
• MSMotionStretchApplicator _stretchApplicator: References the stretch applicator. Automatically retrieved if left unassigned.
• MSMotionRigController _rigController: References the rig controller. Automatically retrieved if left unassigned.
• bool _applyRootMotionDirectly: If true, MSMotionAnimator applies root motion delta translations and rotations directly to the character's Transform.
• bool _applyFootIKOnIdle: If true, applies Unity's built-in Foot IK to default idle clips.

Events

• public event Action<MSMotionAnimationConfig> OnAnimationStarted;
  • Fires when an animation begins playing (at the start of its fade-in).
• public event Action<MSMotionAnimationConfig> OnAnimationCompleted;
  • Fires when a non-looping animation naturally finishes (after its fade-out completes).
• public event Action<MSMotionAnimationConfig> OnAnimationStopped;
  • Fires when an animation is explicitly stopped via code.
• public event Action<Vector3, Quaternion> OnRootMotionDelta;
  • Fires every frame inside OnAnimatorMove with the translation vector and rotation delta for the current frame. Use this to manually apply root motion in custom controllers.

Methods

Play

public void Play(MSMotionAnimationConfig config);

Plays the animation configuration immediately with a hard cut (no fade-in). Any active animation on the same layer is stopped instantly.

CrossFade

public void CrossFade(MSMotionAnimationConfig config, float fadeOverride = -1f);

Smoothly transitions to the new animation configuration. fadeOverride overrides both the fade-in and fade-out durations if greater than 0f.

PlayThenCrossFade

public async Awaitable PlayThenCrossFade(MSMotionAnimationConfig current, MSMotionAnimationConfig next);

Plays the current config, waits for its active duration to reach its fade-out threshold, and then smoothly crossfades into next.

Stop / StopSmoothly / StopAll

• public void Stop(MSMotionAnimationConfig config);: Immediately stops the animation, snapping the layer weight back to 0.
• public void StopSmoothly(MSMotionAnimationConfig config);: Smoothly fades out the active animation over its configured fade-out duration.
• public void StopAll();: Instantly halts playback across all layers, returning all layers to idle or bind poses, and terminates all active sustained FX.

Playback Control & Weights

• public void Pause(int layer) / public void Pause(MSMotionAnimationConfig config): Pauses playback on the layer (sets play speed to 0).
• public void Resume(int layer) / public void Resume(MSMotionAnimationConfig config): Resumes playback, restoring the speed defined in the active config.
• public void PauseAll() / public void ResumeAll(): Pauses or resumes all active animation playables.
• public void SetLayerWeight(int layer, float weight): Instantly sets the root layer mixer weight (clamped [0,1]).
• public void FadeLayerWeight(int layer, float targetWeight, float duration): Asynchronously interpolates the root layer weight to target weight over duration seconds.
• public void SetPlaybackSpeed(int layer, float speed) / public void SetPlaybackSpeed(MSMotionAnimationConfig config, float speed): Overrides the active animation's speed multiplier at runtime.

Query Methods

• public bool IsPlaying(MSMotionAnimationConfig config);: True if the config is active on its layer.
• public bool IsPlaying(int layer);: True if any action is playing on the layer index.
• public float GetNormalizedTime(int layer);: Returns playback progress [0, 1] on the layer.
• public float GetNormalizedTime(MSMotionAnimationConfig config);: Returns playback progress [0, 1] of the specific config.
• public float GetCurrentTime(int layer);: Returns the absolute playback head position in seconds.
• public MSMotionAnimationConfig GetActiveConfig(int layer);: Returns the active config asset on the layer.
• public float GetActiveWeight(int layer);: Returns the current layer blend weight.
• public int GetAllocatedLayerCount();: Returns total layers currently allocated in the graph.
• public AnimationClip GetCurrentClip(int layer);: Retrieves the currently active AnimationClip on the layer.
• public float GetClipLength(int layer);: Returns active clip length in seconds.
• public float GetTimeRemaining(int layer);: Returns remaining play duration (factors loop iterations).
• public float GetPlaybackSpeedMultiplier(int layer);: Returns the custom speed multiplier currently applied to the layer.
• public float GetEffectivePlaybackSpeed(int layer);: Returns the true real-world playback speed (combining clip base speed, layer multiplier, and global Animator.speed).
• public bool IsPaused(int layer);: Returns true if the animation on the given layer is actively paused.
• public bool IsFading(int layer);: Returns true if the layer is currently crossfading or transitioning weights.
• public UnityEngine.Playables.Playable GetActivePlayable(int layer);: Returns the generic active Playable struct for advanced graph modifications.
• public UnityEngine.Animations.AnimationClipPlayable GetActiveAnimationClipPlayable(int layer);: Returns the underlying AnimationClipPlayable if present.
• public UnityEngine.Animations.AnimatorControllerPlayable GetAnimatorControllerPlayable();: Returns the legacy controller playable running on Layer 0, if assigned.

MSMotionAnimationConfig Reference

MaharajaStudio.MSMotion.Runtime.MSMotionAnimationConfig : ScriptableObject

Drag-and-drop asset declaring playback settings. Create via: Assets > Create > Maharaja Studio > MsMotion > Animation Config.

Custom Sequences & Blending Example

using UnityEngine;
using MaharajaStudio.MSMotion.Runtime;

public class AdvancedAnimatorController : MonoBehaviour
{
    [SerializeField] private MSMotionAnimator _animator;
    [SerializeField] private MSMotionAnimationConfig _heavyAttack;
    [SerializeField] private MSMotionAnimationConfig _recoveryIdle;

    private void Update()
    {
        if (Input.GetKeyDown(KeyCode.Alpha1))
        {
            // Trigger heavy attack and transition to recovery once complete
            _ = PlayCombatChain();
        }
        
        if (Input.GetKeyDown(KeyCode.Alpha2))
        {
            // Dynamically slow down playback speed
            _animator.SetPlaybackSpeed(_heavyAttack, 0.5f);
        }
    }

    private async Awaitable PlayCombatChain()
    {
        Debug.Log("Starting Attack Chain...");
        
        // Play attack and automatically crossfade to recovery
        await _animator.PlayThenCrossFade(_heavyAttack, _recoveryIdle);
        
        Debug.Log("Combat Chain Completed and Returned to Recovery Idle.");
    }
}

External Graph & Host Mixer Attachment

For advanced pipelines such as custom locomotion systems, dialogue frameworks, or external playable controllers, MSMotionAnimator can attach its internal layers to a foreign host PlayableGraph without creating a redundant graph instance:

// Direct host mixer mode: action layers evaluate at config.Layer + layerOffset
animator.AttachToExternalGraph(externalGraph, hostMixer, layerOffset: 0);

// Sub-mixer mode: creates an internal sub-mixer plugged into targetLayerSlot
animator.AttachToExternalGraph(externalGraph, hostMixer, targetLayerSlot: 2);

// Clean disconnection:
animator.DetachFromExternalGraph();

• public bool IsExternalGraph { get; }: Returns true when attached to an external host graph.
• public PlayableGraph Graph { get; }: Accesses the active PlayableGraph.
• public AnimationLayerMixerPlayable RootLayerMixer { get; }: Accesses the active layer mixer.

Dynamic Visual & Avatar Rebinding (Modular Characters / Online Spawning)

For games with late-instantiated character visuals, skin swapping, or modular armor sets:

// Master one-liner to swap character visual rig at runtime:
animator.Rebind(newAnimator, newBoneRoot: null, rebuildGraph: true);

• public void Rebind(Animator newAnimator, Transform newBoneRoot = null, bool? rebuildGraph = null): Master one-liner that rebinds MSMotionAnimator, updates or retargets AnimationPlayableOutput, flushes and retargets bone caches in MSMotionFXPlayer, clears bone chains in MSMotionStretchApplicator, and updates MSMotionRigController.
• public void RebuildGraph(): Destroys and recreates the internal PlayableGraph from scratch. Useful when avatar skeleton structure changes completely.
• public Animator TargetAnimator { get; set; }: Property to get or assign the active Animator component (setting it automatically invokes Rebind).
• public bool AutoSearchChildrenForAnimator { get; set; }: When true (default), automatically searches child GameObjects for an Animator if one is not present on the root container GameObject.
• public event Action<Animator> OnAnimatorRebound: Fires whenever the target Animator is rebound or swapped at runtime.
• public void EnsureSubsystemReferences(): Auto-discovers or refreshes linked subsystem components (MSMotionFXPlayer, MSMotionStretchApplicator, MSMotionRigController) on the root GameObject or child GameObjects.
• public MSMotionFXPlayer FXPlayer { get; set; } / StretchApplicator / RigController: Direct properties to get/set linked subsystems.

Multi-Actor Interaction & Choreography System

MSMotion 2.0.0 introduces the Multi-Actor Interaction & Choreography System, enabling creators to author and execute complex synchronized multi-character animations — such as dance duets, martial arts grapples/takedowns, shared lifts, co-op puzzle interactions, and 3+ character cinematics — with one line of code and full runtime control.

Key Capabilities

• Synchronized Multi-Character Choreography: Coordinate 2, 3, or more characters playing interdependent animations with 0ms frame drift.
• Humanoid & Generic (Non-Humanoid) Support: Seamlessly mix Humanoids with Generic rigs (quadrupeds, monsters, robots, props) in the exact same choreography.
• Independent PlayableGraph Isolation: Every character maintains its own independent MSMotionAnimator and PlayableGraph. The system orchestrates them without graph conflicts, evaluation order glitches, or race conditions.
• Dynamic Participant Departure: Characters can break away or leave early (e.g. taking damage, hit reaction, interrupted) while remaining characters smoothly continue or cancel the choreography.
• Cross-Actor Partner Targeting: Hand/foot IK effectors and head look-at modifiers can directly target bones on partner characters.

1-Line-of-Code Runtime API

Playing a synchronized multi-character interaction requires just one line of C#:

using System.Collections.Generic;
using MaharajaStudio.MSMotion.Runtime;
using UnityEngine;

public class InteractionTrigger : MonoBehaviour
{
    [SerializeField] private MSMotionInteractionConfig salsaDuetConfig;
    [SerializeField] private MSMotionInteractionOverrides trollTakedownOverrides;
    [SerializeField] private MSMotionFXRegistry darkFlameRegistry;
    [SerializeField] private Transform movingStageAnchor;
    [SerializeField] private MSMotionAnimator leadDancer;
    [SerializeField] private MSMotionAnimator partnerDancer;

    public void PlayStandard()
    {
        // 1. Plays synchronized at lead character's position
        MSMotionInteraction.Play(salsaDuetConfig, leadDancer, partnerDancer);
    }

    public void PlayOnMovingTransform()
    {
        // 2. Dynamically anchored to a moving platform, elevator, or vehicle
        MSMotionInteraction.Play(salsaDuetConfig, movingStageAnchor, leadDancer, partnerDancer);
    }

    public void PlayWithDirectFXRegistry()
    {
        // 3. Direct FX Registry injection (replaces audio/particles without extra animation configs)
        MSMotionInteraction.Play(salsaDuetConfig, darkFlameRegistry, leadDancer, partnerDancer);
    }

    public void PlayWithPerRoleFX()
    {
        // 4. Per-role FX Registry dictionary (e.g. fire partner vs ice victim)
        var roleRegistries = new Dictionary<string, MSMotionFXRegistry>
        {
            { "lead", fireRegistry },
            { "partner", iceRegistry }
        };
        MSMotionInteraction.Play(salsaDuetConfig, roleRegistries, leadDancer, partnerDancer);
    }

    public void PlayWithOverrides()
    {
        // 5. Designer-authored ScriptableObject overrides preset
        MSMotionInteraction.Play(salsaDuetConfig, trollTakedownOverrides, leadDancer, partnerDancer);
    }
}

Native Unity 6 Async Execution (PlayAsync)

When sequencing game choreography, cutscenes, combat finishers, or dialogue interactions, you can use Unity 6's native Awaitable to await completion asynchronously:

public async Awaitable ExecuteCinematicDuet()
{
    // Plays and suspends execution until the interaction finishes naturally or is stopped
    var session = await MSMotionInteraction.PlayAsync(salsaDuetConfig, leadDancer, partnerDancer);
    
    Debug.Log($"Interaction {session.Config.name} finished! Continuing cutscene...");
}

public async Awaitable ExecuteWithCancellation(CancellationToken ct)
{
    // Awaits with full cancellation token support (e.g. player skipped cutscene)
    await MSMotionInteraction.PlayAsync(salsaDuetConfig, movingStageAnchor, ct, leadDancer, partnerDancer);
}

Query, Introspection & Session Lifecycle

// Query status
bool isBusy = MSMotionInteraction.IsInInteraction(character);
bool isSequenceRunning = MSMotionInteraction.IsInteractionActive(salsaDuetConfig);

// Introspection
if (MSMotionInteraction.TryGetSession(character, out var session))
{
    Debug.Log($"Playing interaction elapsed: {session.ElapsedTime}s (Progress: {session.NormalizedTime * 100f}%)");
}

// Global pause / resume
MSMotionInteraction.PauseAllInteractions();
MSMotionInteraction.ResumeAllInteractions();

// Stop specific actor with cascade policy
MSMotionInteraction.StopInteractionFor(character, fadeOutTime: 0.2f, InteractionCascadePolicy.ContinueRemaining);

// Stop all interactions
MSMotionInteraction.StopAllInteractions(fadeOutTime: 0.25f);

Fluent Builder & Runtime Control

MSMotionInteraction.Play or MSMotionInteraction.Prepare returns an MSMotionInteractionSession instance that exposes fluent chaining controls:

MSMotionInteraction.Prepare(salsaDuetConfig, leadDancer, partnerDancer)
    .SetSyncPoint(movingStageAnchor)
    .OverrideFXRegistry(darkFlameRegistry)
    .OverrideActorFXRegistry("partner", holyAuraRegistry)
    .SetFadeIn(0.3f)
    .SetFadeOut(0.25f)
    .OnComplete(() =>
    {
        Debug.Log("Dance duet completed successfully!");
    })
    .OnActorStopped(actor =>
    {
        Debug.Log($"{actor.name} left the interaction.");
    })
    .Play();

Dynamic Participant Departure (StopActor)

In games, characters often need to break away early — for example, if Character B takes damage, is interrupted by combat, or triggers a ragdoll:

// Character B gets hit and must react immediately:
session.StopActor(characterB, fadeOutTime: 0.15f, InteractionCascadePolicy.ContinueRemaining);

Cross-Actor IK & Look-At Targeting

• IK Chain Modifier: Set PartnerActorId to target a partner character, and specify either PartnerHumanBone (for Humanoids) or PartnerBonePath (for Generic rigs). The effector pins directly to the partner's bone in world space.
• Look-At Modifier: Set PartnerActorId to make a character dynamically turn their head, spine, and eyes toward the partner's head or chest during the sequence.

Dynamic / Temporary Actors (Summons & Ephemeral Entities)

MSMotion supports ephemeral entities like summoned dragons, phantom weapons, Stand avatars, spectral beasts, or familiars that:

• Spawn automatically at a precise moment in the animation.
• Attach to the caster's root, a specific bone/socket (e.g. right hand, spine), or the world sync point.
• Play their companion animation in full synchronization.
• Automatically despawn, dissolve/fade out, and recycle back to the zero-allocation MSMotionActorPool.
• Zero Gameplay Code Required: The gameplay programmer merely calls animator.Play(attackConfig). The companion interaction engine manages the dynamic actor's lifecycle under the hood.

Motion Warping & Dynamic Alignment System

In gameplay scenarios, characters rarely stand at the exact millimetric coordinate authored for a synchronized duet or grapple. The Dynamic Alignment System bridges arbitrary starting distances dynamically:

• Secondary actors travel smoothly toward their authored sync spots using their designated locomotion clip (e.g. walk, run).
• Animation playback speed dynamically scales to match travel distance and duration without foot sliding.
• Characters arriving early enter a Waiting / Idle state until all participants reach their spots.
• Once all participants arrive, all actors seamlessly crossfade into the main synchronized choreography together.

Cross-Actor FX & Prop Handover

Cross-Actor Handover is supported across all visual, audio, and physical effect nodes:

Interaction Overrides System (MSMotionInteractionOverrides)

The MSMotion Interaction Overrides System provides a non-destructive, designer-friendly preset workflow for multi-actor choreographies. It allows technical animators, game designers, and programmers to adapt baked interaction sequences post-export—compensating for character body dimensions, swapping reaction clips, retargeting weapon variants, fine-tuning pre-interaction locomotion & motion warping, and redirecting prop handovers—with zero re-exporting and zero code modifications.

Key Capabilities & Highlights

• Non-Destructive Post-Export Customization: Modify character spacing, playback speed, locomotion clips, and summons without touching the authored MSMotionInteractionConfig asset.
• Granular Field-Level Toggles: Every individual property features an independent toggle checkbox. Only explicitly enabled properties override the baseline; unselected properties automatically inherit authored settings from the interaction track.
• Full Baseline Pre-Filling: All fields are pre-populated with baseline authored values from the target interaction config, letting designers see existing defaults before tweaking.
• 4-Category Dynamic Alignment Foldouts: Locomotion & Gaits, Pathfinding & Navigation, Steering & Arrival Rotation, and Timing, Stride & Speed Bounds.
• ⚡ Auto Stride Derivation: Automatically analyzes walk animation root-motion curves and extracts the exact linear velocity in one click.
• Dynamic Summoned Actor & Prop Overrides: Swap summoned weapon prefabs, bone attachment sockets, local offsets, 3D scale multipliers, and spawn/despawn timestamps.
• Direct FX Registry Overrides: Override sound, particle, decal, and transform themes globally or per-role without creating duplicate animation configs.
• Live Runtime PlayMode Tools: Detects active scene sessions with a 1-click Apply Overrides to Active Session button.
• 1-Line C# Execution: Play directly via MSMotionInteraction.Play(config, overrides, actors...).

Architecture & Evaluation Hierarchy

When an interaction executes, values resolve in strict order of precedence:

1. Runtime Fluent Overrides: Programmatic session calls made before playback (e.g. session.OverrideActorClip(...)).
2. Interaction Overrides Preset (MSMotionInteractionOverrides):
   • Role-Specific Overrides: Explicitly enabled clip, config, offset, speed, and FX registry overrides take highest priority within the preset.
   • Interaction-Wide Overrides: Global settings such as interaction-wide FX Registry and ground LayerMask apply to all roles not individually overridden.
3. Authored Baseline Configuration (MSMotionInteractionConfig): Default values authored in the Composition Editor timeline and Actor Roster window.

Participant Role Overrides Reference

The 4 Dynamic Alignment Foldout Categories

1. 🎬 Locomotion & Gaits

2. 🧭 Pathfinding & Navigation

3. 🔄 Steering & Arrival Rotation

4. ⏱ Timing, Stride & Speed Bounds

Dynamic Actor Overrides Reference

C# Runtime API Reference

using MaharajaStudio.MSMotion.Runtime;
using UnityEngine;

public class InteractionTrigger : MonoBehaviour
{
    [SerializeField] private MSMotionInteractionConfig salsaDuetConfig;
    [SerializeField] private MSMotionInteractionOverrides trollPartnerOverrides;
    [SerializeField] private MSMotionAnimator leadDancer;
    [SerializeField] private MSMotionAnimator partnerDancer;

    public void ExecuteChoreography()
    {
        // 1-line execution applying all designer-authored overrides:
        MSMotionInteraction.Play(salsaDuetConfig, trollPartnerOverrides, leadDancer, partnerDancer);
    }
}

Pre-Flight Preparation & Session Augmentation

// 1. Prepare session with base config and designer overrides
var session = MSMotionInteraction.Prepare(grappleConfig, heavyOverrides, attackerAnim, victimAnim);

// 2. Programmatically augment specific parameters at runtime
session.SetActorSpeedMultiplier("victim", 0.75f);

// 3. Initiate synchronized playback
session.Play();

Practical Recipes

• Recipe 1: Giant Monster Grapple (Spatial Body Compensation): Create an Interaction Overrides asset, add role 'victim', enable Spatial Spacing (Offset) with Position Offset Z = +0.45m to push the monster back and prevent body mesh clipping, and set Speed Multiplier to 0.85x for a heavy, weightier reaction.
• Recipe 2: Injured Participant Approach: In the role override for Character B, unfold Locomotion & Gaits, set Gait Mode to WalkOnly, assign Humanoid_Limping_Walk, click ⚡ Auto Stride in Section 4 to extract the limping speed, and clamp Max Playback Speed to 1.0x.
• Recipe 3: Weapon Disarm & Handover to Teammate: In the Handover Overrides list, add an entry, set EventIdOrRoleId to 'disarm_sword', ReceiverActorId to 'teammate', and ReceiverBone to 'RightHand'.

Rigging & IK System

MSMotion integrates procedural skeletal control with Unity's modern Animation Rigging package via the MSMotionRigController component. By mapping rigging constraints to abstract string identifiers, the system completely decouples runtime targeting logic from individual character bone structures.

The Decoupling Pattern

Standard IK setups bind gameplay targets directly to specific skeletal transforms, making it difficult to reuse animations across characters with different bone hierarchies. MSMotion solves this with a Slot-Based Decoupling Pattern:

1. Named Constraints: In the Inspector, the developer maps a string Id (e.g. "LeftFoot", "LookAtTarget") to a specific IRigConstraint component on the character (such as a TwoBoneIKConstraint or MultiAimConstraint).
2. Asset Configuration: The MSMotionAnimationConfig defines constraint behaviors by referencing the string Id inside its IKOverrides list.
3. Dynamic Execution: When the animator plays the config, it requests MSMotionRigController to activate the slot. The controller resolves the mapping and drives the target weight, leaving gameplay code to only manage target positions.

This means the exact same MSMotionAnimationConfig asset can play on a giant, a goblin, or a standard hero, provided each character has registered the correct constraint slots.

Blending & Timing Rules

Each IK override entry (MSMotionIKEntry) specifies custom timing parameters:

• Target Weight: The target weight [0, 1] to apply to the constraint.
• Delay Start / End: Delays in seconds before blending the IK constraint in or out.
• Fade In / Fade Out: Speeds to ramp the constraint weight (falls back to animation fade speeds if set to 0).
• Blend Mode:
  • Override: Linearly blends towards the target weight, overriding lower layers.
  • Additive: Adds weight on top of lower active solvers (clamped to a max of 1.0).

Pole Vector Stabilization (Hint Math)

For limbs using a TwoBoneIKConstraint (such as arms and legs), rapid movement of the target can cause joints (like knees or elbows) to flip violently. MSMotionRigController includes a built-in mathematical stabilization solver. If an IK constraint target is set and an IK hint (pole vector) transform is registered, the controller evaluates the bone geometry of the limb every frame, computes a stable bend normal vector, and applies a spherical interpolation (Slerp) blending toward the limb's natural rest bend direction.

Cross-Layer Suppression

If multiple override layers are active simultaneously (for example, a character running while executing a dynamic sword slash), the IK solvers on lower layers should not distort the active upper-body action. If _enableCrossLayerSuppression is enabled, the controller checks the weight of higher layers. If a higher layer is active, non-additive, and has an AvatarMask that covers the bone driven by a lower layer's IK constraint, the controller reduces the effective blend weight of that lower IK solver proportionally.

MSMotionRigController API Reference

MaharajaStudio.MSMotion.Runtime.MSMotionRigController : MonoBehaviour

• public void SetTarget(string constraintId, Transform target);: Assigns a world-space Transform target to the specified constraint slot. The target is tracked dynamically every frame.
• public void ClearTarget(string constraintId);: Clears the active target, disabling the constraint.
• public void RegisterConstraint(string id, IRigConstraint constraint);: Registers an IK constraint programmatically (useful for procedurally spawned rigs or modular characters). Replaces any existing slot with the same ID.
• public void UnregisterConstraint(string id);: Removes the slot mapping from the lookup table.
• public void PauseIK();: Pauses all IK evaluations, locking the current weight levels in place.
• public void ResumeIK();: Resumes dynamic weight and target evaluations.
• public void SetCrossLayerSuppression(bool enable);: Enables or disables automatic weight culling based on higher active layers' masks.
• public float GetConstraintWeight(string constraintId);: Returns the actual final weight [0, 1] applied to the constraint component in the current frame.
• public bool IsConstraintActive(string constraintId);: Returns true if the constraint is actively being driven by any playing animation layer.
• public IRigConstraint GetConstraint(string constraintId);: Retrieves the underlying Unity IRigConstraint interface matching the slot ID (useful for low-level custom modifications).
• public int GetRegisteredConstraintCount();: Returns the total number of constraint slots currently registered on this rig controller.

Procedural Aiming C# Example

using UnityEngine;
using MaharajaStudio.MSMotion.Runtime;

public class CharacterAimer : MonoBehaviour
{
    [SerializeField] private MSMotionRigController _rigController;
    [SerializeField] private string _aimConstraintId = "HeadLookAt";
    [SerializeField] private Transform _targetTransform;
    [SerializeField] private float _aimDistanceThreshold = 15f;

    private void Update()
    {
        if (_targetTransform == null) return;
        float distance = Vector3.Distance(transform.position, _targetTransform.position);

        if (distance <= _aimDistanceThreshold)
        {
            _rigController.SetTarget(_aimConstraintId, _targetTransform);
        }
        else
        {
            _rigController.ClearTarget(_aimConstraintId);
        }
    }
}

Stretch & Scale System

MSMotion includes a high-performance procedural scaling solver managed by the MSMotionStretchApplicator component. It applies Squash & Stretch scale transformations directly to skeletal bone transforms at runtime based on curves baked into animation metadata.

Standalone vs. Driver Execution Modes

The applicator adapts automatically to your character's setup, running in one of two modes:

1. Standalone (Vanilla) Mode

If no MSMotionAnimator is present on the GameObject, the applicator runs in standalone mode:

• Every frame, it polls Animator.GetCurrentAnimatorClipInfo(0) to detect active animation clips.
• Upon clip change, it searches for an embedded MSMotionClipMetadata sub-asset and evaluates scale curves in sync with the state's normalized playback time.

2. Driver Mode

When bound to an MSMotionAnimator driver component, the applicator bypasses Animator polling. The animator actively updates the applicator, allowing it to blend scale curves across **multiple layers** simultaneously, respecting active layer weights, additive blending modes, and isolated bone AvatarMask boundaries.

Cross-Layer Scale Suppression

To maintain visual consistency during multi-layer blending, lower-layer scale curves must not distort bone segments actively driven by higher-priority actions. If _enableCrossLayerSuppression is enabled, the applicator evaluates bones layer-by-layer in ascending order and dynamically suppresses lower-layer scale curve weights if a higher, non-additive layer is active and its mask includes the same bone:

Level-of-Detail (LOD) & Distance Culling

Procedurally modifying bone scales every frame across dozens of characters can quickly exhaust CPU resources. To prevent this, MSMotionStretchApplicator implements a distance-based Level-of-Detail (LOD) optimization system that dynamically adjusts evaluation intervals:

[Camera] ===== Near =====> [ Near LOD: Tick Every Frame ]
          ===== Mid ======> [ Mid LOD: Tick Every N Frames ]
          ===== Far ======> [ Far LOD: Capped / Restored Bind Scale ]

MSMotionStretchApplicator API Reference

MaharajaStudio.MSMotion.Runtime.MSMotionStretchApplicator : MonoBehaviour

• public void PauseStretch(); / public void ResumeStretch();: Freezes or resumes real-time scale calculations.
• public void ClearVanillaStretch();: Instantly restores all affected bones to their original bind-pose local scales when in Standalone mode.
• public void SetLODSettings(float nearDistance, float farDistance, int midLODInterval);: Configures LOD thresholds and frame-skipping intervals at runtime.
• public int GetCurrentLODInterval();: Returns the currently active LOD update interval.
• public void SetCrossLayerSuppression(bool enable);: Toggles whether higher-layer Avatar Masks dynamically suppress lower-layer bone scale curves.
• public int GetActiveStretchLayerCount();: Returns the number of layers actively contributing to stretch calculations (always returns 0 in Standalone mode).
• public void SetMetadata(MSMotionClipMetadata metadata);: Manually assigns a metadata asset. Only applicable when running in Standalone (Vanilla) mode.

LOD Configuration C# Example

This example demonstrates how to adjust culling thresholds dynamically based on graphics quality settings:

using UnityEngine;
using MaharajaStudio.MSMotion.Runtime;

public class PerformanceManager : MonoBehaviour
{
    [SerializeField] private MSMotionStretchApplicator[] _applicators;

    public void ApplyGraphicsSettings(bool highPerformanceMode)
    {
        foreach (var applicator in _applicators)
        {
            if (highPerformanceMode)
            {
                // Strict performance: cull early, skip frames frequently in mid-range
                applicator.SetLODSettings(5f, 25f, 4);
            }
            else
            {
                // High visual quality: extend full-rate evaluation distance
                applicator.SetLODSettings(15f, 60f, 2);
            }
        }
        
        Debug.Log($"[Performance] Adjusted {_applicators.Length} stretch applicators.");
    }
}

Dynamic Bone Subdivision (DBS) (Exp)

The Dynamic Bone Subdivision (DBS) system creates fluid, snake-like, or elongated movements for existing bones without requiring the source rig to have extra bones authored. It preserves mesh integrity while producing stylized animations such as long-neck creatures, stretchy arms, or flowing tails.

System Architecture

The system operates across two main phases:

1. Editor & Baking Phase

During composition editing, virtual bones are dynamically inserted and solved using a high-performance FABRIK algorithm. Upon export, virtual bone positions and rotations are baked directly into the output .anim clip, embedding a lightweight SubdividedChainMetadata sub-asset alongside it.

Dummy Bones & Smart Child Propagation

When a bone is subdivided, its mesh weights transfer to virtual bones while the original bone becomes a dummy bone (tagged with [DUMMY] in the editor):

• Smart Re-parenting: Children located at the tip (e.g. Head on Neck) auto-attach to the virtual chain end; base children (e.g. ShoulderPad) remain at the base.
• Tip Rotation Preservation: Uses minimal-arc FromToRotation so tip children maintain local axes without twisting.

2. Runtime Playback Phase

Runtime playback is zero-solver and lightweight because it does not execute IK/FABRIK algorithms per frame:

1. Attach SubdividedChainApplicator to your character (alongside MSMotionAnimator or Animator).
2. The component detects active SubdividedChainMetadata from the playing clip.
3. Hierarchy and child propagation are reconstructed seamlessly.
4. In LateUpdate, baked curves from the animation clip sample and drive virtual bones directly.

Additive Blending & Crossfading

The SubdividedChainApplicator includes a BlendWeight property (0.0 to 1.0):

// Smoothly transition into a subdivided state over 0.5 seconds
StartCoroutine(applicator.FadeIn(0.5f));

// Smoothly transition back to original bind pose
StartCoroutine(applicator.FadeOut(0.5f));

Mesh Preservation (Skin Weight Redistribution)

To prevent mesh distortion, the SkinWeightRedistributor creates a dynamic copy of the SkinnedMeshRenderer's mesh during baking. It intelligently extracts the top 4 most significant bone influences per vertex, bypassing Unity vertex buffer limitations while maintaining mesh fidelity.

FX & Event System

MSMotion includes a robust, frame-accurate runtime FX execution engine managed by the MSMotionFXPlayer component. This system schedules, pools, and blends audio clips, particle bursts, visual effect graphs, camera shakes, procedural transform adjustments, and custom game logic callbacks in sync with character animation frames.

Dispatch Mechanisms

The FX Player supports two high-performance execution modes, which are transition automatic:

1. Animation Event Mode (OnFXTrigger)

For standalone or legacy projects, the exported .anim clip embeds exactly one AnimationEvent per FX node. This event calls OnFXTrigger(string eventId), performing a fast dictionary lookup on the active manifest and immediately firing the matching effect. This minimizes overhead by avoiding per-frame timeline scrubbing.

2. Driver Mode (TickByDriver)

When an MSMotionFXPlayer resides alongside an MSMotionAnimator, the animator binds the player into Driver Mode. The playback dispatcher completely ignores OnFXTrigger animation events. Instead, the animator calls TickByDriver(layer, compositionTime) every LateUpdate frame, giving the engine precise sub-frame scrubbing capability.

The Three-Level Priority Override System

MSMotion utilizes an override structure designed to allow assets (e.g., footstep sounds on sand vs. concrete) to be swapped without needing to re-author or re-export animation clips:

+---------------------------------------------+
|  3. Runtime Overrides (Highest Priority)    | -> Set via SetRuntimeOverride() in C#
+---------------------------------------------+
                       |
+---------------------------------------------+
|  2. Global Registry Overrides               | -> Assigned via MSMotionFXRegistry asset
+---------------------------------------------+
                       |
+---------------------------------------------+
|  1. Manifest Defaults (Lowest Priority)      | -> Authored in the visual timeline editor
+---------------------------------------------+

• Manifest Defaults: The fallback assets and timing configurations baked into the exported MSMotionFXManifest.
• Global Registry Overrides: An MSMotionFXRegistry ScriptableObject mapping stable EventId keys to customized assets. If an entry is found, it overrides the manifest default.
• Runtime Overrides: Dynamic override containers (MSMotionAudioFXOverride, etc.) set programmatically via C# on a specific character instance. These take absolute priority and never modify assets on disk.

Detailed FX Event Reference

All events inherit from the base MSMotionFXEvent class, which declares common fields: EventId (GUID string), TriggerTime / Duration (seconds), Loop (bool), BlendIn / BlendOut (seconds), TargetBone (string) / TargetHumanBone (HumanBodyBones), and TransformSpace (FXTransformSpace: FollowTarget or FixedAtSpawnLocation).

1. AudioFXEvent: Plays an AudioClip at the target bone.
   • Clip (AudioClip): The audio clip asset.
   • Volume / Pitch (float): Base playback parameters.
   • PitchVariance (float): Adds random pitch variations per play: Pitch +/- Random(-Variance, +Variance).
   • SpatialBlend (float): 0 = 2D (stereo UI/music), 1 = 3D (world-space spatial).
   • MinDistance / MaxDistance (float): 3D roll-off bounds.
   • VolumeTransitionInCurve / VolumeTransitionOutCurve (AnimationCurve): Volume ramps.
2. ParticleFXEvent: Spawns a legacy Particle System prefab.
   • Prefab (GameObject): Prefab to instantiate.
   • PlayMode (ParticlePlayMode): OneShot (single burst), Sustained (loops over duration), or ManualEmit (triggers Emit(EmitCount)).
   • EmitCount (int): Number of manual particles to emit.
   • ScaleMultiplier (float): Uniform local scale adjustment.
   • AttachToBone (bool): Parent the instance under the target bone.
   • WaitForCompletion (bool): Restores the instance to the pool only after all particles have decayed.
3. VFXGraphFXEvent: Spawns a Visual Effect Graph asset.
   • VFXAsset (VisualEffectAsset): The graph to run.
   • ParameterOverrides (List<VFXParameterOverride>): Unions of types (float, int, bool, Vector4, Texture, Mesh) mapped to exposed graph parameters.
   • StopAtDurationEnd (bool): Sends a "Stop" event to the graph at the end of the duration.
   • TransitionPropertyName (string): Exposed property name (e.g. SpawnRate) scaled by the event weight transitions.
4. CameraShakeFXEvent: Triggers a Cinemachine impulse shake.
   • ImpulseSourcePrefab (GameObject): Cinemachine impulse source component host.
   • Amplitude / Frequency (float): Intensity and speed multipliers.
   • ImpulseDirection (Vector3): Force vector direction.
   • UseCharacterForward (bool): Rotates the direction relative to the character's facing direction.
   • PropagationRadius (float): Distance limit for cameras to feel the impulse.
5. SpawnFXEvent: Instantiates a generic GameObject prefab.
   • Prefab (GameObject): Prefab to spawn.
   • DestroyOnEnd (bool): If true, destroys (or returns to pool) the instance when the event duration expires.
   • UsePool (bool): Uses MSMotionFXPool to prevent instantiation garbage collection.
   • AttachToBone (bool): Parent the spawned object to the target socket.
6. TransformFXEvent: Drives bone or target transform offsets over time.
   • Mode (TransformFXMode): Snap (immediate), Lerp (linear blend), SmoothStep (slow-fast-slow), or Curve (evaluates custom curves).
   • DrivePosition / DriveRotation / DriveScale (bool): Property switches.
   • TargetLocalPosition / TargetLocalEuler / TargetLocalScale (Vector3): Goal properties.
   • PreservePreviousTransform (bool): Blends smoothly starting from the bone's pre-event transform instead of cutting.
7. ScriptFXEvent: Triggers developer-defined logic callbacks.
   • ScriptEventTag (string): Identifier passed to listeners (e.g., FootstepRight, ApplyDamage).
   • ContextTargetMode (FXOverrideTargetMode): Target resolution (Root, NodeTargetBone, SpawnedObject).
   • Parameters (List<ScriptFXParameter>): Key-value pairs containing floats, strings, ints, colors, and asset references.
   • UseSendMessage (bool): Automatically executes GameObject.SendMessage on the target.
   • SendMessageMethod (string): The script method name to invoke.

Spline Trajectory System

Both ParticleFXEvent and VFXGraphFXEvent support Bezier Trajectories (FXTrajectoryData). When enabled, the FX Player hands evaluation to FXTrajectoryEvaluator to move the effect along a bezier spline path over its active duration:

• Coordinate Space: Can evaluate in AbsoluteWorld space or RelativeToAnchor (relative to the target bone at the moment of spawning).
• Align to Path: If true, rotates the spawned object to face the forward tangent of the path (useful for projectiles or trailing VFX).
• Easing Curve: An AnimationCurve remapping time [0,1] to accelerate, decelerate, or loop travel along the spline.

Global Script Event Bus

When a ScriptFXEvent is fired, it triggers the player's local OnScriptEvent. If a global MSMotionScriptEventBus asset is assigned to the active registry, the player forwards the event globally:

using UnityEngine;
using MaharajaStudio.MSMotion.Runtime;

public class GameSoundManager : MonoBehaviour
{
    // Assign the same ScriptEventBus asset here as in your FXRegistry
    [SerializeField] private MSMotionScriptEventBus _globalEventBus;

    private void OnEnable()
    {
        _globalEventBus.OnEvent += HandleGlobalFXEvent;
    }

    private void OnDisable()
    {
        _globalEventBus.OnEvent -= HandleGlobalFXEvent;
    }

    private void HandleGlobalFXEvent(ScriptFXEvent ev)
    {
        if (ev.ScriptEventTag == "Footstep")
        {
            string material = ev.GetString("Material", "Grass");
            Vector3 worldPos = ev.ContextTarget != null ? ev.ContextTarget.transform.position : Vector3.zero;
            
            PlayFootstepSFX(material, worldPos);
        }
    }

    private void PlayFootstepSFX(string material, Vector3 position)
    {
        // Integration code...
        Debug.Log($"Playing footstep sound for: {material} at {position}");
    }
}

FX Overrides in Detail

1. Asset-Based Overrides

Exposed in the MSMotionFXRegistry ScriptableObject. Each override class corresponds to an event type and contains a series of boolean switches (OverrideX) and override value fields. At trigger time, the player evaluates these overrides:

• MSMotionAudioFXOverride: OverrideClip (AudioClip), OverrideVolume (float), OverridePitch (float), OverrideSpatialBlend (float), OverrideMinDistance (float), OverrideMaxDistance (float), OverrideStereoPan (float), OverrideLoop (bool).
• MSMotionParticleFXOverride: OverridePrefab (GameObject), OverrideScaleMultiplier (float), OverridePlayMode (ParticlePlayMode), OverrideEmitCount (int), OverrideAttachToBone (bool), OverrideWaitForCompletion (bool).
• MSMotionVFXGraphFXOverride: OverrideAsset (VisualEffectAsset), OverrideStopAtDurationEnd (bool), OverrideAttachToBone (bool).
• MSMotionTransformFXOverride: OverridePrefab (GameObject), OverrideMode (TransformFXMode), OverrideDrivePosition (bool), OverrideTargetLocalPosition (Vector3), OverrideDriveRotation (bool), OverrideTargetLocalEuler (Vector3), OverrideDriveScale (bool), OverrideTargetLocalScale (Vector3).
• MSMotionScriptFXOverride: OverrideMethodName (string), OverrideContextTargetMode (FXOverrideTargetMode), OverrideCustomContextBoneName (string), OverrideCustomContextHumanBone (HumanBodyBones), OverrideUseSendMessage (bool).
• MSMotionCameraShakeFXOverride: OverrideImpulseSourcePrefab (GameObject), OverrideAmplitude (float), OverrideFrequency (float), OverrideImpulseDirection (Vector3), OverrideUseCharacterForward (bool).
• MSMotionSpawnFXOverride: OverridePrefab (GameObject), OverrideDestroyOnEnd (bool), OverrideUsePool (bool), OverrideAttachToBone (bool).

2. Runtime Overrides

For high-performance, dynamic overrides at runtime, subclass one of the MSMotionBaseFXOverride classes. These act as value containers that bypass Registry searches. Assign them using MSMotionFXPlayer.SetRuntimeOverride(overrideContainer). They take absolute priority and never modify assets on disk.

Common Base Fields

All runtime override containers inherit from MSMotionBaseFXOverride and expose the following overrides:

• string EventId (Matches the authoring key)
• bool OverrideDuration / float Duration
• bool OverrideLoop / bool Loop
• bool OverrideBlendIn / float BlendIn
• bool OverrideBlendOut / float BlendOut
• bool OverrideTransformSpace / FXTransformSpace TransformSpace
• bool OverrideTargetBone / string TargetBone
• bool OverrideTargetHumanBone / HumanBodyBones TargetHumanBone
• bool OverrideLocalPosition / Vector3 LocalPosition
• bool OverrideLocalRotationEuler / Vector3 LocalRotationEuler
• bool OverrideLocalScale / Vector3 LocalScale
• List<FXPropertyOverrideDelta> PropertyDeltas (Granular overriding of specific dynamically targeted properties, methods, or fields)

Specialized Classes & Fields

• MSMotionAudioFXOverride: OverrideClip (AudioClip), OverrideVolume (float), OverridePitch (float), OverrideSpatialBlend (float), OverrideMinDistance (float), OverrideMaxDistance (float), OverrideStereoPan (float).
• MSMotionParticleFXOverride: OverridePrefab (GameObject), OverrideScaleMultiplier (float), OverridePlayMode (ParticlePlayMode), OverrideEmitCount (int), OverrideAttachToBone (bool), OverrideWaitForCompletion (bool).
• MSMotionVFXGraphFXOverride: OverrideAsset (VisualEffectAsset), OverrideStopAtDurationEnd (bool), OverrideAttachToBone (bool).
• MSMotionTransformFXOverride: OverridePrefab (GameObject), OverrideMode (TransformFXMode), OverrideDrivePosition (bool), OverrideTargetLocalPosition (Vector3), OverrideDriveRotation (bool), OverrideTargetLocalEuler (Vector3), OverrideDriveScale (bool), OverrideTargetLocalScale (Vector3).
• MSMotionScriptFXOverride: OverrideMethodName (string), OverrideContextTargetMode (FXOverrideTargetMode), OverrideCustomContextBoneName (string), OverrideCustomContextHumanBone (HumanBodyBones), OverrideUseSendMessage (bool).
• MSMotionCameraShakeFXOverride: OverrideImpulseSourcePrefab (GameObject), OverrideAmplitude (float), OverrideFrequency (float), OverrideImpulseDirection (Vector3), OverrideUseCharacterForward (bool).
• MSMotionSpawnFXOverride: OverridePrefab (GameObject), OverrideDestroyOnEnd (bool), OverrideUsePool (bool), OverrideAttachToBone (bool).

Programmatic Override Example

using UnityEngine;
using MaharajaStudio.MSMotion.Runtime;

public class DynamicEnvironmentFX : MonoBehaviour
{
    [SerializeField] private MSMotionFXPlayer _fxPlayer;
    [SerializeField] private AudioClip _underwaterFootstepAudio;

    public void EnterWaterVolume()
    {
        // Smoothly adjust all footstep SFX to play an underwater clip at a lower pitch
        var footstepOverride = new MSMotionAudioFXOverride
        {
            EventId = "Footstep_SFX",
            
            // Override base properties
            OverrideBlendOut = true,
            BlendOut = 0.5f, // longer fade-out in water

            // Override audio properties
            OverrideClip = true,
            Clip = _underwaterFootstepAudio,
            OverrideVolume = true,
            Volume = 0.8f,
            OverridePitch = true,
            Pitch = 0.7f, // deep, muffled sound
            
            // Override dynamic property (e.g., dryLevel parameter on AudioReverbFilter component)
            PropertyDeltas = new System.Collections.Generic.List<FXPropertyOverrideDelta>
            {
                new FXPropertyOverrideDelta
                {
                    TargetComponentTypeName = "AudioReverbFilter",
                    TargetPropertyName = "dryLevel",
                    OverrideSerializedValue = true,
                    SerializedValue = "-2000" // Lower dry level in water
                }
            }
        };

        _fxPlayer.SetRuntimeOverride(footstepOverride);
    }

    public void ExitWaterVolume()
    {
        _fxPlayer.ClearRuntimeOverride("Footstep_SFX");
    }
}

Transient Playback Overrides (Recommended)

You can pass custom overrides directly into the Animator's playback methods. These overrides will apply exclusively to the exact animation triggered, and will automatically be cleared when the animation finishes or is interrupted. This is the safest and cleanest way to alter FX without mutating your ScriptableObject configurations.

// Example: Play an animation but override its Footstep sound
var footstepOverride = new MSMotionAudioFXOverride {
    EventId = "Footstep", OverrideClip = true, Clip = waterStepClip 
};
_animator.Play(attackConfig, transientRuntimeOverrides: new[] { footstepOverride });

Override Priority Hierarchy

Because there are multiple ways to override FX events, MSMotion evaluates them in a strict top-down priority. The first override found in this list completely replaces all lower levels:

1. Transient Runtime Override: (MSMotionBaseFXOverride passed into Play()) - Highest priority, scopes to exact playback instance.
2. Global Runtime Override: (Set via FXPlayer.SetRuntimeOverride()) - Applies to all animations until manually cleared.
3. Transient Registry: (MSMotionFXRegistry passed into Play())
4. Config Registry: (FXRegistryOverride baked into the MSMotionAnimationConfig ScriptableObject)
5. Global Registry: (The MSMotionFXRegistry assigned directly to the MSMotionFXPlayer Inspector)
6. Manifest Default: (The base values authored in the Animation Window) - Lowest priority.

Speed Compensation & Speed Tracking

When a character's animation is slowed down (for example, in bullet-time or slow-motion), sustained effects like audio loops or particle emissions must adjust their lifetimes to match.

The FX Player supports two timing compensation modes:

1. Automatic speed tracking: Call _fxPlayer.SetAnimatorSpeedTracking(true). The component automatically reads the standard Animator.speed scale each LateUpdate and scales internal delta times accordingly.
2. Manual speed setting: Call _fxPlayer.SetPlaybackSpeed(float speed). Useful if you want the visual effects to run at a different speed than the skeletal animation.

MSMotionFXPlayer API Reference

MaharajaStudio.MSMotion.Runtime.MSMotionFXPlayer : MonoBehaviour

The runtime manager component that instantiates and schedules audio, visual, and script effects. Must reside on the same GameObject as the Unity Animator.

Events

• public event Action<ScriptFXEvent> OnScriptEvent;
  • Fired whenever a ScriptFXEvent is triggered on any active animation layer. Use this to bind gameplay logic handlers.

Dispatching & Controls

• public void SwitchManifest(MSMotionFXManifest manifest);: Switches the active default manifest. Stops all currently active sustained effects from the previous manifest and resets evaluation markers.
• public void PauseFX();: Suspends the dispatching of new FX events. Currently active sustained effects continue playing.
• public void ResumeFX();: Resumes scheduling and triggering new events.
• public void PauseActiveFX();: Pauses playback of all currently active sustained effects (pauses audio sources, visual effect graphs, and halts particle systems).
• public void ResumeActiveFX();: Resumes playback of all paused active sustained effects.
• public void StopAllFX();: Immediately terminates all active sustained effects, destroys temporary spawned objects, and returns pooled emitters/audio sources back to the MSMotionFXPool.

Active Status & Query API

• public bool IsFXPlaying(string eventId);: Returns true if any active sustained effect matching the specified eventId is currently playing.
• public int GetActiveFXCount();: Returns the total count of all active sustained effects currently playing on the character.
• public int GetActiveFXCount(string eventId);: Returns the count of active sustained effects specifically matching the given eventId.
• public void StopFX(string eventId);: Immediately halts all active sustained effects matching the specified eventId.
• public AudioSource GetActiveAudioSource(string eventId);: Retrieves the active AudioSource instance for the given event ID, or null if not playing.
• public ParticleSystem GetActiveParticleSystem(string eventId);: Retrieves the active ParticleSystem instance for the given event ID, or null if not playing.
• public UnityEngine.VFX.VisualEffect GetActiveVFX(string eventId);: Retrieves the active VisualEffect component for the given event ID (if VFX Graph is supported), or null if not playing.
• public Transform GetSpawnedObjectTransform(string eventId);: Retrieves the Transform of an active spawned object (VFX Graph, Particle, or spawned Prefab) matching the eventId.
• public GameObject GetSpawnedGameObject(string eventId);: Retrieves the exact spawned GameObject matching the eventId. Only applies to SpawnFX.
• public float GetFXElapsedTime(string eventId);: Returns the elapsed composition time in seconds for a specific sustained FX.
• public float GetFXRemainingTime(string eventId);: Returns the remaining time in seconds before a specific sustained FX automatically ends.
• public float GetLayerSpeed(int layerIndex);: Returns the exact playback speed configured for the specified layer.
• public void RebindBones();: Clears the internal cached bone lookups and layer avatar mask checks. Call this if the character's skeletal hierarchy is structurally modified at runtime.

Playback Speed Controls

• public void SetPlaybackSpeed(float speed);: Sets a manual speed scale multiplier applied to all sustained FX delta calculations. Disables automatic Animator speed tracking.
• public void SetAnimatorSpeedTracking(bool enable);: If true, the FX player automatically polls Animator.speed every frame and compensates sustained transitions, loops, and particle speeds accordingly.
• public float GetPlaybackSpeed();: Returns the current active speed multiplier applied to sustained effects.

Runtime Overrides API

• public void SetRuntimeOverride(MSMotionBaseFXOverride runtimeOverride);: Applies a dynamic, instance-specific runtime override container. This takes immediate precedence over global registries and manifest settings without mutating disk assets.
• public MSMotionBaseFXOverride GetRuntimeOverride(string eventId);: Retrieves the active runtime override container matching the eventId, if one is set.
• public void ClearRuntimeOverride(string eventId);: Removes the runtime override container for the specified event ID.
• public void ClearAllOverrides();: Removes all per-instance runtime overrides.

Optimization & Best Practices

MSMotion's runtime framework is designed from the ground up for high-performance execution, targeting 60+ FPS on console and mobile hardware. This guide details the architectural optimizations under the hood and outlines best practices for structuring your character systems.

Garbage Collection Mitigation

Garbage Collection (GC) spikes cause micro-stutters that ruin fluid action games. MSMotion eliminates runtime allocations using several techniques:

• Pre-Warmed Object Pooling (MSMotionFXPool): Pre-allocates pools of AudioSource and ParticleSystem game objects based on your Inspector settings, avoiding mid-combat Instantiate() and Destroy() calls.
• Allocation-Free Spline Evaluation: Spline trajectories used by particles and visual effects evaluate dynamically via the FXTrajectoryEvaluator using struct-based math arrays rather than heap allocations.
• Cached Data Structures: Traverses the skeleton hierarchy and caches bone lookups (_boneCache) and avatar mask checks (AvatarMaskCache) to prevent per-frame skeleton traversal.

Thread Safety & Asynchronous Playback

• PlayableGraph Evaluation: Unity evaluates the graph internally on worker threads using its native C++ job system. However, custom logic modifications (such as calling Play() or CrossFade()) must be called from the Main Thread.
• Async Fade and Transition Tasks: Driven by C# Awaitable tasks. To prevent memory leaks or abandoned tasks when an animation is interrupted, every layer has an active CancellationTokenSource that cancels the active task before starting a new blend.

Level-of-Detail (LOD) & Culling Strategies

• Distance Culling: Always add MSMotionStretchApplicator to characters using scale features. Set the farDistance threshold to a reasonable range. Once characters cross this threshold, bone scaling evaluation drops to 0.
• Update Skipping: Configure _midLODInterval on the applicator to skip frames for mid-distance characters (e.g., evaluate every 2nd or 3rd frame).
• Disable Off-Screen Applicators: The applicator utilizes Unity's OnBecameVisible() and OnBecameInvisible() callbacks to suspend curve evaluations entirely when a character is off-screen.

Best Practices for Combat & Locomotion Setups

1. Standard Layer Layout

Maintain a consistent layer scheme across all character configurations in your project:

2. Isolate Bones with Avatar Masks

• Always assign an AvatarMask to upper-body action clips (Layer 1) to exclude the hips and legs. This allows your character to move, run, and jump on Layer 0 while naturally executing attack swings on Layer 1.
• Leave full-body overrides (Layer 2) mask-less (or null) so the action takes absolute precedence over the skeletal pose.

3. Additive Blending for Overlays

• Use additive layers for small impact reaction clips. An additive hit-flinch animation can play on Layer 3 without interrupting an attack on Layer 1 or locomotion on Layer 0, blending on top of whatever pose the character is currently in.

Troubleshooting: Foot IK Forced on All Animations

The Issue

When using MSMotionAnimator, you might find that Unity's built-in Foot IK is being forcefully applied to every animation (like attacks, jumps, or rolls), even if you explicitly set ApplyFootIK = false on their MSMotionAnimationConfig. This can cause the character's feet to unexpectedly stick to the ground or snap into odd poses during mid-air animations.

The Cause

Unity's PlayableGraph has a hard limitation when blending legacy Animator Controllers with Playables: If your base layer (Layer 0) is driven by an Animator Controller, and the active state in that controller has "Foot IK" ticked, it will forcefully bubble up and evaluate Foot IK across the entire character.

Because MSMotion uses complex layered overrides, the base layer (your idle/walk/run locomotion) remains active at Weight 1.0 underneath the higher layers to prevent the character from squashing. As long as that base layer is requesting Foot IK, Unity's built-in IK solver will run for the final pose, completely ignoring the ApplyFootIK = false setting on your overriding MSMotion layers.

The Solutions

Troubleshooting: 1-3 Frame Rotation Glitches in Roll & Flip Animations

The Problem

When using extreme acrobatic animations where a Humanoid character goes completely upside down (e.g., forward rolls, backflips), you may notice the character's body visually spin backward or glitch for exactly 1 to 3 frames at the very apex of the flip.

This typically happens in the Composition Editor when Apply Root Motion is disabled for that clip, or when the clip is attached to a Trajectory.

The Cause

This is a known, fundamental limitation within Unity's core PlayableGraph and Humanoid Retargeting engine, not a bug within the MSMotion Animation Editor itself.

When a Humanoid character flips upside down (Pitch reaches 180 degrees), Unity's internal Center of Mass (CoM) extractor hits a mathematical singularity (Gimbal lock). To try and resolve it, Unity generates a massive sudden spike in the internal Root Motion curves and bakes the inverse of that spike into the character's hips.

If Root Motion is enabled, these two spikes cancel each other out perfectly. However, if Root Motion is disabled or redirected via a Trajectory, the character's root is locked in place, and the inverse spike baked into the hips is visually exposed—causing the sudden 3-frame flip glitch.

The Solution

Because this is a native Unity evaluation behavior, the MSMotion Editor cannot mathematically fix the curves at runtime without breaking other features.

To solve this, you must tell Unity to permanently bake the singularity into the animation asset's pose itself, bypassing the buggy Center of Mass extractor.

Step-by-Step Fix

Whenever you drag an animation into the MSMotion Composition Editor, the tool automatically creates a duplicate of that animation and stores it as a sub-asset inside your Composition Asset. You must modify this specific sub-asset.

Once these settings are applied, the animation will play and scrub flawlessly inside the Composition Editor, regardless of whether Root Motion is on, off, or following a Trajectory!

Troubleshooting Compositions

This guide covers common issues and questions when working with the Composition Editor in MSMotion.

1. Character "Jumps" or Snaps When Pressing Play

Issue

When scrubbing the timeline, the character is in one position, but the moment you press Play in the toolbar, the character jumps or shifts to another position in the scene.

Cause

This occurs due to a coordinate origin mismatch. When scrubbing, the editor uses the character's current scene position as the origin path for relative trajectories. When you press Play, if the coordinates haven't been locked, the preview graph may reset to a default origin, causing a sudden snap.

Solution

1. Position your preview character in the scene where you want it.
2. In the Composition Editor's top toolbar, click the Set Origin (avatar pivot) button.
3. This locks the current coordinates as the explicit origin for the Composition asset, ensuring scrubbing and playback align.

2. Character Gaps (Slipping into a T-Pose)

Issue

At certain times along the timeline, the character suddenly slips or blends into a static T-pose.

Cause

This happens when there is a timeline gap where no active animation is playing. If you fade out one clip block and have a gap before the next block begins, the layer's total weight drops to 0. If there is no active animation on lower layers either, the character falls back to their default binding T-pose.

Solution

• Use Hold Extrapolation: Select the preceding clip block and set its **Extrapolation Mode** to **Hold**. This freezes the final frame of the clip across the timeline gap until the next block starts playing.
• Add a Base Layer Loop: Ensure you have a bottom base layer (e.g. Layer 0) containing a looping idle animation block that plays continuously.

3. Script Events or Custom FX Do Not Fire in Editor Preview

Issue

You have placed Audio, Particle, or Script FX nodes on the timeline, but you cannot hear or see them when scrubbing the timeline in the editor.

Cause

• Mute Events Toggle: The global speaker icon on the toolbar is active.
• Safety Toggle Active: The safety toggle (FX indicator) is active, blocking script execution.
• Missing Target Bone: The target bone path is incorrect, or the character's hierarchy has changed.

Solution

1. In the top toolbar, ensure the **Mute Events (Speaker)** toggle is unclicked (not highlighted).
2. Ensure the **Safety Toggle (FX)** is clicked to allow editor execution of custom script overrides.
3. Verify the **Target Human Bone** or **Target Bone** path exists on the preview character. Use the **Try Rebind FX Nodes to Humanoid** utility if you switched character meshes.

4. Performance Spikes or Lag During Editor Playback

Issue

The Unity Editor suffers frame rate drops or lagging when playing or scrubbing a composition.

Cause

Procedural physics (Jiggle) or leg grounding solvers (Foot IK) are executing heavy physics calculations (like raycasts or mesh collisions) every frame in edit mode.

Solution

• Optimize Jiggle Colliders: If using Jiggle Physics, avoid enabling **Enable Self Collision** unless necessary. Self-collision on long bone chains (e.g. 15+ tail bones) is expensive.
• Restrict Raycast Masks: For **Foot IK**, ensure the **Raycast Mask** is set specifically to a simplified Terrain layer. Do not let Raycasts query complex character mesh colliders.
• Simplify Target Bone Paths: Reduce the number of targeted bones inside the Jiggle bone lists.

5. Visual Quality Discrepancies in Baked Clips (Clip Comparer)

Issue

After exporting a composition, you notice that the character's movement in the baked animation clip has subtle offset differences, or is missing specific motion curves compared to the live preview window.

Cause

This can happen due to curve optimization thresholds removing required keyframes, or due to channel filters (e.g. scale curves ignored on Generic exports or rotation modes not matching).

Solution

Use the Clip Comparer utility to run a direct comparison:

1. Open the Clip Comparer by choosing Tools > Maharaja Studio > MsMotion > Debug > Compare Animation Clips from the menu.
2. Assign the original source clip to the Original Clip (A) slot.
3. Assign the newly baked output clip to the Exported Clip (B) slot.
4. Click Compare Clips.
5. The comparer will compare curves at keyframes and write a detailed log mapping missing curves, extra curves, and floating-point value differences.
6. The comparison log will be saved to your project folder at Assets/ClipComparisonLog.txt. Review this file to pinpoint which bones or properties were optimized out, and adjust your **Tangent Modes**, **Precision decimal places**, or **Keyframe Optimization Tolerances** accordingly.

Troubleshooting: Animation Editor

This guide addresses common issues encountered when using the Animation Editor and provides steps to resolve them.

1. "Cannot edit keys: The clip is read-only..."

• Symptoms: Red error warning in the status area; keyframe fields are locked; transforms in the Scene view snap back instantly.
• Cause: The loaded animation clip is embedded inside an imported 3D model file (such as .fbx), which Unity treats as write-protected.
• Solution: In the sidebar's Clip panel, click Extract Editable Copy. This will duplicate the animation into a writeable .anim file and load it automatically.

2. Character does not update when dragging the playhead

• Symptoms: Scrubbing the timeline ruler has no visual effect on your model in the Scene view.
• Cause: The Preview Root field is empty, or the character model's bones do not match the animation curve paths.
• Solution:
  1. Verify that your character GameObject is assigned to the Preview Root field in the top toolbar.
  2. Ensure the character has an active Animator component.
  3. If using Generic (non-humanoid) animations, check that the bone names and hierarchy paths in the clip match your character's bone names exactly.

3. Skeletons and bone lines do not render in the Scene view

• Symptoms: The character model is visible, but the colored bone lines, shapes, and name tags do not draw.
• Cause: The bone overlay toggle is disabled, or Unity's scene gizmos are turned off.
• Solution:
  1. In the sidebar's Viewport panel, check that Show Bones is toggled on.
  2. If Animated Bones Only is enabled, check that your loaded animation clip actually contains keyframes for the model's joints.
  3. Ensure that Gizmos are enabled in the top toolbar of the Unity Scene view.

4. IK target handles do not appear in the Scene view

• Symptoms: You cannot see the circle or line handles to grab and pose limbs, even though you have a character loaded.
• Cause: No IK rig config is assigned, or the IK Solver panel is disabled.
• Solution:
  1. Expand the IK / FK Solver section in the sidebar.
  2. Verify that your character has a valid IK rig configuration assigned.
  3. Make sure you are in a perspective or orthographic Scene view (not the Game view).

5. Transforming bones does not record keyframes

• Symptoms: You rotate or move bones in the Scene view, but no keyframe markers appear on the timeline.
• Cause: Auto-Key is disabled, or the modified bone is outside the Preview Root hierarchy.
• Solution:
  1. Check that the Auto-Key toggle is active (highlighted) in the top toolbar.
  2. Verify that the bone transform you are modifying is a child of the GameObject assigned to the Preview Root field.
  3. Make sure the playhead is sitting on the frame where you want to record the key before you move the bone.

6. Posing a bone on one frame shifts the animation across all frames

• Symptoms: When you rotate a bone, instead of writing a keyframe on the active frame, the entire animation path for that bone shifts by that offset.
• Cause: Offset Mode is enabled in the top toolbar.
• Solution: Toggle Offset Mode off to return to standard single-frame keyframe recording.