Component Overview

Export

Use this overview to identify which Ultimate Character Controller component owns a behavior before changing the Inspector or writing custom code.

UCC separates the character motor, control source, camera, animation, items, traits, and scene services. Most projects should let the supplied managers build these relationships instead of adding individual components by hand.

Build the component structure

  1. Open Tools > Opsive > Ultimate Character Controller > Setup Manager.
  2. On the Project tab, configure the required layers and the input or render-pipeline settings used by the project.
  3. On the Scene tab, select Add Managers under Manager Setup.
  4. Under Camera Setup, choose the Perspective and matching View Type, then select Setup Camera.
  5. Open Tools > Opsive > Ultimate Character Controller > Character Manager.
  6. Assign the Character, choose its Perspective and movement type, and assign an Animator Controller when the character uses animation.
  7. Enable only the optional groups the character needs: Standard Abilities, AI Agent, NavMeshAgent, Items, Health, Unity IK, Foot Effects, and Ragdoll.
  8. Select Build Character for a new character or Update Character for an existing one.

The Character Manager configures component dependencies, the kinematic Rigidbody, collider hierarchy, layers, input route, abilities, and model-level components together. Use the Inspector afterward to tune the generated setup.

Understand the component groups

Area Main components Responsibility and relationship
Scene services Surface Manager, Decal Manager, Simulation Manager, Object Pool, Scheduler, Audio Manager, Spawn Point Manager, State Manager, and Layer Manager Add Managers places these services on the scene’s Game object. Features use them for simulation, pooling, delayed work, audio, spawning, states, surfaces, and layer setup.
Character motor Ultimate Character Locomotion, Character Layer Manager, a kinematic Rigidbody, and supported colliders Ultimate Character Locomotion handles movement, collision detection, slopes, stairs, gravity direction, root motion, variable time scale, and moving platforms. It also owns the configured Movement Types, Abilities, Item Abilities, and Effects.
Player control A Player Input implementation, Ultimate Character Locomotion Handler, and, when items are enabled, Item Handler The input implementation reads the device. The character handlers translate that input into movement, ability input, and equipped-item movement.
AI control Local Look Source plus the chosen AI or navigation integration An AI character does not use the player input components or Ultimate Character Locomotion Handler. The NavMeshAgent option adds the NavMesh Agent Movement ability for Unity navigation; it does not create decision-making AI.
Models and animation Unity Animator and Animator Monitor; optionally Model Manager and Perspective Monitor Animator Monitor is the bridge between UCC runtime values and Animator parameters. Model Manager coordinates multiple character models. Perspective Monitor supports a character that switches between first and third person presentation.
Camera Camera Controller, Camera Controller Handler, and one or more View Types; optionally Object Fader Camera Controller follows the assigned Character and delegates framing and rotation to the active View Type. Camera Controller Handler reads player camera input. Setup Camera adds Object Fader for a third-person-capable camera.
Character items Inventory, Item Set Manager, Item Handler, Item Placement, and Item Abilities on Ultimate Character Locomotion Inventory tracks item identifier amounts. Item Set Manager decides which Character Items can occupy the configured slots and categories. Item Handler is omitted for AI characters.
Item behavior Character Item, perspective-item components, and one or more Character Item Action components Character Item identifies and coordinates an equippable object. Shootable Action, Melee Action, Shield Action, and other actions divide their behavior into replaceable module groups. A single Character Item can contain multiple actions.
Attributes and health Character Attribute Manager, Character Health, and Character Respawner Character Attribute Manager stores values such as Health, Shield, or Stamina. Character Health reads the named health and shield attributes and adds character-specific damage behavior. Character Respawner handles the character lifecycle after death.
Character presentation Character IK, Character Foot Effects, the Surface System, and the Ragdoll ability Character IK adjusts humanoid limbs and look direction. Character Foot Effects detects steps and asks the Surface System to play the matching audio, decal, or spawned effect. Ragdoll adds its ability and humanoid ragdoll colliders. These features are optional.

Choose the right extension point

  • To change how directional input becomes motion and rotation, configure or create a Movement Type.
  • To add a temporary character behavior such as jumping, climbing, interacting, or changing height, configure or create an Ability.
  • To add lightweight presentation that runs alongside locomotion, use an Effect.
  • To change camera placement or rotation, use a View Type rather than moving the camera directly each frame.
  • To change how an equipped weapon or tool works, configure its Character Item Action modules.
  • To add health, shield, stamina, hunger, or another changing value, use the Character Attribute Manager and add Character Health only when damage and death behavior are required.
  • To respond to impacts or footsteps, configure the Surface System instead of placing one-off audio, decal, and particle logic on every object.

Example: a player-controlled third-person character

Build the character with a third-person Movement Type, Animator, Standard Abilities, and the player input route. The character root owns Ultimate Character Locomotion, Character Layer Manager, the Rigidbody and colliders, the input handlers, and any optional gameplay groups. The model owns the Animator and Animator Monitor. The scene camera owns Camera Controller, Camera Controller Handler, a third-person View Type, and Object Fader.

Example: an AI character with a weapon

Enable AI Agent and Items. The character uses Local Look Source instead of player input and Ultimate Character Locomotion Handler. Inventory and Item Set Manager still determine what the agent owns and can equip, while the AI solution starts movement, abilities, and item actions. Enable NavMeshAgent only when Unity navigation should supply locomotion.

Verify in Play Mode

  1. Select the character root. In Ultimate Character Locomotion, confirm that the intended First Person Movement Type or Third Person Movement Type is active and that the configured Abilities can start.
  2. Move or drive the character. The kinematic Rigidbody should remain controlled by Ultimate Character Locomotion, and the colliders should resolve stairs, slopes, and obstacles without a second movement component competing with it.
  3. Select the camera and confirm that Camera Controller follows the expected Character with the intended View Type.
  4. Watch the model’s Animator parameters while moving or starting an ability. Animator Monitor should update them and the expected animation should play.
  5. Exercise each optional group that was enabled: equip an item, apply damage, trigger a footstep, or switch perspective. Only the corresponding component group should own that behavior.

The Console should remain free of missing component, unassigned Item Collection, missing Look Source, and invalid movement or View Type errors.

Troubleshooting

Symptom Check Fix
The character does not move from player input Check for a Player Input implementation, Ultimate Character Locomotion Handler, and an active Movement Type. Also check whether the character was built as AI Agent. Update the character through Character Manager using the correct player or AI route, then configure the matching input system.
The character moves twice, jitters, or fights physics Check for another movement script, a dynamic Rigidbody, or Unity gravity acting alongside Ultimate Character Locomotion. Remove the competing motor and restore the UCC Rigidbody to Is Kinematic with Use Gravity disabled.
The camera does not follow the character Check Camera Controller > Character, Init Character On Awake, and the configured View Types. Assign the character or rerun Setup Manager > Scene > Camera Setup with the correct Perspective.
Animations do not respond to movement Check that the active model has both an Animator with the intended controller and an Animator Monitor. Update the character through Character Manager and correct the model’s Animator Controller.
An item is owned but cannot equip Check Inventory, Item Set Manager, its Item Collection, Item Set Group category and rules, Item Handler for a player, and the Item Abilities. Re-enable Items in Character Manager and configure a valid Item Collection and Item Set Rule.
Health or respawning is incomplete Check for the complete Character Attribute Manager, Character Health, and Character Respawner group and the named Health attribute. Enable Health in Character Manager, then configure the attributes and respawn behavior.
An AI character responds to player input Check for player input components, Ultimate Character Locomotion Handler, or Item Handler left on the AI character. Update it with AI Agent enabled. Drive it through the AI integration and Local Look Source instead.
The character collides with its own model or misses expected layers Check the Character, SubCharacter, Overlay, and other UCC layers plus the generated collider hierarchy. Run the Setup Manager’s Project layer setup and update the character through Character Manager.

Developer reference

The main runtime types are grouped by responsibility:

  • Opsive.UltimateCharacterController.Character contains UltimateCharacterLocomotion, handlers, AnimatorMonitor, Movement Types, Abilities, and Effects.
  • Opsive.UltimateCharacterController.Camera contains CameraController and View Types.
  • Opsive.UltimateCharacterController.Inventory contains InventoryBase, Inventory, ItemSetManager, ItemCollection, and the built-in ItemType.
  • Opsive.UltimateCharacterController.Items and .Items.Actions contain CharacterItem, perspective items, actions, and modules.
  • Opsive.UltimateCharacterController.Traits contains AttributeManager, CharacterAttributeManager, Health, CharacterHealth, and CharacterRespawner.
  • Opsive.Shared.Events.EventHandler connects these systems without requiring direct component references for every notification.

Common entry points include:

Goal API
Change the movement model UltimateCharacterLocomotion.SetMovementType(Type) or SetMovementType(string)
Find and control an ability GetAbility<T>(), GetAbilities<T>(), TryStartAbility(Ability, ...), and TryStopAbility(Ability, ...)
Find an item ability or effect GetItemAbility<T>() and GetEffect<T>()
Change the camera model CameraController.SetViewType(Type, bool) and GetViewType<T>()
Read or change an item amount InventoryBase.GetItemIdentifierAmount, AddItemIdentifierAmount, and RemoveItemIdentifierAmount
Find a changing value AttributeManager.GetAttribute(string)

For example, custom gameplay code can ask the locomotion component for the configured Jump ability instead of constructing a second movement system:

using Opsive.UltimateCharacterController.Character;
using Opsive.UltimateCharacterController.Character.Abilities;
using UnityEngine;

public class StartConfiguredJump : MonoBehaviour
{
    public void TryJump()
    {
        var locomotion = GetComponent<UltimateCharacterLocomotion>();
        var jump = locomotion.GetAbility<Jump>();
        if (jump != null) {
            locomotion.TryStartAbility(jump);
        }
    }
}

Use the Events page when custom code should observe UCC state changes rather than poll components each frame.