Behavior Designer Pro

Export

Use the Behavior Designer Pro integration when a behavior tree should decide what an AI character does while Ultimate Character Controller handles locomotion, collision, animation, items, health, abilities, and effects.

Before you begin

  • Install Ultimate Character Controller Version 3 and a compatible Behavior Designer Pro release. Ultimate Character Controller 3.2.1 was the first Version 3 release with Behavior Designer Pro support; when either product changes, install the integration version intended for that combination.
  • Build or update the character as an AI Agent in Character Manager. This prepares the character for external decisions and removes player-input ownership, but does not add sensing or a behavior tree.
  • Enable NavMeshAgent when the character will use Unity navigation. Enable Items and Health only when the tree needs the related Ultimate Character Controller tasks.
  • Bake a valid NavMesh before testing a moving agent. Behavior Designer chooses the destination, but Ultimate Character Controller’s NavMeshAgent Movement ability performs the character movement.

Install and connect the integration

  1. Sign in to Opsive Downloads and download the Behavior Designer Pro integration for Ultimate Character Controller. The bridge is not included in either base product’s Integrations folder before this download.
  2. Import the downloaded package after both products compile. Importing it creates the integration files in the project; resolve any package or assembly errors before continuing.
  3. Open Tools > Opsive > Ultimate Character Controller > Character Manager. Assign the character and enable AI Agent. Enable NavMeshAgent if the tree will use Unity navigation, then select Build Character or Update Character.
  4. Open Tools > Opsive > Ultimate Character Controller > Integrations Manager and select Behavior Designer Pro.
  5. Expand Agent Setup, assign the Ultimate Character Controller character to Character, and select Setup Agent.
  6. Inspect the character. Setup adds Behavior Tree and Behavior Tree Agent and ensures that the character uses the Ultimate Character Controller AI-agent configuration.
  7. Open the Behavior Tree and create or assign the tree that will control the character.

The Behavior Tree Agent component coordinates the tree with Ultimate Character Controller death and respawn. Its Pause On Death choice determines whether an active tree is paused or stopped when the character dies. A tree that was active before death starts again after respawn.

Build a patrol-and-attack scenario

Start with one small behavior whose result is easy to observe:

  1. Add a high-priority branch that checks whether the agent has a valid, visible target. Sensing tasks come from Behavior Designer, an add-on, or your own project; they are not supplied by this bridge.
  2. In the attack branch, use Set Aim Target to assign the target to Ultimate Character Controller’s Local Look Source.
  3. Use Start Stop Ability to start the Aim ability, then Start Stop Use to use the equipped item. Enable Wait For Use Complete when the branch should remain active until the Use ability finishes.
  4. Add a chase branch that sends the target position to the selected Behavior Designer movement task. That task supplies the destination; NavMeshAgent Movement converts the path into Ultimate Character Controller input and rotation.
  5. Add a lower-priority patrol branch for the no-target state.
  6. When an attack or chase branch is aborted, deliberately stop any ability that should not remain active and clear the aim target.

This creates a clean ownership chain: the behavior tree chooses patrol, chase, or attack; navigation calculates the route; the integration requests Ultimate Character Controller actions; and Ultimate Character Controller produces the final movement, collision, items, and animation. See Patrol and chase an enemy for a nontechnical tree structure.

Choose the correct integration task

All integration tasks can act on the tree owner or another target GameObject. The selected object must contain the Ultimate Character Controller component required by that task.

Abilities and effects

Task Important fields Result
Start Stop Ability Ability Type, Priority Index, Start, Always Return Success Starts or stops the matching Ultimate Character Controller ability. Priority Index selects the ability’s Index when more than one ability has the same type; -1 uses the first match.
Is Ability Active Ability Type, Priority Index Succeeds only while the matching ability is active.
Start Stop Effect Effect Type, Start, Always Return Success Starts or stops the matching Ultimate Character Controller effect.
Is Effect Active Effect Type Succeeds only while the matching effect is active.
Start Stop Interact Ability Type, Priority Index, Start, Interactable GameObject Assigns the target object’s Interactable component to an Ultimate Character Controller Interact ability, then starts or stops that ability.

The Ability Type and Effect Type controls list types present on the selected Ultimate Character Controller character. Starting can fail when the ability is missing, blocked, or rejected by Ultimate Character Controller’s ability rules. Leave Always Return Success disabled when the tree should react to that failure.

Items and aiming

Task Important fields Result
Set Aim Target Aim Target Assigns or clears Local Look Source > Target. It fails if the target character has no Local Look Source.
Start Stop Use Slot ID, Action ID, Start, Wait For Use Complete, Always Return Success, Aim Target Selects the matching Use ability, optionally aims at a target, and starts or stops item use. When waiting, the task returns Running until use completes.
Reload Slot ID, Action ID Starts the matching Reload ability for an item slot and action.
Start Equip Unequip Category ID, Item Set Index Starts the Equip Unequip ability for the selected item-set group and index.
Start Item Set Ability Ability Type, Category ID Starts the matching item-set ability in the chosen item-set category.
Get Item Identifier Amount Item Type, Store Result Stores the inventory amount for the selected item identifier. It fails if the inventory, item, or output variable is unavailable.

Use Slot ID and Action ID when a character has multiple item actions. Do not assume that the first Use or Reload ability controls the intended weapon. Also confirm that the correct item set is equipped before asking the tree to use or reload it.

Health, attributes, state, and events

Task Important fields Result
Damage Amount Applies positive damage through the target’s Health component.
Heal Amount Heals the target through its Health component.
Is Alive None Succeeds while the target’s Health component reports that it is alive.
Has Taken Damage Attacker Succeeds as a short damage notification and can store the attacking GameObject. It is not a persistent damaged state.
Get Attribute Value Attribute Name, Store Result Stores the current value of a named Ultimate Character Controller attribute, such as Health.
Set State State Name, Activate State Activates or deactivates an Ultimate Character Controller state on the target.
Execute Event Event Name Sends a named, parameterless Ultimate Character Controller event to the target GameObject.

Use shared variables for stored results so later tasks can compare the inventory, attribute, or attacker value. Has Taken Damage is intended to trigger an immediate reaction; store any information needed after that brief notification.

Key choices and limitations

  • Decision tasks and UCC tasks are different layers. The integration supplies Ultimate Character Controller actions and conditions, not sight, hearing, patrol routes, target selection, or general pathfinding tasks.
  • Only one system should move the character. Let a supported navigation task choose or update the destination, then let an Ultimate Character Controller pathfinding movement ability and Ultimate Character Locomotion apply final motion. Do not also move the Transform.
  • Ultimate Character Controller owns normal character animation. Start abilities and item actions instead of forcing Animator states for standard locomotion, aiming, reloading, or item use.
  • Task failure is useful. A start task normally fails when Ultimate Character Controller rejects the request. Use that result to select a fallback branch. Reserve Always Return Success for cleanup where rejection is intentionally harmless.
  • Waiting changes branch lifetime. Start Stop Use returns Running while Wait For Use Complete is enabled and the Use ability is active. If the task ends during that wait, it stops the active Use ability.
  • Events have no payload in this task. Execute Event sends only Event Name. Use another task or custom integration code when the receiver requires arguments.
  • Death handling is component-based. Keep Behavior Tree Agent on the character if the tree should stop or pause on death and resume after respawn.

Verify in Play Mode

  1. Enter Play Mode without pressing movement controls. The AI character should not respond to player input.
  2. Watch the Behavior Designer runtime view. The tree should become active and select the expected patrol branch when no target is present.
  3. Present a reachable target. Confirm the movement task updates the destination, NavMeshAgent Movement becomes active, and the character follows the path using Ultimate Character Controller movement and animation.
  4. Enter attack range. Confirm Local Look Source > Target points at the intended object, Aim starts, and Start Stop Use controls the correct item slot and action.
  5. Force an ability to be blocked. The corresponding start task should return Failure unless Always Return Success is enabled, and the tree should take its intended fallback.
  6. Apply damage. Confirm Has Taken Damage triggers the immediate reaction and stores the attacker when configured.
  7. Kill and respawn the character. The tree should pause or stop according to Pause On Death, then restart only if it was active before death.

Troubleshooting

Symptom Check Fix
The integration tasks are missing or Unity reports missing types One product may be absent, or the bridge may not match the installed Behavior Designer Pro and Ultimate Character Controller releases Install both supported product versions first, then reimport the matching integration and allow Unity to recompile.
Setup Agent is disabled or does nothing Character may be empty or may not contain Ultimate Character Locomotion Build or update the object as an Ultimate Character Controller character, assign that root GameObject in Agent Setup, and run Setup Agent again.
The tree runs but the character never moves The bridge does not provide a destination task, the NavMesh may be missing, or NavMeshAgent Movement may not be installed Add a supported Behavior Designer movement task, bake the NavMesh, and update the Ultimate Character Controller character with AI Agent and NavMeshAgent enabled.
The character jitters or separates from its navigation agent A navigation component and Ultimate Character Controller may both be applying Transform movement Let the behavior system set the destination and let Ultimate Character Controller apply final position and rotation. Remove the competing Transform update.
Start Stop Ability always fails The selected Ability Type may be absent, Priority Index may select no matching Index, or another ability may block it Add the ability, correct the Index selection, and inspect the active abilities that can block the request. Do not hide the failure until the cause is understood.
The agent aims correctly but uses or reloads the wrong item Slot ID, Action ID, or the active item set may not match the intended item action Equip the expected item set and select the exact slot and action used by that item.
The agent attacks forward instead of toward its target Local Look Source may be missing, or Set Aim Target may not have run before Aim and Use Update the character as an AI Agent, then set the aim target before starting the abilities.
A damage reaction is inconsistent when checked later Has Taken Damage is a brief event-driven condition rather than a lasting state React immediately, or store the attacker and any follow-up state in shared variables.
The tree continues through death or does not restart after respawn Behavior Tree Agent may be missing, the tree may not have been active before death, or Pause On Death may not match the desired lifecycle Run Setup Agent, choose the intended death behavior, and verify the tree is active before testing death and respawn.
Movement works but animation does not match The Animator, Animator Controller, Movement Type, or root-motion configuration may be incomplete Repair the Ultimate Character Controller Animator setup and let Ultimate Character Controller drive its parameters instead of forcing Animator states from the tree.

Developer reference

The integration’s Agent Setup calls the Ultimate Character Controller AI-agent builder, then adds the Behavior Designer Behavior Tree and the bridge’s Behavior Tree Agent components. The bridge tasks use Ultimate Character Controller’s normal public systems rather than bypassing them:

  • Ability and effect tasks call the same start and stop validation used by Ultimate Character Controller gameplay code.
  • Use waits by observing the selected Use ability and its usable item actions; ending a waiting task stops that active Use ability.
  • Health and attribute tasks resolve the target’s Health, Attribute Manager, and named attribute at runtime.
  • Has Taken Damage listens for Ultimate Character Controller damage and death events and exposes the attacker only during its short success window.
  • Execute Event invokes Ultimate Character Controller’s named event dispatcher without arguments.
  • Behavior Tree Agent listens for Ultimate Character Controller death and respawn events to preserve the tree’s intended lifecycle.

Create a custom Behavior Designer task when a tree must pass event parameters, select a project-specific item module, expose a longer-lived condition, or coordinate several Ultimate Character Controller calls as one reusable action. Keep the same ownership boundary: the tree decides what should happen, and Ultimate Character Controller performs character mechanics through its supported APIs.