Artificial Intelligence (AI)

Export

Ultimate Character Controller supplies the character movement, animation, items, health, and abilities that an AI can control. It does not choose when to patrol, chase, attack, or retreat; connect a behavior tree, state machine, or your own decision system for those choices.

Choose an AI workflow

Scenario	Character setup	Decision and movement source
A guard patrols, detects a target, and chases it	AI Agent, NavMeshAgent, Animator, and the abilities used by the guard	A behavior system chooses destinations and actions; NavMeshAgent Movement follows the baked NavMesh.
A stationary turret aims and fires	AI Agent, Items, and a Local Look Source; no navigation is required	The behavior system assigns a target and starts the Aim and Use abilities.
A companion repeatedly follows a moving target	AI Agent and the selected pathfinding integration	The behavior system refreshes the destination until it is within the chosen follow distance.
An agent uses the A* Pathfinding Project	AI Agent, but not the Unity NavMeshAgent option	Install the integration and use its Astar AI Agent Movement ability.
A custom navigation solution drives the character	AI Agent and a custom Pathfinding Movement ability	The custom ability converts the navigation result into UCC input and rotation.

Use one system for decisions and one integration for movement. Avoid letting a pathfinding component and Ultimate Character Locomotion both move the Transform.

Build an AI-ready character

Place the character model in the scene. Character Manager updates scene objects rather than editing a prefab asset directly.
Open Tools > Opsive > Ultimate Character Controller > Character Manager.
Assign the model to Character, choose Perspective, and select First Person Movement and/or Third Person Movement for that perspective. Enable Animator and assign a compatible Animator Controller when the model should animate.
Enable AI Agent. This adds Local Look Source and removes Ultimate Character Locomotion Handler, Item Handler, and the Unity input component.
Enable NavMeshAgent only when this character will use Unity navigation. Character Manager adds NavMeshAgent Movement and its required Unity NavMeshAgent component.
Enable Standard Abilities, Items, and Health only when the AI scenario needs them. Assign the required item collection and item-set rule when Items is enabled.
Select Build Character for a new character or Update Character for an existing UCC character.
Inspect the result. An AI character should have Local Look Source and should not retain player-input handlers. A Unity-navigation character should also have NavMeshAgent Movement in its ability list.

The AI Agent option prepares the character for external control; it does not add sensing, decisions, targets, patrol points, or attack logic.

Connect the behavior system

Choose a controlling system that can issue small, explicit commands to the character:

For Behavior Designer, install the character-controller integration and follow the Opsive Character Controllers integration. Its tasks can coordinate navigation and UCC abilities from a behavior tree.
For a stationary or aiming agent, set Look Transform on Local Look Source to the head or desired origin, then assign Target when the AI acquires something to look at. The target changes the look direction; the behavior system must still decide when to Aim or Use an item.
For a custom decision system, use the public movement and ability APIs in the developer section instead of simulating keyboard input or moving the character Transform.

Keep decisions separate from character mechanics. For example, a chase state should select the target and destination, while NavMeshAgent Movement, Ultimate Character Locomotion, and the Animator handle the path, collision, and visible movement.

Build a NavMesh that contains the agent’s starting position and every intended destination.
Select the character and expand Abilities in Ultimate Character Locomotion.
Select NavMeshAgent Movement and configure Auto Enable, Rotation Override, Arrived Distance, Allow Movement In Air, and any off-mesh link choices.
Have the behavior system assign a reachable destination.
Use HasArrived or the behavior system’s equivalent condition before advancing to the next patrol point or action.

The Unity NavMeshAgent calculates the path, but Ultimate Character Locomotion performs the character movement. NavMeshAgent Movement disables direct NavMesh position updates, converts desired velocity into UCC input, and keeps the agent synchronized with the resulting character position. See NavMeshAgent Movement for rotation, arrival, speed, and off-mesh link choices.

Design common scenarios

Patrol and chase

Store patrol destinations in the behavior system. Send the current point to NavMeshAgent Movement, wait for arrival, and then choose the next point. When the character detects a target, replace the patrol destination with the target’s current or predicted position. Decide how often to refresh a moving destination so the agent responds without recalculating unnecessarily every frame.

Aim and attack

Assign the detected target to Local Look Source > Target, then start Aim and Use only while the behavior permits an attack. Configure Items in Character Manager and verify that the required item is equipped before starting Use. Stop the abilities or clear the target when the behavior exits the attack state.

Investigate and return

Keep the last known position separate from the current target. Navigate to that position, perform the investigation behavior for a limited time, then return to patrol when the target is not reacquired. UCC performs the movement and abilities; the decision system owns the timer and state transition.

Use another pathfinder

Do not enable Character Manager’s NavMeshAgent option when the character will use a different navigation system. For the A* Pathfinding Project, follow the A* Pathfinding Project integration. For another system, implement a Pathfinding Movement ability that exposes its desired input, rotation, destination, arrival, and teleport behavior.

Verify in Play Mode

Start the scene without providing player input. Keyboard or controller input should not move the AI character.
Assign a reachable destination. Confirm the pathfinding movement ability becomes active, a valid path is created, and the character follows it using its UCC movement and animation.
Confirm the character stops within Arrived Distance and the controlling behavior advances only after arrival.
Change the target while the character moves. Navigation and facing should update from the intended systems without the character snapping or rotating between two competing owners.
For an armed agent, assign the Local Look Source target, equip the intended item, and start Aim and Use. The item should act in the same direction the AI presents visually.
Apply damage and trigger death or respawn if the character supports them. The behavior should react, and navigation should resume from the new character position rather than the previous agent position.
Test every required off-mesh link, movement speed, and target-loss transition before duplicating the agent.

Troubleshooting

Symptom	Check	Fix
Keyboard or controller input still moves the AI.	The character may still have Ultimate Character Locomotion Handler, Item Handler, or a Unity input component.	Enable AI Agent in Character Manager and select Update Character. Confirm the player-input components were removed.
The AI has no look direction or attacks forward instead of at its target.	Local Look Source may be missing, its Look Transform may be unsuitable, or Target may be empty.	Update the AI Agent setup, assign the look origin, and set the target before starting Aim or Use.
Setting a Unity NavMesh destination fails.	The ability may be disabled without Auto Enable, or the agent may not be on a baked NavMesh.	Enable the ability or Auto Enable, then place the character on a valid NavMesh and retry a reachable destination.
A path exists but the character does not move.	The path may still be pending, the NavMeshAgent may be stopped, the destination may already be inside Arrived Distance, or movement animation may not provide the expected root motion.	Inspect the path and active ability, test a farther destination, and verify the Movement Type and Animator setup.
The character slides, jitters, or separates from its NavMeshAgent.	Another component may be updating the Transform or NavMeshAgent position directly.	Let NavMeshAgent Movement synchronize the agent and let Ultimate Character Locomotion move the character. Remove the competing Transform update.
The item is equipped but does not attack.	The Items setup, Local Look Source, Use ability, or the behavior’s manual start and stop commands may be incomplete.	Verify item support and the active item set, assign the look target, then start and stop the correct Use ability deliberately.
The agent will not cross a jump link.	Jump or Fall may be absent, or the link area may not match Manual Off Mesh Link Name.	Add the required abilities and match the NavMesh link and NavMeshAgent Movement settings.
Many AI characters are expensive.	Animator, inverse kinematics, collision detection, items, and decision updates may all contribute.	Profile before changing behavior, then disable unneeded features on the AI setup and reduce update frequency or visual detail for distant agents.

Developer integration

Send a Unity NavMesh destination

Retrieve the built-in NavMeshAgent Movement ability and call SetDestination. The call returns false when the disabled ability cannot auto-enable, the agent is not on a NavMesh, or Unity rejects the destination.

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

public class AIDestination : MonoBehaviour
{
    [SerializeField] private GameObject m_Character;
    [SerializeField] private Transform m_Destination;

    public bool MoveToDestination()
    {
        var locomotion = m_Character.GetComponent<UltimateCharacterLocomotion>();
        var movement = locomotion.GetAbility<NavMeshAgentMovement>();
        return movement != null && movement.SetDestination(m_Destination.position);
    }
}

The current movement surface also provides GetDestination(), HasArrived, SetDestinationRotation(Quaternion), and Teleport(Vector3).

Integrate another pathfinder

Derive the movement ability from PathfindingMovement. Supply InputVector, DeltaRotation, HasArrived, SetDestination, GetDestination, and Teleport; override SetDestinationRotation when the pathfinder supports a final facing direction. The base ability is concurrent, can suppress input in the air, writes the result to Ultimate Character Locomotion, and applies an active Speed Change multiplier.

Control abilities, items, damage, and impacts

Retrieve an ability with UltimateCharacterLocomotion.GetAbility<T>(), then use TryStartAbility and TryStopAbility. AI characters do not have an input handler to start these actions for them.
Start a specific item-set change with EquipUnequip.StartEquipUnequip(itemSetIndex). The index belongs to that Item Set Group, so do not assume the same index across different groups.
Apply simple damage with Health.Damage(float), or use a richer overload when the behavior needs an impact point, direction, force, attacker, or collider.
Listen for OnObjectImpact with EventHandler.RegisterEvent<ImpactCallbackContext> when the configured impact action invokes that event. Unregister the same callback when the receiving component is destroyed.