UMA

Export

Use the UMA integration when an avatar assembled by UMA must move, animate, use Items, and interact as an Ultimate Character Controller Version 3 character.

Choose the edit-time Bone Builder workflow for a character that you want to finish with the Ultimate Character Controller managers. Choose UMA Character Builder only when UMA must create the avatar in Play Mode and the project can perform any additional setup after creation.

Compatibility boundary

The current Opsive documentation declares UMA 2.8+ as the minimum. The packaged UMA.unitypackage inspected for this page was updated in the Ultimate Character Controller Version 3 repository on August 20, 2025, but it contains no version Inspector or tested maximum-version declaration.

UMA now also has a separate 3.x release line. The checked-in Opsive package predates that release line, so this page does not claim UMA 3 compatibility. Confirm compilation and both workflows with the exact UMA and Ultimate Character Controller packages in the project before upgrading either product. The imported bridge source and its download notes take precedence if the supported boundary changes.

The integration is a plain Unity package, not an Integration Inspector. After UMA and Ultimate Character Controller compile, sign in to Opsive Downloads and download the UMA integration. It is not included in the base product’s Integrations folder before download. Its current source-visible components are UMA Character Builder, UMA Ability Builder, UMA Item Pickup, and UMA First Person Base Object.

Choose a setup workflow

Workflow	Choose it when	Important consequence
Bone Builder	The character can exist in the editor before Play Mode and needs normal Ultimate Character Controller manager setup.	UMA generates the bones first; the Ultimate Character Controller Character and Item Managers can then configure the character like another humanoid model. This is the recommended route for Items, detailed abilities, ragdoll, and inspector-driven customization.
UMA Character Builder	The avatar must be generated from an UMA recipe at runtime.	The bridge creates a new Ultimate Character Controller root after UMA raises `CharacterCreated`. Setup is intentionally limited to the fields exposed by the runtime builder, so project code usually completes advanced configuration.

Do not combine the workflows on the same avatar. UMA Character Builder exits when the generated UMA GameObject already contains Ultimate Character Locomotion.

Before you begin

Install UMA first, then Ultimate Character Controller Version 3, and resolve all compiler errors before importing the bridge.
Run the Ultimate Character Controller Layer Manager so the Character, SubCharacter, Overlay, and related layers exist.
Use a humanoid UMA avatar with a valid Avatar and an Ultimate Character Controller Animator Controller. Runtime Item slots and collider positioning depend on Unity’s humanoid Head, Hips, and Hand bones.
Create the Ultimate Character Controller Item Collection and Item Set Rule assets before enabling runtime Item support.
Place and configure an Ultimate Character Controller Camera Controller before relying on Assign Camera. The UMA bridge assigns an existing camera; it does not create one.
Save the scene and create a source-control checkpoint before changing the UMA avatar hierarchy or converting an existing character.

Install the integration

Download the UMA integration from Opsive Downloads.
Import the downloaded package after both UMA and Ultimate Character Controller compile. Importing it creates Assets/Opsive/UltimateCharacterController/Integrations/UMA in the project.
Remove an older copy of Assets/Opsive/UltimateCharacterController/Integrations/UMA before importing a replacement package.
In Add Component, confirm that UMA Character Builder, UMA Ability Builder, UMA Item Pickup, and UMA First Person Base Object are available.
Reopen the Console and resolve missing UMA or Ultimate Character Controller types before configuring a character.

There is no UMA Integration Inspector or setup wizard in this package. Importing the Unity package is the complete installation step.

Build an editor-configured character

Use Bone Builder when the generated skeleton can be prepared in the editor.

Place the UMA Dynamic Character Avatar prefab in the scene.
Open UMA’s Bone Builder from the UMA toolbar.
Assign the scene avatar to UMA GameObject and select Generate Bones.
Open Tools > Opsive > Ultimate Character Controller > Character Manager and build the character with the generated UMA model.
Select the child that contains Dynamic Character Avatar.
In Dynamic Character Avatar, set Additional Utility Recipes to an empty list.
Under Race Animation Controllers, assign the Ultimate Character Controller controller to Default Animator Controller.
Under Advanced Options, enable Keep Avatar and Keep Animator Controller, then assign the same controller to Animation Controller.
On the child’s Animator, assign the same asset to Controller.
Finish the character through the Ultimate Character Controller Character and Item Managers, then save the configured prefab or scene object.

Dynamic Character Avatar configured with no additional utility recipes, the Demo controller, Keep Avatar, Keep Animator Controller, and the matching Animator Controller.

The three controller references must agree. Otherwise UMA can replace the controller after Ultimate Character Controller has configured the Animator, leaving the character visible but unable to drive the expected Ultimate Character Controller parameters.

Build a character at runtime

Use this workflow when the avatar does not exist in its final form until UMA finishes generation.

Place the UMA Dynamic Character Avatar prefab in the scene.
Apply the same Additional Utility Recipes, Default Animator Controller, Keep Avatar, Keep Animator Controller, Animation Controller, and Animator > Controller settings used by the Bone Builder workflow.
Add UMA Character Builder to the same GameObject as Dynamic Character Avatar.
Enable Add First Person Perspective, Add Third Person Perspective, or both. Keep only movement types installed by the project’s Ultimate Character Controller perspective packages.
Assign the Ultimate Character Controller Animator Controller.
Enable Add Items only when Item Collection and Item Set Rule reference project assets intended for this character.
Choose whether the builder should add Health, Unity IK, Foot Effects, and Standard Abilities.
For an AI character, enable AI Agent and optionally Add Nav Mesh Agent. For a player, leave AI Agent disabled.
If both perspectives are enabled, choose Start First Person Perspective.
Enable Assign Camera only for a player that should take ownership of the existing Ultimate Character Controller Camera Controller.
Add a listener to Character Created for setup that must use the newly created Ultimate Character Controller root.

UMA Character Builder configured for first- and third-person movement, Items, health, Unity IK, foot effects, standard abilities, camera assignment, and a Character Created event.

When UMA raises DynamicCharacterAvatar.CharacterCreated, the bridge:

removes a Capsule Collider directly on the generated avatar because Ultimate Character Controller creates its own collider structure;
creates a new GameObject at the avatar’s position and rotation;
reparents the UMA-generated avatar beneath that new object;
uses Ultimate Character Controller’s runtime Character Builder to add locomotion, movement types, the Animator Monitor, colliders, optional systems, and input or AI support;
assigns an existing Camera Controller when requested; and
invokes Character Created, then destroys UMA Character Builder.

The object supplied to Character Created is the new Ultimate Character Controller root. Scene, save, camera, networking, and gameplay references that still point to the original Dynamic Character Avatar point to the model child rather than the controllable character.

Choose runtime options

Perspectives and movement types

First Person Movement Type and Third Person Movement Type are fully qualified class-name strings. The packaged defaults are:

Opsive.UltimateCharacterController.FirstPersonController.Character.MovementTypes.Combat
Opsive.UltimateCharacterController.ThirdPersonController.Character.MovementTypes.Adventure

First Person Hidden Object Names contains paths relative to the generated UMA model, such as Head. Ultimate Character Controller marks the resolved objects as third-person objects. Assign Invisible Shadow Castor Material when the first-person body should cast a shadow while its renderers are hidden.

Items

With Add Items enabled, the runtime builder adds Ultimate Character Controller Inventory, Item Set Manager, Item Placement, the standard Item abilities, and Character Item Slots on the humanoid hands. It then initializes the Animator Monitor’s Item parameters.

The builder does not create Character Item prefabs, Item Categories, or project-specific Item Sets. Prepare those assets separately. Use UMA Item Pickup only when one or more existing Ultimate Character Controller Item Pickup objects should grant their Items after creation.

Abilities, health, IK, and foot effects

Add Standard Abilities adds Jump, Fall, Move Towards, Speed Change, and Height Change. It does not add every included ability and it does not create a Ragdoll setup.

UMA Ability Builder can add additional ability types by class-name string after the character is created, but it does not configure their fields. Treat it as a starting point for a project-specific builder rather than a substitute for the Character Manager.

Add Health adds the Character Attribute Manager, Character Health, and Character Respawner. Add Unity IK adds Character IK, and Add Foot Effects adds Character Foot Effects. Verify all bone-dependent behavior after UMA has produced the final skeleton.

Player input, AI, and camera

The current UMA Character Builder custom Inspector does not expose its serialized Add Input System choice or an Input Actions field. Its default player path therefore builds the legacy Unity Input component. A project that uses Unity’s Input System or another input integration should prefer Bone Builder or replace and configure input from Character Created, then verify Player Input Proxy. See Input.

An AI build adds the local look source, removes player input handlers, and can add Nav Mesh Agent Movement. Assign Camera is skipped for AI agents. For a player, it only assigns an Ultimate Character Controller Camera Controller that CameraUtility can already find.

Add generated first-person arms

The runtime bridge can use another UMA avatar as a generated first-person base object:

Place a second Dynamic Character Avatar in the scene for the arms or first-person body.
Add UMA First Person Base Object to it.
Set Local Position, Local Rotation, and its Animator Controller.
Add child paths to Item Slot Locations for each hand or other Item attachment point.
Add that component to the main UMA Character Builder > First Person Base Objects list.

After both avatars are ready, the component moves the first-person avatar beneath Ultimate Character Controller’s First Person Objects root, assigns the Overlay layer, gives it a unique First Person Base Object ID, adds an Animator and Child Animator Monitor when configured, and creates Character Item Slots at the resolved paths. It then destroys itself.

Use First Person Arms for the Ultimate Character Controller Animator and Item requirements. A generic arms recipe is valid, but it still needs the expected humanoid animation and Item attachment structure.

Handle later UMA avatar changes

The packaged bridge is an initial-construction bridge, not a continuous avatar-update adapter. UMA Character Builder, UMA Ability Builder, UMA Item Pickup, and UMA First Person Base Object each destroy themselves after their one-time work.

Wardrobe or material changes are safe only when they preserve the Ultimate Character Controller root, Animator, required humanoid bones, Item Slot paths, and collider references. A later UMA race or recipe rebuild that replaces the Animator or skeleton is not automatically rebound to Animator Monitor, Character IK, Character Foot Effects, collider positioning, Character Item Slots, or first-person objects.

For a project that rebuilds those objects after initial creation, listen to the appropriate UMA update event in project code and revalidate or rebind every affected Ultimate Character Controller component. Do not call the one-shot builder repeatedly on an existing Ultimate Character Controller character.

Save and network runtime avatars

The package contains no UMA recipe saver, Ultimate Character Controller save orchestration, network authority, or replication code.

Save the UMA recipe or avatar identity with UMA’s supported workflow and save Ultimate Character Controller gameplay state with the project’s chosen save system.
During loading, recreate the UMA avatar, wait for Character Created, capture the new Ultimate Character Controller root, and only then restore Ultimate Character Controller state that depends on locomotion, Items, or abilities.
For networking, create or assign the network identity and ownership against the new Ultimate Character Controller root after the event. Replicate the recipe and gameplay state through the selected networking solution.
Do not use the original Dynamic Character Avatar reference as the persistent Ultimate Character Controller character reference after runtime construction.

Editor checkpoint

Before entering Play Mode, confirm that:

UMA, Ultimate Character Controller, and the imported bridge compile without errors;
the project uses either Bone Builder or UMA Character Builder for this avatar, not both;
Dynamic Character Avatar keeps the Ultimate Character Controller Avatar and Animator Controller;
its UMA and Animator controller fields reference the same Ultimate Character Controller Animator Controller;
runtime movement-type strings resolve to installed Ultimate Character Controller classes;
Item Collection and Item Set Rule are assigned when Add Items is enabled;
the player or AI choice matches the planned input and camera ownership;
a Unity Input System or third-party input project has an explicit post-build input plan;
Character Created captures the new Ultimate Character Controller root for dependent systems;
the scene has the required Ultimate Character Controller layers and an existing Camera Controller when Assign Camera is enabled; and
ragdoll, save, networking, and later UMA skeleton rebuilds have project-specific handling when required.

Verify in Play Mode

Enter Play Mode and wait for UMA to finish. Confirm that one new parent object contains Ultimate Character Locomotion and that the generated UMA avatar is its model child.
Confirm that the Ultimate Character Controller root has one intended Rigidbody and collider hierarchy. The model should not retain a competing root Capsule Collider.
Move and rotate the player, or drive the AI. Confirm that the expected movement type is active and the Animator uses the Ultimate Character Controller controller.
Confirm that the camera follows the new root for a player and remains unassigned for an AI agent.
If Items are enabled, equip and use one Character Item. Confirm that hand slots, Item Sets, Item abilities, and Animator parameters update.
If both perspectives are enabled, switch perspectives. Confirm that the hidden model paths, shadow material, first-person base object, and Item Slots behave correctly.
Damage and respawn a character when Add Health is enabled. Test ragdoll only after a separate ragdoll setup has been added.
Change the UMA wardrobe and then perform any supported avatar rebuild. Confirm that the Animator, IK, feet, collider, and Items still reference valid objects.
Save and reload or spawn through the networking layer. Confirm that dependent systems use the new Ultimate Character Controller root returned by Character Created.

Troubleshooting

Symptom	Check	Fix
The bridge does not compile	Import order, duplicate old bridge files, and the exact UMA/Ultimate Character Controller versions	Install UMA and Ultimate Character Controller first, remove the previous `Integrations/UMA` folder, then import the matching bridge. Do not assume the unverified UMA 3 boundary.
Bone Builder creates bones but Ultimate Character Controller animation does not run	Default Animator Controller, Animation Controller, Keep Avatar, Keep Animator Controller, and Animator > Controller	Assign the same Ultimate Character Controller controller in all three locations and enable both keep options.
UMA reports a hierarchy-name conflict	Duplicate generated and Ultimate Character Controller Item placement object names	Rename only the conflicting Item placement objects to unique names such as `RightItems` and `LeftItems`, then update any paths or references that used the old names.
No runtime Ultimate Character Controller character is created	UMA Character Builder location, the UMA `CharacterCreated` event, and an existing Ultimate Character Locomotion on the generated object	Put the builder on the same Dynamic Character Avatar, remove a competing prebuilt Ultimate Character Controller setup, and confirm UMA completes generation once.
Another system still controls the model child	Its character reference was captured before runtime construction	Subscribe to Character Created and replace the reference with the event’s new Ultimate Character Controller root.
A movement type cannot be found	Fully qualified class name and installed first- or third-person package	Use an exact current Ultimate Character Controller Version 3 type name or choose the Bone Builder workflow and configure it with Character Manager.
The player uses the wrong input backend	The runtime Inspector does not expose the current Input System setup fields	Replace and configure input after Character Created, including Player Input Proxy, or use Bone Builder. Do not leave competing player-input components active.
The camera remains on the previous target	AI Agent, Assign Camera, and whether an Ultimate Character Controller Camera Controller exists	Disable AI for a player, create/configure the camera first, or assign its Character from Character Created.
Item slots or first-person arms are missing	Humanoid hand bones, Add Items, First Person Base Objects, and exact child paths	Use a valid humanoid Avatar, assign Item assets, and correct the first-person Item Slot paths.
IK, footsteps, Items, or colliders fail after changing race	UMA may have replaced bones or the Animator after the one-shot bridge finished	Preserve the skeleton where possible or rebind the affected Ultimate Character Controller components from a project-specific UMA update listener.
Ragdoll is absent	The runtime builder has no Ragdoll option	Use Bone Builder and the normal Ultimate Character Controller ragdoll workflow, or implement and verify a project-specific post-build setup.
Loading or networking targets the wrong GameObject	Saved or replicated identity points to the original Dynamic Character Avatar	Wait for Character Created, then restore or bind state to the returned Ultimate Character Controller root.

Developer reference

The packaged source is under Assets/Opsive/UltimateCharacterController/Integrations/UMA:

UMACharacterBuilder listens to DynamicCharacterAvatar.CharacterCreated, creates the new Ultimate Character Controller root, calls Ultimate Character Controller’s runtime CharacterBuilder, invokes its own event, and destroys itself.
UMAAbilityBuilder resolves each Ability Types entry with TypeUtility.GetType, adds the ability, and destroys itself.
UMAItemPickup calls each assigned Ultimate Character Controller ItemPickup.DoItemPickup against the newly created Inventory and destroys itself.
UMAFirstPersonBaseObject waits for its UMA object and the Ultimate Character Controller First Person Objects root, creates the first-person identifiers and Item Slots, and destroys itself.

Character Created is a UnityEvent<GameObject, UMAData>. The GameObject argument is the new Ultimate Character Controller root; UMAData describes the generated model. Use this event as the synchronization point for custom abilities, input replacement, save restoration, network ownership, camera assignment, and references held by other gameplay systems.

UMA