UMotion API

The UMotion API is a simple and easy-to-use API that provides a basic interface for custom scripts to interact with UMotion.

In order to implement custom constraints or 3rd party IK solutions, please take a look at the UMotion Callback System instead.

Preparation

To access the UMotion API in one of your scripts, make sure that the script is placed inside an "Editor" folder. Add the following using statement to get access to the UMotion namespace: using UMotionEditor.API;

There are two classes within this namespace:

• ClipEditor
• PoseEditor

ClipEditor Overview

Properties

• static bool IsWindowOpened
  True when the Clip Editor window is opened and initialized. It might be necessary to focus either the Clip Editor or the Pose Editor window in order to initialize UMotion.
• static bool IsProjectLoaded
  True when the Clip Editor window has a UMotion project loaded.

Methods

• static void AddMenuItem(ClipEditor.MenuCategory category, string name, GenericMenu.MenuFunction clickedAction)
  Adds a new menu item to the clip editor's "File", "Edit" or "Help" menu. When the menu item is clicked, the clickedAction method is called.
  
  Example usage (place this script in a folder named "Editor"):

  using UnityEngine;
  using UnityEditor;
  using UMotionEditor.API;
  
  [InitializeOnLoad]
  public class UMotionExtensions
  {
     static UMotionExtensions()
     {
     ClipEditor.AddMenuItem(ClipEditor.MenuCategory.File, "My Menu Item", MyMenuItemPressed);
     }
     
     private static void MyMenuItemPressed()
     {
        Debug.Log("My menu item was pressed!");
     }
  }

• static void OpenWindow()
  Opens the UMotion Clip Editor window. If the window is already opened but hidden by another window, it is brought to the front. It takes at least one frame (or more) until the window is initialized.
• static void LoadProject(string path)
  Loads a UMotion project. The Clip Editor needs to be open in order for this method to succeed. This method can also be used to switch from one loaded project to another. The path must be relative to the Unity project directory (e.g. "Assets/umotion_project.asset").
• static void CloseProject()
  Closes a loaded UMotion project.
• static string GetLoadedProjectPath()
  Get the path to the currently loaded UMotion project. The path is relative to the Unity project directory. Returns null if no project is currently loaded.
• static string[] GetAllClipNames()
  Returns the names of all animation clips in the currently loaded UMotion project. A UMotion project must be loaded.
• static string GetSelectedClipName()
  Returns the name of the currently selected animation clip in the Clip Editor.
• static void SelectClip(string name)
  Selects (opens) the clip in the clip editor. The clip must already exist in the current UMotion project.
• static void SetClipName(string oldName, string newName)
  Changes the name of an animation clip. When called right before "ExportCurrentClip()" this method can be used to change the name of the exported animation clip. This is useful when exporting the same animation clip several times (with different animation layers enabled).
• static void DeleteClip(string name)
  Deletes the clip with the given name from the UMotion project.
• static void ExportCurrentClip()
  Exports the clip currently opened in the Clip Editor. This method blocks until the export is finished.
• static void ExportAllClips()
  Exports all clips of the current loaded UMotion project. This method blocks until the export is finished.
• static string[] GetClipLayerNames()
  Returns an array that holds the names of all animation layers of the currently opened animation clip. The base layer is not included.
• static void SetClipLayerName(string oldName, string newName)
  Changes the name of an animaton layer of the currently opened animation clip.
• static void GetClipLayerBlendProperties(string layerName, out bool mute, out float blendWeight)
  Gets the blend properties (mute and blend weight 0-1) of the layer with the given name.
• static void SetClipLayerBlendProperties(string layerName, bool mute, float blendWeight)
  Sets the blend properties (mute and blend weight 0-1) of the layer with the given layer name. This method is useful for exporting an animation clip several times with different layers muted/unmuted.
• static int GetFrameCursorPosition()
  Returns the current position of the frame cursor (in frames).
• static void SetFrameCursorPosition(int frame, string undoName)
  Sets the current frame cursor position. There are situations in which setting the frame cursor is not possible (e.g. when in config mode), in that case this method does nothing. If undoName is null, the performed action is not added to the undo stack.
• static float GetPlaybackFramePosition()
  Returns the current frame position during playback or -1.0 if playback is not active.
• static float GetLastKeyFrame()
  Returns the last frame number of the current clip where at least one key is present.
• static float ImportClips(IEnumerable<AnimationClip> animationClips, ClipEditor.ImportClipSettings importClipSettings)
  Starts the UMotion clip importer. Imports the passed animation clips with the passed settings. In order to import clips from FBX files, use the Unity AssetDatabase API to get the required references to the FBX file's animation clips.

enum ClipEditor.MenuCategory

• File
  File menu of the clip editor.
• Edit
  Edit menu of the clip editor.
• Help
  Help menu of the clip editor.

struct ClipEditor.ImportClipSettings

• bool ConvertToProgressive
• bool DisableAnimCompression
• bool DisableAnimCompression
• bool FkToIkConversion
• bool FkToIkDeleteFkKeys
• bool HumanoidHandIKEnable
• bool HumanoidLosslessKeyframeReduction
• static ClipEditor.ImportClipSettings Default
  Default settings

Please check out the clip import dialog documentation for a detailed description of each of these settings.

PoseEditor Overview

Properties

• static bool IsWindowOpened
  True when the Pose Editor window is opened and initialized. It might be necessary to focus either the Pose Editor or the Clip Editor window in order to initialize UMotion.
• static GameObject AnimatedPreviewGameObject
  When a GameObject is assigned to the UMotion pose editor, it is duplicated and the original GameObject gets hidden. All modifications done to the pose are only applied to the duplicated GameObject. As soon as "Clear" is pressed in the pose editor, the duplicated GameObject gets destroyed and the original GameObject gets visible again. This ensures that changes done to the pose are only kept within the UMotion editing session and do not influence the "real" GameObject in the scene.
  This proprety returns the duplicated GameObject or null if there is currently no GameObject assigned to the pose editor.
• static PoseEditor.PivotMode Pivot
  Gets or sets the current pivot mode of the pose editor (local/global).

Methods

• static void AddButton(PoseEditor.FoldoutCategory category, string name, string tooltip, System.Action buttonPressedAction)
  Adds a button with the given name to a foldout in the pose editor. Them method supplied for "buttonPressedAction" is called as soon as the button is pressed. The tooltip string is shown when the user hovers the mouse over the button. Use it to provide helpful information.
  
  Example usage (place this script in a folder named "Editor"):

  using UnityEngine;
  using UnityEditor;
  using UMotionEditor.API;
  
  [InitializeOnLoad]
  public class UMotionExtensions
  {
     static UMotionExtensions()
     {
        PoseEditor.AddButton(PoseEditor.FoldoutCategory.Tools, "My Button", "This is shown as tooltip.", MyButtonPressed);
     }
     
     private static void MyButtonPressed()
     {
        Debug.Log("Button was pressed!");
     }
  }

• static void OpenWindow()
  Opens the UMotion Pose Editor window. If the window is already opened but hidden by another window, it is brought to the front. It takes at least one frame (or more) until the window is initialized.
• static void SetAnimatedGameObject(GameObject gameObject)
  Applies a GameObject (from the current Unity scene) to the Pose Editor. A UMotion project already needs to be loaded.
• static void ClearAnimatedGameObject(PoseEditor.ClearMode clearMode = PoseEditor.ClearMode.RevertChanges)
  Removes a GameObject from the Pose Editor. By default, the GameObject is reverted to the pose that it had before it has been assigned to UMotion.
• static void GetAllTransforms(List<Transform> transformsList)
  Fills the list with all bones/transforms of the current animated GameObject.
• static void GetSelectedTransforms(List<Transform> transformsList)
  Clears the provided list and then adds every transfrom currently selected in UMotion.
• static int GetTransformChildCount(Transform transform)
  Returns the number of child bones/transforms of the given transform. This includes custom transforms that only exist within UMotion's pose editing time.
• static Transform GetTransformChildAt(Transform transform, int index)
  Returns the child bone/transform with the given index.
• static void SetTransformIsSelected(Transform transform, bool selected)
  Selects or deselects the transform based on the "selected" value.
• static bool GetTransformIsSelected(Transform transform)
  Returns true if the passed transform is currently selected.
• static void GetMirrorTable(List<Transform> leftHandSideList, List<Transform> rightHandSideList)
  Returns the mirror table.
• static bool TrySetFkLocalPosition(Transform transform, Vector3 localPosition, string undoMessage, bool createKey)
  Updates the local postion of the passed transform. The transform must be a child of the currently animated GameObject. This method returns false if the local position of the transform is not "write-able" (e.g. because it's visibility is set to "locked" in config mode). If undoName is null, the performed action is not added to the undo stack. If createKey is set to true, a key frame is created at the current frame cursor position. The key frame creation action is always added to the undo stack.
  This method throws an exception if called from within a UMotion callback because adjusting the current FK pose while updating the current pose would result in an endless loop.
• static bool TrySetFkWorldPosition(Transform transform, Vector3 worldPosition, string undoMessage, bool createKey)
  Same as TrySetFkLocalPosition() but sets the world space position.
• static bool TrySetFkLocalRotation(Transform transform, Quaternion localRotation, string undoMessage, bool createKey)
  Same as TrySetFkLocalPosition() but sets the local rotation.
• static bool TrySetFkWorldRotation(Transform transform, Quaternion worldRotation, string undoMessage, bool createKey)
  Same as TrySetFkLocalPosition() but sets the world space rotation.
• static bool TrySetFkLocalScale(Transform transform, Vector3 localScale, string undoMessage, bool createKey)
  Same as TrySetFkLocalPosition() but sets the local scale.
• static void GetCustomPropertyConstraintNames(Transform transform, List<string> constraintNamesList)
  Returns a list of all custom property constraints of the passed bone/transform.
• static bool TrySetCustomPropertyConstraintValue(Transform transform, int customPropertyConstraintIndex, float value, string undoMessage, bool createKey)
  Updates the current value of the custom property constraint at the passed index. The index is the same as the index the constraint has in the list returned by "GetCustomPropertyConstraintNames()". Other than that the method acts the same as TrySetFkLocalPosition().
• static void CopyToOtherSide(Transform transform, bool position, bool rotation)
  Copies the current position and/or rotation of the passed bone/transform to it's sibling on the other side.

enum PoseEditor.FoldoutCategory

• Tools
  Tools foldout of the pose editor.
• Animation
  Animation foldout of the pose editor.
• Selection
  Selection foldout of the pose editor.
• Display
  Display foldout of the pose editor.

enum PoseEditor.ClearMode

• RevertChanges
  Restores the original pose of the GameObject before it was assigned to the UMotion Pose Editor.
• KeepChanges
  Keeps the current pose of the GameObject.

enum PoseEditor.PoseMode

• Local
  Local space pivot mode.
• Global
  World space pivot mode.