A* Pathfinding Project

Export

Use the A* Pathfinding Project integration when an AI character should follow an A* graph while Ultimate Character Controller remains responsible for collision, animation, abilities, and final character movement.

Before you begin

  • Install Ultimate Character Controller Version 3 and the A* Pathfinding Project version supported by the integration package.
  • Download the Ultimate Character Controller A* integration from the Opsive downloads page. The bridge is distributed separately so it can compile against A* without adding that dependency to Ultimate Character Controller.
  • Start with an A* graph that scans successfully and includes both the character’s starting point and its intended destinations. The official A* get started guide covers AstarPath, graphs, movement scripts, and scanning.
  • Read the integration package’s included documentation before choosing an A* movement component. A* adds and changes movement implementations independently of Ultimate Character Controller, so a newer component name does not by itself establish bridge support.

Import A* before the integration. If either product is upgraded later, confirm that the bridge release supports the new version before replacing it in a working project.

Connect an A* agent to Ultimate Character Controller

  1. Open Tools > Opsive > Ultimate Character Controller > Character Manager.
  2. Assign the character model and enable AI Agent. Leave NavMeshAgent disabled because that option installs Unity’s navigation components and NavMeshAgent Movement instead.
  3. Choose the required perspective, Animator, standard abilities, items, and health for the agent, then select Build Character or Update Character.
  4. Add the A* movement component required by the downloaded integration release. Current A* versions include components such as AIPath, RichAI, AILerp, and FollowerEntity, but do not substitute one unless the bridge documentation explicitly lists it.
  5. Add any A* companion component required by that movement implementation. For example, AIPath, RichAI, and AILerp use a Seeker; FollowerEntity has different requirements.
  6. Add one AstarPath component to the scene through Component > Pathfinding > AstarPath, configure its graph, and select Scan.
  7. On the character’s Ultimate Character Locomotion component, expand Abilities, select the plus button, and add Astar AI Agent Movement.
  8. Keep only one pathfinding movement ability on the character. Astar AI Agent Movement is concurrent, so it does not need a priority position merely to remain active with other abilities. If the character uses Speed Change, keep Speed Change above the pathfinding ability so the generated input is not scaled twice by update order.
  9. Supply a reachable destination through the supported A* movement component or through the behavior system that controls the agent.

The AI Agent option removes player-input ownership and adds a Local Look Source. It prepares the character for external decisions but does not add patrol points, sensing, target selection, or attack logic.

How movement is shared

A behavior tree, state machine, or gameplay script chooses the destination. A* calculates the path and steering needed to follow it. Astar AI Agent Movement converts that result into the input vector and rotation expected by Ultimate Character Locomotion. Ultimate Character Controller then moves the character, resolves collisions, and drives its movement animation.

Do not let an A* movement script and Ultimate Character Controller both apply final position or rotation to the Transform. Use the movement settings supplied with the integration release; fields such as A*’s Update Position and Update Rotation have changed across A* versions. A competing Transform writer usually produces sliding, jitter, or separation between the graph agent and visible character.

Set a destination

Choose one owner for destination updates:

  • For a fixed patrol point, set the A* movement agent’s destination and request a path. Calling SearchPath() requests the new path immediately; otherwise the agent may wait for its next automatic repath.
  • For a moving target, A*’s AIDestinationSetter can copy its Target Transform into IAstarAI.destination before path searches. Use it only with an A* movement component supported by the bridge release.
  • For a behavior system, update the destination when the target changes enough to justify a new path. Recalculating an unchanged path every frame adds work without improving the character movement.

A* path requests are asynchronous. pathPending remains true until the result is available, and remainingDistance may be infinite when no path exists. Do not treat either state as arrival.

Decide what arrival means

Current A* movement agents expose two related results:

  • reachedDestination is the recommended best-effort check for the requested destination. For AIPath and RichAI, it uses End Reached Distance and also considers whether the destination lies above or below the character.
  • reachedEndOfPath means the agent reached the end of the calculated path. That endpoint can differ from the requested destination when an obstacle makes the destination unreachable.

Ultimate Character Controller’s PathfindingMovement contract exposes HasArrived, and the integration maps the A* result into that property. The exact A* property and tolerance used by that mapping are bridge-version details; check the downloaded source or README before gameplay logic depends on one interpretation. For a patrol, verify both that path calculation has finished and that the arrival result matches whether an unreachable endpoint should count.

Choose A* or Unity NavMesh

Use case Recommended route
The project already uses A* graphs, tags, penalties, graph updates, or A*-specific movement Build an Ultimate Character Controller AI Agent without NavMeshAgent, then use the downloaded Astar AI Agent Movement integration.
The project only needs Unity navigation Enable AI Agent and NavMeshAgent in Character Manager and use Ultimate Character Controller’s built-in NavMeshAgent Movement. No A* integration is required.
The project needs a custom pathfinder Derive a movement ability from Ultimate Character Controller’s PathfindingMovement contract and keep the pathfinder from moving the Transform directly.

Do not install both Astar AI Agent Movement and NavMeshAgent Movement for the same navigation job. They can issue different movement and rotation values during the same frame.

Key choices and limitations

  • Graph and movement implementation: choose these in A* first, then confirm that the integration release supports the selected movement component. The current A* manual listing a component is not a compatibility promise from the Ultimate Character Controller bridge.
  • Root motion: A* supplies the route, not the final animated displacement. Match Ultimate Character Controller movement animations and Speed Change settings to the speed the character should display.
  • Airborne movement: Allow Movement In Air comes from Ultimate Character Controller’s pathfinding base ability. Disable it when a jump, fall, or another airborne ability must own planar input and rotation.
  • Links and special traversal: Unity NavMeshAgent Movement has Ultimate Character Controller-specific off-mesh-link handling, but those settings do not automatically apply to an A* graph link. Confirm both the A* movement component’s link support and the bridge release’s handoff before relying on jumps or custom traversal.
  • Teleports and respawns: Ultimate Character Controller pathfinding abilities must keep their navigation agent synchronized after an immediate Transform change. Test these flows because the implementation is bridge-version specific.

Verify in Play Mode

  1. Show the A* graph in the Scene view and confirm the character starts on a walkable node or surface.
  2. Assign a destination on the same connected graph. Confirm a path is calculated after any brief pathPending period.
  3. In Ultimate Character Locomotion, confirm Astar AI Agent Movement becomes active and the character follows the path around an obstacle.
  4. Confirm the visible character, collider, and A* agent remain together. Position and rotation should not be applied twice.
  5. Move the destination while running. The path should update at the intended rate without pausing or recalculating continuously when the target is stationary.
  6. Test a reachable and an unreachable destination, then confirm the result used by the behavior system matches the intended arrival rule.
  7. Trigger Speed Change, an airborne ability, teleport, death, and respawn when the game uses those features. Confirm the A* agent and Ultimate Character Controller character remain synchronized.

Troubleshooting

Symptom Check Fix
The integration produces missing A* types or namespaces A* may be absent, imported after the bridge, or outside the bridge’s supported version range Import the supported A* release first, then reimport the matching Ultimate Character Controller integration.
No path is calculated AstarPath may be missing, the graph may not be scanned, or the endpoints may be outside connected walkable nodes Add one AstarPath, configure and Scan the graph, then move both endpoints onto the same connected graph.
A path appears but the Ultimate Character Controller character does not move Astar AI Agent Movement may be absent or disabled, or the chosen A* movement component may not be supported by this bridge release Add and enable the integration ability, then restore the A* component named by the package README or demo.
The character jitters, slides, or separates from the A* agent Both systems may be writing the Transform Restore the integration’s recommended A* movement settings and let Ultimate Character Controller apply final position and rotation. Remove any additional movement script that also moves the character.
The behavior reports arrival too early The path may still be pending, or it may be checking the end of the current path instead of the requested destination Wait for path calculation, then use the arrival result whose semantics match the scenario. Check End Reached Distance when supported by the selected A* agent.
The character reaches the closest walkable point but never reaches the requested destination The destination may be outside the graph or behind an unreachable area Move or project the destination onto a reachable graph location, or deliberately treat reachedEndOfPath as a separate failure result.
Keyboard or controller input still moves the AI The character may still have player-input handlers Enable AI Agent in Character Manager, select Update Character, and confirm player-input components are removed.
A root-motion character moves at the wrong visible speed The pathfinder’s speed and the selected movement animation do not match Use Ultimate Character Controller Speed Change and suitable movement animations; do not expect the A* speed field alone to retime root motion.
A graph link does not trigger a jump or special animation The A* movement component or bridge may not support that traversal handoff Use a supported A* link workflow and explicitly connect it to the required Ultimate Character Controller ability or animation. Do not copy Unity NavMesh link settings.

Developer reference

The released Ultimate Character Controller Version 3 PathfindingMovement base class defines the handoff expected from any navigation integration:

  • InputVector and DeltaRotation provide the values consumed by Ultimate Character Locomotion.
  • SetDestination(Vector3) and GetDestination() manage the navigation target.
  • HasArrived reports the integration’s arrival result.
  • Teleport(Vector3) synchronizes the navigation agent after an immediate character Transform change.
  • SetDestinationRotation(Quaternion) optionally supplies final facing.
  • AllowMovementInAir determines whether path input continues while airborne.

On the A* side, current IAstarAI implementations expose destination, SearchPath(), pathPending, reachedDestination, reachedEndOfPath, remainingDistance, and Teleport(). The Ultimate Character Controller bridge connects these two contracts, but its concrete class names and mappings can change independently of both products. Compile and test custom code against the integration package installed in the project rather than copying a namespace or field from a different bridge release.