()` retrieves the first enabled, State-active module matching a type across the action's groups.
Useful runtime events include `OnItemUse` and `OnItemUseComplete` for Usable actions, `OnShieldImpact` for Shield impacts, and `OnCharacterUpdateItemAbilityParameters` when item-ability Animator parameters should refresh. Custom modules should use their module lifecycle and interfaces so they register listeners only while enabled and equipped, and clean up on unequip, removal, and destruction.
---
# Usable
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/)
A Usable Action turns the character's **Use** input into an item result. Use the base action for a switch, flashlight, scanner, or another custom interaction; use a specialized action when the item needs firearm, melee, throwable, or spell systems. Every Usable Action shares the same input selection, Trigger timing, animation events, and reusable module lifecycle.
## Choose the action that matches the result
| Goal | Action | What it adds |
| --- | --- | --- |
| Toggle a flashlight, play an effect, change a State, or spend an Attribute | **Usable Action** | The shared Trigger and Usable module groups without a weapon-specific pipeline. |
| Fire a firearm or other ranged weapon | [Shootable](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/shootable/) | Shooters, ammunition, clips, projectiles or hitscan, fire effects, impacts, and reloading. |
| Swing an Iron Sword or perform an unarmed attack | [Melee](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/melee/) | Attacks, hitbox collision, impacts, and recoil. |
| Throw a grenade or another inventory-backed object | [Throwable](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/throwable/) | Throwing, projectile spawning, ammunition, impacts, trajectory preview, and re-equipping. |
| Cast a spell | [Magic](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/magic/) | Casters and modular spell start, repeat, stop, and impact behavior. |
These four specialized actions inherit the shared Usable Action flow. Configure their action-specific groups on the linked pages, but use the Trigger and common fields on this page to decide when each cycle starts and completes.
## Build or update the item
1. Open **Tools > Opsive > Ultimate Character Controller > Item Manager**.
2. Assign the Item Definition, perspectives, visible objects, Animator Item ID, and Character Item slot described in [Item Creation](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-creation/).
3. In the action list, select the plus button and choose **Usable**, **Shootable**, **Melee**, **Throwable**, or **Magic**. Give the row a name that describes its result.
4. Select **Build Item** for a new Character Item or **Update Item** for an existing one.
5. Select the generated Character Item and inspect every Character Item Action. Each action on the same item needs a unique **ID**.
6. On the character, add or select the [Use item ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/use/). Set its **Action ID** to the action's **ID**, and use **Slot ID -1** for all equipped slots or a specific Inventory slot.
7. Confirm that the action has at least one enabled Trigger module. A Usable Action without an enabled Trigger is invalid and cannot produce a result.
In released Version 3, choosing the base **Usable** type in the Item Manager creates the demo flashlight pattern: an item **Attribute Manager** with a `Battery` Attribute, a **Simple** Trigger, a **Use Attribute Modifier Toggle**, and Light children for the supplied perspective objects. It also changes **Use Event** and **Use Complete Event** to immediate timed triggers. Keep those generated parts for a flashlight, or replace them with the modules required by your interaction.
The following configured flashlight shows the two shared groups. Its values are an example, not the raw component defaults.
## Configure the shared action fields
Adding `UsableAction` directly as a component starts with empty Trigger and Usable groups. Its released Version 3 field defaults are:
| Inspector field | Default | Choose this based on |
| --- | ---: | --- |
| **ID** | `0` | The **Action ID** used by the character's Use ability. IDs must be unique on one Character Item. |
| **Use Rate** | `0.1` seconds | The minimum delay after completion before another cycle may start. A Repeat or combo Trigger still respects this delay. |
| **Face Target** | Enabled | Whether a non-independent-look Movement Type turns toward the Look Source while using the item. The Use ability's **Rotate Towards Look Source Target** must also allow rotation. |
| **Stop Use Ability On Complete Delay** | `1` second | `0` permits an immediate stop, a positive value holds the Use ability for that delay, and a negative value does not release it on completion. |
| **Use Event** | Wait for `OnAnimatorItemUse`; stored duration `0.2` seconds | The exact point when the main Trigger is allowed to perform the action. Disable event waiting to use the duration. |
| **Use Complete Event** | Timed; duration `0.05` seconds | The point when the cycle becomes complete. Enable event waiting to use `OnAnimatorItemUseComplete`. |
| **Force Root Motion Position** | Disabled | Whether the use animation must temporarily own positional root motion. |
| **Force Root Motion Rotation** | Disabled | Whether the use animation must temporarily own rotational root motion. |
Both event fields use an [Animation Event Trigger](https://opsive.com/support/documentation/ultimate-character-controller/animation/animation-event-trigger/). The Item Manager and action templates can replace component defaults, so inspect the generated values before editing Animator events.
## Choose one main Trigger
Only the first enabled module in **Trigger Action Module Group** is active. Reordering or disabling Trigger modules therefore changes the action's timing; adding several does not combine their behavior.
| Trigger | Use it when |
| --- | --- |
| **Simple** | One press should produce one complete cycle. |
| **Repeat** | Holding input should start another cycle whenever the previous cycle and **Use Rate** allow it. |
| **Burst** | One press should perform a fixed group. **Burst Size** defaults to `5`, **Cancel Burst On Stop** is disabled, and **Burst Repeat Delay -1** prevents another burst. |
| **Charged** | Holding input should build a `TriggerData.Force` value and releasing should perform the action. Force defaults from `0.1` to `1` over a normalizer of `1` second; auto-fire and repeat-fire are disabled. |
| **Simple Combo** | Separate presses should move through Animator Audio States and may chain between use and completion. Add at least two states for an actual sequence. |
| **Repeat Combo** | Holding input should continue through the combo states. |
| **In Air** | A Simple-style action needs a separate airborne path. With **Require In Air Ability In Air** enabled by default, normal Use still works while grounded but airborne use must come from [In Air Melee Use](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/use/in-air-melee-use/). |
Simple, Repeat, Burst, Charged, and both combo triggers use an [Animator Audio State Set](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/animator-audio-state-set/) to supply audio and Item Substate Index data. The Trigger's **Substate Index Data** starts at index `0` with priority `100`; the selected Animator Audio State contributes its own state index.
## Add common Usable modules
The **Usable Action Module Group** can contain several enabled modules. Each module participates only in the lifecycle stages represented by its implemented interfaces, so one module can block the start while another supplies effects or animation data.
| Module | User-facing purpose |
| --- | --- |
| **Generic Item Effects** | Run an [Item Effect group](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/item-effects/) on start, use, update, or completion. Only **On Use** is enabled by default. |
| **Use Attribute** | Spend an Attribute on the item GameObject per use and optionally drop the item when that Attribute reaches its destination. |
| **Character Use Attribute** | Spend an Attribute from the character per use. |
| **Aim Substate** | Add Item Substate Index data while Aim is active and optionally run effects when input-driven aiming starts or stops. Its default index is `100`, priority `150`, and additive mode is enabled. |
| **Use Attribute Modifier Toggle** | Toggle perspective GameObjects and an Attribute modifier each time the action is used. By default it prevents use when the configured Attribute is invalid and targets the `Battery` Attribute. |
| **Module State Switcher** | Select one named option and activate its State on both the character and Character Item. **Loop** is enabled and **Index** starts at `0`. |
| **Activate States** | Activate character States while equipped, between start and use, or between use and completion. All three phases are enabled by default. |
| **Enable Can Start Use** | Expose a **Can Start Use** boolean, enabled by default, that a State preset or project code can turn off. |
| **Debug Use** | Write a configured message when the action reaches Use. This is intended for diagnosis rather than final gameplay. |
Use Attribute reads the item's Attribute Manager; Character Use Attribute reads the character's Attribute Manager. Reversing those two is a common reason an action remains unavailable even though an Attribute with the same name exists elsewhere.
See [Action Module Groups](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/) for enabling, ordering, State presets, and custom modules.
## How it runs
1. The Use ability finds the equipped Character Item by **Slot ID** and its component by **Action ID**. It also requires a Look Source and, by default, rejects a new input while the pointer is over UI.
2. The action checks **Use Rate**, pending Use or completion events, and every enabled module that can veto the ability or item start.
3. **Start Use** registers `OnAnimatorItemUse` and `OnAnimatorItemUseComplete`, applies the root-motion and facing choices, starts the main Trigger, and invokes start-stage modules.
4. **Use Event** releases the cycle at the selected animation event or duration. The first enabled Trigger performs its pattern, then all enabled modules that participate in Use receive the call.
5. **Use Update** runs while the ability is active. Repeat, Burst, Charged, combo, condition, and effect modules can use this stage to continue or delay the cycle.
6. **Use Complete Event** marks the cycle complete, calculates the next allowed time from **Use Rate**, invokes completion modules, and releases the ability according to **Stop Use Ability On Complete Delay**.
7. **Stop Use** cancels outstanding waits, stops participating modules, removes forced root motion, and unregisters the animation events.
Aim can remain active and feed aiming state to the action's modules. Use has priority over Reload for the same Character Item, and beginning Use can stop that item's reload. An **Equip Unequip** ability with **Prevent Start Use Reload Active** can keep Use from interrupting an equipment transition; otherwise a requested Use may stop the active equip change.
## Verify the result
### Editor checkpoint
Before Play Mode, confirm:
- the Character Item Action **ID** matches the Use ability's **Action ID**;
- every action on the Character Item has a unique ID;
- the intended Trigger is the first enabled module;
- **Use Event** and **Use Complete Event** match the animation clips or tested durations;
- the Trigger's Animator Audio States map to valid Item Substate Index transitions; and
- item and character Attributes exist on the GameObject read by their respective modules.
The Usable Character Item Action Inspector also exposes **Interfaces info** labels beside lifecycle interfaces. The label shows the matching module count. Hover it to list the matching modules. Right-click and choose an action such as **Log modules with interface 'IModuleUseItem'.** to print each matching module and its active/inactive and enabled/disabled state to the Console. This is a diagnostic command: it does not enable, reorder, or invoke a module. Use it together with the action's **Debug** foldout when one module is blocking or supplying a lifecycle stage.
### Play Mode checks
1. Equip the item, select its Usable Action, expand **Debug**, and press the configured Use input.
2. Confirm the expected action becomes active and the Debug section advances through start, use, completion, and stop.
3. Confirm the result occurs at **Use Event**, not merely when input begins, and that it does not repeat sooner than **Use Rate**.
4. Hold and release input. Compare the result with the chosen Simple, Repeat, Burst, Charged, or combo behavior.
5. Watch the Animator's Item State and Item Substate Index. Aim once and confirm an **Aim Substate** changes only the intended animation.
6. For a firearm, verify a shot and reload handoff; for an Iron Sword, verify the hitbox window; for a throwable, verify release and re-equip; for magic, verify the caster's start-to-stop sequence.
7. For a plain Usable Action, confirm each State, Attribute, GameObject toggle, audio clip, or other Item Effect changes once at the configured lifecycle stage.
8. Unequip and re-equip the item, then repeat the test to confirm toggles, States, pending events, and module conditions reset as intended.
## Troubleshoot a Usable Action
| Symptom | Check | Fix |
| --- | --- | --- |
| Use becomes active but nothing happens | **Trigger Action Module Group** | Enable at least one Trigger and move the intended Trigger to the first enabled position. |
| The wrong action runs | Character Item Action **ID**, Use **Action ID**, and Use **Slot ID** | Give every action a unique ID and match the correct Use row to that ID and slot. Module IDs do not select the action. |
| The action waits forever before its result | **Use Event** and `OnAnimatorItemUse` | Add the event to the correct animation and slot, or disable event waiting and use a tested duration. |
| The animation finishes but Use remains active | **Use Complete Event**, `OnAnimatorItemUseComplete`, stop delay, and modules that prevent stopping | Supply the event or duration, then use `0` for an immediate post-completion release or a tested positive delay. |
| Repeat, Burst, or combo timing is wrong | First enabled Trigger, **Use Rate**, Animator Audio States, and event timing | Test one Trigger at a time. Confirm each state reaches Use and completion before tuning the next cycle. |
| An Attribute module blocks use | Attribute owner and name | Put **Use Attribute** targets on the item and **Character Use Attribute** targets on the character; make the exact Attribute name and available value valid. |
| The character does not face the target | Use ability rotation, action **Face Target**, and Movement Type | Enable both rotation choices. An independent-look Movement Type keeps control of facing. |
| Aim plays the wrong use animation | **Aim Substate** index/priority and ability order | Verify the substate data and keep Use above Aim when Use's Item State should have priority. |
| Reload or Equip Unequip behaves unexpectedly | The interacting ability's target item and priority | Use stops Reload for the same item. Check **Prevent Start Use Reload Active** on Equip Unequip when equipment transitions must finish first. |
| A Magic action conflicts with another action ID | IDs after an Item Manager build | Released Version 3's Magic builder path leaves a new Magic Action at the default ID `0`. Assign a unique ID before Play Mode. |
| Replacing **Activate States > State Names** from code disables the wrong State or throws | Runtime array replacement | Released Version 3's runtime setter uses incorrect values while replacing an active array. Author the fixed list in the Inspector before Play Mode; if runtime replacement is unavoidable, first deactivate the module and its States, then manage the transition in project code. |
## Saving and multiplayer
Action fields and module configuration are serialized with the Character Item or prefab. The current use cycle, cooldown time, pending animation waits, charge progress, and active Trigger data are runtime state and are reinitialized; persist an Attribute or another gameplay value explicitly when it must survive a save and load.
The multiplayer integration supplies network ownership to Character Item Actions, and some built-in modules send explicit network calls, including the Generic Item Effects start stage and Use Attribute Modifier Toggle GameObject changes. Do not assume a custom module or every lifecycle stage is replicated automatically. Keep authoritative results in the networking integration and test start, repeated use, completion, perspective toggles, and interruption on owner and remote clients.
## Related tasks
- [Use item ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/use/) configures input, Slot ID, Action ID, and ability interactions.
- [Character Item Actions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/) explains action ownership and unique IDs.
- [Action Module Groups](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/) explains module ordering, States, and extension points.
- [Item Effects](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/item-effects/) lists reusable effects for a plain Usable Action.
- [Animator Audio State Set](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/animator-audio-state-set/) configures Trigger animation, audio, and substate selection.
- [Animator Parameters](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/animator-parameters/) explains Item State Index and Item Substate Index.
- [Attributes](https://opsive.com/support/documentation/ultimate-character-controller/attributes/) explains the item and character values consumed by Attribute modules.
## Developer reference
`UsableAction` implements `IUsableItem` and exposes the shared values through `UseRate`, `FaceTarget`, `UseEvent`, `UseCompleteEvent`, `ForceRootMotionPosition`, `ForceRootMotionRotation`, `TriggerActionModuleGroup`, and `UsableActionModuleGroup`. `MainTriggerModule` returns the first enabled Trigger, and `TriggerData` carries `Force`, `Index`, and the use count into specialized action modules.
Custom common modules inherit `UsableActionModule` and implement only the lifecycle interfaces they need. Common choices include `IModuleCanStartUseItem`, `IModuleStartItemUse`, `IModuleUseItem`, `IModuleUseItemUpdate`, `IModuleItemUseComplete`, `IModuleTryStopItemUse`, `IModuleCanStopItemUse`, `IModuleStopItemUse`, `IModuleGetUseItemSubstateIndex`, and `IModuleOnAim`. Use the Inspector's Play Mode **Debug** foldout to see which module vetoed a stage before adding logs.
The [Event System](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/) publishes `OnItemStartUse(IUsableItem, bool)`, `OnItemUse(IUsableItem)`, `OnUseAbilityUsedItem(IUsableItem)`, and `OnItemUseComplete(IUsableItem)` during the shared lifecycle. `OnAnimatorItemUse` and `OnAnimatorItemUseComplete` are the matching animation event names.
---
# Shootable
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/shootable/)
A Shootable Action turns a Character Item into a firearm, bow, launcher, or another ranged weapon. Configure it as a pipeline: input chooses when to fire, the Shooter chooses hitscan or a moving projectile, Ammo and Clip track rounds, effects provide feedback, Impact modules decide what a hit does, and the Reloader refills the clip.
## Create a working firearm
1. Open **Tools > Opsive > Ultimate Character Controller > Item Manager** and follow [Item Creation](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-creation/) to assign the Item Definition, perspectives, visible objects, slot, and Animator Item ID.
2. In the action list, add **Shootable**, give the row a descriptive name, and select **Build Item** or **Update Item**.
3. Select the generated Character Item. Confirm that the Shootable Action **ID** is unique on this item, then match it with **Action ID** on the character's [Use item ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/use/). Use **Slot ID -1** for every equipped slot or select the weapon's exact slot.
4. In **Ammo Action Module Group**, select **Item Ammo** and assign an **Ammo Item Definition**. Add that definition to the character's inventory or Default Loadout. Use **Infinite Ammo** only when the weapon should not consume an inventory item.
5. Position the generated **Fire Point Location**, **Muzzle Location**, and **Shell Location** for every enabled perspective. If a Hitscan Shooter uses a Tracer, also assign **Tracer Location**; that transform is not created automatically.
6. Choose the firing recipe below, then configure the inherited **Use Event** and **Use Complete Event** to match the weapon animation. Configure reload timing on **Generic Reloader**.
7. In **Impact Action Module Group**, keep or add **Generic Shootable Impact** and configure its conditions and Impact Actions. A ray or projectile collision does not create gameplay damage by itself.
The Item Manager's released Version 3 Shootable recipe starts with **Repeat**, **Hitscan Shooter**, **Item Ammo**, a **Simple Clip** of `50`, **Basic Projectile**, common firing effects, **Generic Shootable Impact**, **Generic Reloader**, **Dry Fire Substate**, and **Slot Item Monitor Module**. These are useful starting values, not a finished weapon: the ammo definition, visuals, animations, audio, and target result still need to be assigned.
## Choose a firing recipe
| Result | Main modules | Important choices |
| --- | --- | --- |
| Instant firearm | **Simple**, **Repeat**, or **Burst** Trigger; **Hitscan Shooter**; **Basic Projectile** | Use **Fire In Look Source Direction** for crosshair aiming. Set **Fire Count** above `1` for a pellet weapon, and tune **Spread**, **Impact Layers**, and range. |
| Moving bullet, rocket, or energy bolt | **Projectile Shooter**; **Spawn Projectile** | Assign a prefab with the UCC **Projectile** component, a perspective-aware **Fire Point Location**, velocity, fired layer, and collision settings on the projectile. |
| Bow or another visible loaded projectile | **Charged** Trigger; **Projectile Shooter**; **Spawn Projectile**; **Simple Clip** | A one-round clip and **Always** or **On Aim** projectile visibility can show the arrow before release. Use the visible-projectile and reload event fields to synchronize drawing and attaching it. |
| Shotgun or scatter weapon | A Hitscan or Projectile Shooter with **Fire Count** above `1` | One trigger cycle consumes one round from the clip, then produces the configured number of rays or projectiles. **Fire Count** is not a burst; use the **Burst** Trigger for several timed use cycles. |
| Weapon with no reserve-ammo limit | **Infinite Ammo**; **Simple Clip**; **Generic Reloader** | Infinite Ammo still feeds a clip. Keep an enabled Clip, Projectile, and Reloader module because Shootable Action validation requires each core group. |
Only the first enabled **Trigger**, **Shooter**, **Ammo**, **Clip**, **Projectile**, and **Reloader** module is active. Reorder or disable alternatives instead of expecting them to combine. Fire Effects, Dry Fire Effects, Impact, Usable, and Extra groups can run several enabled modules.
## Configure the firing pipeline
### Shooter and projectile
| Module or field | Released Version 3 default | What it controls |
| --- | --- | --- |
| **Hitscan Shooter > Fire In Look Source Direction** | Enabled | Uses the Look Source and crosshair direction. With a non-independent-look Movement Type, the ray begins from the Look Source position. |
| **Hitscan Fire Delay** | `0` seconds | Delays the raycast, but fire effects run when the weapon fires. Use animation timing deliberately if this is positive. |
| **Hitscan Fire Range** | Maximum float value | Maximum ray distance, multiplied by the Trigger's force. |
| **Max Hitscan Collision Count** | `15` | Size of the non-allocating raycast buffer. The editor warns when it fills. |
| **Hitscan Trigger Interaction** | **Ignore** | Whether trigger colliders may be detected. |
| **Hitscan Tracer** | None | Optional pooled tracer. **Tracer Default Length** is `100`, and **Tracer Spawn Delay** is `0`. Assign **Tracer Location** when using it. |
| **Hitscan Spread / Fire Count** | `0.01` / `1` | Random direction variation and rays produced by one consumed clip round. |
| **Projectile Shooter > Fire In Look Source Direction** | Disabled | Uses the Fire Point's forward direction until enabled. |
| **Use Look Source Position** | Disabled | Starts the projectile at the Look Source when the Movement Type does not use independent look. Otherwise it starts at **Fire Point Location**. |
| **Projectile Fire Velocity Magnitude** | `10` | Base launch speed, multiplied by Trigger force. **Inherit Character Velocity** is disabled. |
| **Projectile Fired Layer / Layer Change Delay** | **VisualEffect** / `0` | Layer applied after firing and the delay before it changes. |
| **Projectile Spread / Fire Count** | `0.01` / `1` | Random direction variation and projectiles produced by one consumed clip round. |
| **Spawn Projectile > Projectile Visibility** | **On Fire** | Choose **On Aim**, **On Reload**, or **Always** when a bow arrow, shell, or other loaded projectile should be visible before firing. |
| **Spawn Projectile > Projectile Start Layer** | **IgnoreRaycast** | Layer used while a visible projectile is attached to the item. |
For hitscan, **Impact Layers** determine what the ray can hit. For Projectile Shooter, the field helps choose the aim direction and prevent a pre-spawned projectile from crossing an obstruction; the projectile prefab's own collider, layers, and [Projectile](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/projectile/) settings control the moving object's actual collisions.
### Ammo, clip, and reload
**Item Ammo** removes inventory ammo when it is loaded into the clip, not when the shot leaves the clip. Its **Drop Option** defaults to **Ammo Left**, and **Shared Ammo Item Identifier** is disabled. Enable sharing only when two active weapons that use the same Ammo Item Definition should redistribute a limited reserve.
**Simple Clip** defaults to **Clip Size 50**. Index `0` is the next round to fire. On the first equip, a valid Generic Reloader with any Auto Reload option enabled immediately fills the clip when ammo is available.
**Generic Reloader** defaults are:
- **Auto Reload**: **Pickup** and **Empty**;
- **Reload Type**: **Full** rather than one round per cycle;
- **Reload Can Camera Zoom** and **Reload Crosshairs Spread**: enabled;
- **Reload Event**: wait for the slot event `OnAnimatorItemReload`;
- **Reload Complete Event**: wait for the slot event `OnAnimatorItemReloadComplete`; and
- reload Item Substate Index: index `0`, priority `100`.
Change **Reload Type** to **Single** for a shotgun-style one-round loop. The reloader repeats its reload state while the clip has room and reserve ammo remains, then waits for the completion event. When using **Reload Detach Attach Clip**, move a separate MeshRenderer clip transform. Do not reparent a SkinnedMeshRenderer or a weapon-rig bone.
See [Reload](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/reload/), [Animation Event Trigger](https://opsive.com/support/documentation/ultimate-character-controller/animation/animation-event-trigger/), and [Animator Audio State Set](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/animator-audio-state-set/) for the ability, timing, and reload substate setup.
### Feedback, impacts, and aiming
The generated Fire Effects group contains **Muzzle Effect**, **Shell Effect**, **Recoil Effect**, and **Crosshairs Spread**. Muzzle pooling is enabled by default; the muzzle and shell prefabs still need to be assigned. Add **Smoke Effect** or **Generic Item Effects** when the weapon needs additional feedback. The Dry Fire Effects group is separate, so an empty clip can use different audio or visuals.
**Generic Shootable Impact** evaluates its [Impact Action Conditions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/impact-action-conditions/), then runs either its pass or fail [Impact Actions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/impact-actions/). Use this group for damage, force, surface effects, events, or other target results.
Useful Extra modules include:
- **Dry Fire Substate**, which defaults to index `11`, priority `200`, and prevents a held Repeat or Burst Trigger from cycling continually while dry;
- **Look Sensitivity**, which defaults to `0.97` in both perspectives and delays firing until the visible weapon points closely enough toward the Look Source. A value of `-1` effectively removes this restriction;
- **Prevent Dry Fire**, which prevents a use cycle only when both the clip and reserve are empty;
- **Scope**, whose **Disable Scope Camera On No Aim** option is disabled by default; enable it and assign perspective-specific scope camera objects when the scope should appear only during input-driven Aim; and
- **Slot Item Monitor Module**, which shows both loaded and unloaded counts by default.
The [Aim](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/aim/) ability supplies aiming state. [Third Person Item Pullback](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/third-person-item-pullback/) can move a third-person firearm away from walls before Use, Aim, or Reload continues.
## How it runs
1. The Use ability selects the equipped Character Item by **Slot ID** and its Shootable Action by **Action ID**. The inherited Trigger and Use Event determine when one fire cycle begins.
2. The first enabled Shooter reads round `0` from the first enabled Clip. If it is invalid, the action invokes Dry Fire Effects instead of firing.
3. A valid cycle removes one round from the clip. Hitscan schedules its ray or Projectile Shooter obtains objects from the Projectile module. **Fire Count** can produce several rays or projectiles from that one round.
4. Hitscan range, projectile velocity, and impact strength use the Trigger's force. This is what lets a Charged Trigger produce a stronger or faster result.
5. The action invokes every enabled Fire Effect once per fire cycle. A moving projectile then owns its flight; hitscan resolves its ray immediately or after **Hitscan Fire Delay**.
6. On collision, the Shootable Action invokes each enabled Impact module. Generic Shootable Impact evaluates conditions and applies the configured pass or fail actions.
7. Clip and reserve changes refresh their events and the Slot Item Monitor. If the clip becomes empty and Generic Reloader includes **Empty**, completion of Use asks the Reload ability to start.
8. Generic Reloader waits for the reload event, transfers inventory ammo into the clip, repeats for **Single** reloads when needed, then waits for the reload-complete event and releases the Reload ability.
## Verify the weapon
### Editor checkpoint
Before Play Mode, confirm:
- the Shootable Action **ID** matches Use **Action ID**, and every Character Item Action ID is unique;
- Shooter, Ammo, Clip, Projectile, and Reloader each have an enabled first module;
- Item Ammo has an Ammo Item Definition that exists in the inventory or Default Loadout;
- every perspective property points to the intended visible object's fire, muzzle, shell, tracer, scope, projectile, and reload transforms;
- Projectile Shooter uses **Spawn Projectile** and a prefab with a UCC Projectile component, while Hitscan uses **Basic Projectile**;
- Use, Use Complete, Reload, and Reload Complete events exist in the correct Animator clips or use tested durations; and
- Impact Layers and Generic Shootable Impact allow the intended target and result.
### Play Mode checks
1. Equip the weapon, expand the Shootable Action's **Debug** section, and note loaded and unloaded ammo.
2. Fire one cycle. Confirm the clip falls by one even when **Fire Count** produces several pellets, and confirm muzzle, shell, recoil, audio, and animation occur at the intended frame.
3. Fire at a valid target and an excluded target. Confirm the correct Impact Condition branch runs and that the target receives damage, force, surface feedback, or the configured alternative.
4. Aim and fire near an obstruction in first and third person. Confirm the shot direction, origin, crosshair alignment, visible projectile, muzzle, tracer, and scope all switch to the correct perspective.
5. Empty the clip. Confirm dry-fire feedback occurs once for held Repeat or Burst input, then confirm Empty auto-reload starts only while reserve ammo remains.
6. Test Full and Single reload timing. Watch Item State and Item Substate Index, clip attachment, ammo transfer, camera zoom, and crosshair spread through completion.
7. Unequip, re-equip, switch perspective, and repeat. Confirm pooled effects and visible projectiles are removed or reattached correctly.
## Troubleshoot a Shootable Action
| Symptom | Check | Fix |
| --- | --- | --- |
| Use starts but the weapon does not fire | Required first modules, clip count, reserve count, and **Look Sensitivity** | Enable a Shooter, Ammo, Clip, Projectile, and Reloader. Add the Ammo Item Definition to inventory, reload, and temporarily use `-1` Look Sensitivity while confirming alignment. |
| The wrong weapon action runs | Shootable Action **ID**, Use **Action ID**, and Use **Slot ID** | Give every action a unique ID and match the Use row to the intended action and slot. |
| Hitscan fires in the wrong direction | **Fire In Look Source Direction**, Movement Type, Fire Point, and Look Source | Enable look-source firing for crosshair aim, or rotate and position each perspective's Fire Point when muzzle-forward firing is intended. |
| A tracer throws an error or starts at the wrong place | **Tracer** and **Tracer Location** | Assign a perspective-specific Tracer Location whenever a tracer prefab is assigned. |
| The ray hits but nothing happens | **Impact Layers**, trigger interaction, Generic Shootable Impact, and target colliders | Include the target layer, choose trigger handling deliberately, and add pass/fail Impact Actions that produce an observable result. |
| A projectile is null, does not move, or never collides | Shooter/Projectile pairing and projectile prefab | Pair Projectile Shooter with Spawn Projectile, assign its prefab, and build that object with the UCC Projectile component, collider, layers, and impact settings. |
| A loaded bow arrow is missing or attached incorrectly | **Projectile Visibility**, Fire Point, reload attachment, and visible-projectile events | Use On Aim or Always as appropriate, assign both perspective transforms, and synchronize show/attach events with the bow animation. |
| The clip stays empty | Ammo Item Definition, inventory quantity, Clip Size, Auto Reload, and active item | Add reserve ammo, keep Clip Size positive, and enable a suitable Auto Reload flag or start Reload manually. Shared ammo does not let an unequipped item take the reserve. |
| Reload never transfers ammo or never ends | `OnAnimatorItemReload`, `OnAnimatorItemReloadComplete`, slot, and event-wait settings | Put both events in the matching slot animation, or disable event waiting and use tested durations. |
| A reload clip deforms or disrupts the rig | **Reloadable Clip** transform | Use a separate MeshRenderer object. Do not assign a SkinnedMeshRenderer or bone that belongs to the weapon rig. |
| One press creates too many shots | Trigger type and Shooter **Fire Count** | Use Fire Count for simultaneous pellets. Return it to `1` and use Burst when the shots should be separate timed cycles. |
| A projectile fails **Check Weapon Source Category** or **Check Weapon Source Definition** unexpectedly | Projectile Shooter impact context | In released Version 3, Projectile Shooter clears the Shootable Action reference before these two conditions evaluate, so the projectile is treated as a non-weapon source. Avoid those source-weapon filters for projectile shots unless **Allow Non Weapon Impact** matches the intended result; use projectile/target conditions or a project-fixed shooter module instead. |
| **Projectile Enable Delay After Other Use** has no effect | Projectile Shooter field | Released Version 3 serializes this default `0.4` field but never reads it at runtime. Coordinate dual-item timing with Use Rate, animation events, or project code instead. |
## Saving and multiplayer
The Character Item or prefab serializes the Shootable Action, module order, module fields, and perspective references. Item Ammo is an inventory amount and Simple Clip exposes its remaining count through the item-definition consumer interface, but an in-progress use, delayed hitscan, visible pre-spawned projectile, recoil, and reload event wait are runtime state. Save durable ammo and clip counts through the inventory/save integration and restart transient action timing after load.
The multiplayer integration explicitly routes built-in fire effects, dry-fire effects, and impact modules; Projectile Shooter also uses network ownership and server handling for spawned projectiles. A custom module, custom Item Effect, or arbitrary event is not replicated merely because it belongs to a Shootable Action. Test firing, impact authority, ammo, reload, visible projectiles, and first/third-person effects on the owner, server, and remote clients.
## Related tasks
- [Usable Action](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/) explains Trigger choices, Use timing, Action IDs, and the common module lifecycle.
- [Use](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/use/), [Aim](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/aim/), and [Reload](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/reload/) configure the interacting item abilities.
- [Common Item Setups](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-creation/common-setups/) provides practical creation routes for ranged items.
- [Projectile](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/projectile/) configures a moving projectile object's collision and runtime behavior.
- [Action Module Groups](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/) explains module order, States, and custom modules.
- [Item Effects](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/item-effects/), [Impact Action Conditions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/impact-action-conditions/), and [Impact Actions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/impact-actions/) configure feedback and hit results.
- [Animator Parameters](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/animator-parameters/) explains Item State and Item Substate Index values.
## Developer reference
`ShootableAction` extends `UsableAction` and exposes `ShooterModuleGroup`, `AmmoModuleGroup`, `ClipModuleGroup`, `ProjectileModuleGroup`, `FireEffectsModuleGroup`, `DryFireEffectsModuleGroup`, `ImpactModuleGroup`, `ReloaderModuleGroup`, and `ExtraModuleGroup`. `MainShooterModule`, `MainAmmoModule`, `MainClipModule`, `MainProjectileModule`, and `MainReloaderModule` return each group's first enabled module. Runtime counters are available through `ClipSize`, `ClipRemainingCount`, and `AmmoRemainingCount`; `ReloadClip(bool instantly, bool fullClip)` provides the direct reload entry point.
The [Event System](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/) publishes `OnShootableItemAmmoChange(CharacterItem, ShootableAmmoModule)`, `OnShootableItemClipChange(CharacterItem, ShootableClipModule)`, `OnStartReload(ShootableReloaderModule)`, `OnItemReload(IReloadableItem)`, `OnItemReloadComplete(IReloadableItem)`, and `OnShootableWeaponShowProjectile(GameObject, bool)`. The core animation event names are `OnAnimatorItemReload`, `OnAnimatorItemReloadComplete`, `OnAnimatorStartVisibleProjectile`, `OnAnimatorItemReloadShowProjectile`, and `OnAnimatorItemReloadAttachProjectile`; clip visuals also support detach, drop, attach, and reactivate events.
---
# Melee
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/melee/)
The Melee Action turns an equipped item, an unarmed Body action, or another close-range attack into timed collision checks, impacts, damage, recoil, and animation. Use it when an Iron Sword swing should be active only during a specific part of its animation and should react differently to characters, shields, and solid scenery.
## Before you begin
- Create the Character Item through **Tools > Opsive > Ultimate Character Controller > Item Manager**. The [Sword setup](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-creation/common-setups/#sword) shows the usual visible-item arrangement; use the [invisible Body setup](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-creation/common-setups/#invisible-body-or-unarmed-action) for fists or kicks.
- Confirm that the character has a [Use item ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/use/). Its **Action ID** must match the Melee Action's **ID**, and its **Slot ID** must include the equipped item.
- Add the attack states and Item Substate Index values to the Animator before relying on animation events. See [Animator Parameters](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/animator-parameters/).
- Decide whether movement comes from locomotion or the clip. **Force Root Motion Position** and **Force Root Motion Rotation** are both off by default and should be enabled only for an animation authored to own that motion.
## Build an Iron Sword attack
1. In the Item Manager, create or select the Iron Sword Character Item and add a **Melee** action. Select **Build Item** for a new item or **Update Item** for an existing one.
2. Select the generated Character Item. Confirm that the Melee Action has a unique **ID** and that the character's Use ability targets that ID and slot.
3. Inspect the generated starter modules: **Repeat Combo** Trigger, **Simple Attack**, **Hitbox Collision**, **Generic Melee Impact Module**, and **Simple Recoil**. The builder also sets **Face Target** off. Remove or replace a starter only when the attack needs different behavior.
4. In **Hitbox Collision**, configure the first- and third-person **Hitboxes** separately. Resize each generated Box Collider around the blade or striking limb; Box, Sphere, and Capsule Colliders are supported.
5. On each hitbox, keep **Damage Multiplier** at `1` initially, assign an optional **Surface Impact**, and decide whether minimum offsets, movement, or one-hit-per-use filtering should limit it.
6. In the Repeat Combo Trigger's **Animator Audio State Set**, add one state per combo step. Map each state to an Item Substate Index implemented by the Iron Sword Animator.
7. In **Simple Attack**, align **Active Attack Start Event Trigger**, **Active Attack Complete Event Trigger**, and **Allow Chain Attack Event Trigger** with the swing. Use animation events for authored contact windows or tested durations for a simple prototype.
8. In **Generic Melee Impact Module**, tune the successful [Impact Actions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/impact-actions/) for damage, force, surface response, and target reactions. Its default filters accept every substate and Attack ID.
9. Keep **Simple Recoil** when the swing should stop and play recoil after hitting a valid shield or a `RecoilObject`. Add a **Trail Effect** or **Generic Item Effects** only after the attack window and collision are correct.
10. Save the Character Item prefab, then verify the same active window, hitbox placement, and impact result in both supported perspectives.
The registered legacy Inspector image identifies the Melee Action's Trigger, Usable, Attack, Collision, Attack Effects, Impact, Recoil, and Extra module groups.
## Understand the module groups
| Group | Active-module rule | Responsibility |
| --- | --- | --- |
| **Trigger** | First enabled module | Chooses one use, held repeat, or a combo sequence and supplies the use substate. |
| **Usable** | Every enabled compatible module | Applies shared Attributes, States, effects, and other [Usable Action](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/) behavior. |
| **Attack** | First enabled module | Opens and closes one or more active attack windows. |
| **Collision** | First enabled module | Checks the current perspective's hitboxes or a character-centered sphere while the attack is active. |
| **Attack Effects** | Every enabled module | Runs item-side feedback at active-attack start or completion. |
| **Impact** | Every enabled module | Applies conditions and results after Collision reports a valid target. |
| **Recoil** | First enabled module | Decides whether a hit is solid enough to cancel the attack and select recoil animation/audio. |
| **Extra** | Every enabled module | Adds melee-specific behavior outside the main pipeline. Released Version 3 includes **Trail Effect**. |
Module IDs identify rows for States and networking. The Melee Action **ID** is the value selected by the Use ability; keep action IDs unique on one Character Item.
## How it runs
1. The Use ability resolves the equipped item by **Slot ID** and the Melee Action by **Action ID**, then starts the first enabled Trigger and all applicable shared Usable modules.
2. **Use Event** releases the Trigger. The first enabled Attack module waits for **Active Attack Start Event Trigger**.
3. At active start, the Attack supplies `MeleeAttackData`, activates its optional State on the character and Character Item, and notifies every enabled melee module.
4. During the active window, the Collision module checks once per item update. A valid hit builds the melee impact context and sends it through every enabled Impact module.
5. A solid shield or `RecoilObject` can make Simple Recoil cancel the active attack, select its recoil substate/audio, and publish `OnMeleeRecoil`.
6. **Active Attack Complete Event Trigger** closes the collision window, removes the attack State, and runs completion-stage modules. **Use Complete Event** completes the shared use cycle.
7. Stop Use cancels pending attack events, clears recoil, stops participating effects, and releases the Use ability.
The active attack window, not the entire animation clip, controls damage. Place its start after the wind-up and its completion after the blade has passed the target.
## Choose attack and combo timing
**Simple Attack** performs one active window per use. Its released-Version-3 defaults are:
| Field | Default | Runtime purpose |
| --- | ---: | --- |
| **Active Attack Start Event Trigger** | Timed, `0` seconds | Opens collision checking. The matching event is `OnAnimatorActiveAttackStart`. |
| **Active Attack Complete Event Trigger** | Timed, `0.2` seconds | Closes collision checking. The matching event is `OnAnimatorMeleeAttackComplete`. |
| **Allow Chain Attack Event Trigger** | Timed, `0.2` seconds | Allows a Combo Trigger to accept the next use before the current use fully completes. The matching event is `OnAnimatorAllowChainAttack`. |
| **Single Hit** | Off | Intended attacker-level one-hit choice, but it is not consumed by the released collision code; use the working hitbox choice described below. |
Each attack carries **Attack ID** `0`, blank **State Name**, **Strength Multiplier** `1`, and a Single Hit value. **Attack ID** and the current use substate can filter Attack Effects and Impact modules. A nonempty State is active on both the character and Character Item only during that attack. Impact strength is Trigger force multiplied by **Strength Multiplier**, and Hitbox Collision multiplies it again by that hitbox's **Damage Multiplier**.
Use the Trigger and Attack modules for different jobs:
- **Simple Combo** or **Repeat Combo** advances through the Trigger's Animator Audio States across separate uses. **Allow Attack Combos** starts enabled.
- **Multi Attack** opens several active windows inside one use, each with its own attack data and start/complete timing. Use it for a rapid multi-slash move, not for a normal button-by-button combo.
- A Multi Attack resets the target hit list for each active subattack, so the same target can be damaged once by each subattack when the hitbox's own **Single Hit** is off.
## Choose collision detection
All three Collision modules share **Impact Layers**, **Trigger Interaction: Ignore**, **Max Collision Count: 20**, and **Forward Shield Sensitivity: -0.75**. The hit list resets at each active attack and excludes the attacking character and first-person camera children.
| Collision module | Use it for | Key settings and behavior |
| --- | --- | --- |
| **Hitbox Collision** | A sword, fist, foot, or another shape that follows animation | Uses separate first- and third-person `MeleeHitbox` arrays. Each hitbox can resolve a collider directly or through **Collider Object ID** (`-1` by default), has **Damage Multiplier** `1`, zero minimum Y/Z offsets, **Require Movement** off, **Single Hit** off, and an optional Surface Impact override. |
| **Lerped Hitbox Collision** | Intended to bridge fast motion between frames | Adds **Density**, but the released-Version-3 implementation does not retain the previous pose and therefore does not perform the intended interpolation. Use the limitation guidance below. |
| **Sphere Overlap Collision** | An unarmed or broad area attack that does not need weapon geometry | Checks a sphere centered at local `(0, 1, 1)` with radius `1`. It has no per-hitbox damage multiplier or Surface Impact override. |
Hitbox Collision supports Box, Sphere, and Capsule Colliders. It temporarily disables the attacking character's collision layer and the hitbox collider while performing its overlap, so the item does not detect itself. Keep hitbox colliders on an appropriate trigger or non-blocking layer rather than using their disabled state as the attack gate.
When a struck character has an equipped Shield Action, the collision module can redirect the target collider to the shield if the characters face each other closely enough for **Forward Shield Sensitivity**. A shield that requires Aim must also be actively aimed. The Shield Action then owns absorption and the [Block or parry reaction](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/block/).
## Configure effects, impacts, and recoil
Released Version 3 includes two Attack Effects:
- **Generic Item Effects** invokes an [Item Effect group](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/item-effects/). **On Start Attack** is on, **On Complete Attack** is off, and **Substate Index** and **Attack ID** both start at `-1`, which matches every attack.
- **Enable Disable Effects** selects perspective objects to enable and disable around an active attack. Its released start filter is reversed; use the workaround in Troubleshooting instead of depending on it.
**Generic Melee Impact Module** is the only built-in Impact module. Its Substate and Attack ID filters start at `-1`, its Conditions use the default group, its success result uses the default damage Impact Action group, and its failure group is empty. Add separate rows when different attacks need distinct conditions or results.
**Simple Recoil** recognizes a `ShieldCollider` with durability remaining or a `RecoilObject`. It stops further collision checks for that attack, uses an Animator Audio State Set with substate priority `500`, and publishes `OnMeleeRecoil`. Recoil does not make arbitrary scenery solid automatically; add `RecoilObject` where that response is required.
**Trail Effect** can show a trail only during Attack or Always. It defaults to Attack visibility, no spawn delay, and a timed `0.5` second **Attack Stop Trail Event**. Assign a pooled trail prefab with a `Trail` component and perspective-specific **Trail Location** values.
## Coordinate special melee scenarios
- For an aerial slash or ground slam, configure a separate action and the [In Air Melee Use](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/use/in-air-melee-use/) ability. The **In Air** Trigger keeps normal Use from selecting that path while airborne when **Require In Air Ability In Air** is enabled.
- For a defender reaction, configure the Shield Action and [Block](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/block/). A defending item that contains both Shield and Melee actions uses the parry Item State Index; damage absorption still belongs to Shield.
- For a timed response after a valid block, configure [Melee Counter Attack](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/use/melee-counter-attack/) with its own action ID, range, input order, and collision/impact setup.
- For a root-motion lunge, enable only the root-motion axes authored by the attack clip, then retest hitbox timing and distance. Leave **Face Target** off when player or Movement Type rotation should remain in control.
## Editor checkpoint
Before entering Play Mode, confirm that:
- the Melee Action has a unique **ID** and Use selects the correct ID and slot;
- the intended Trigger, Attack, Collision, and Recoil rows are first among their enabled groups;
- every combo state has a valid Item Substate Index and matching Animator state;
- Use, active-start, active-complete, chain, and Use-complete events exist on the correct slot or use tested durations;
- first- and third-person hitboxes resolve to correctly sized Box, Sphere, or Capsule Colliders;
- Impact Layers include the targets but exclude unintended item, UI, and effect layers;
- the Impact group contains the intended damage, force, surface, and reaction actions; and
- Trail, audio, Item Effect, State, Shield, recoil, and Surface Impact references are assigned where used.
## Verify in Play Mode
1. Equip the Iron Sword, select its Melee Action, expand **Debug**, and perform one attack away from a target.
2. Confirm the Debug state reaches active attack only between the configured start and complete points; collision checks should stop outside that window.
3. Strike one target. Confirm it receives one impact, the expected damage and force, and the correct Surface Impact. Watch the reported attack ID, hit count, and impact strength.
4. Repeat in first and third person. The visible hitbox should follow the correct blade and produce the same gameplay result.
5. Perform every combo step slowly, then at the intended chain timing. Confirm Item Substate Index changes in order and a late press restarts instead of skipping a step.
6. Test a Multi Attack against the same target. Confirm each configured subattack opens and closes once and may apply its own filtered effects and impacts.
7. Strike a `RecoilObject`, an unaimed shield, an aimed shield, and ordinary scenery. Confirm only configured solid targets cancel the attack and select recoil.
8. Test a miss, an airborne start, root-motion movement, perspective switching, and save/load or network boundaries used by the project.
## Troubleshooting and released-Version-3 limitations
| Symptom | Check | Fix |
| --- | --- | --- |
| The animation plays but no collision checks occur | **Active Attack Start Event Trigger**, **Active Attack Complete Event Trigger**, and first enabled Attack | Add the correct events or use tested durations. Keep the active window open across the visible contact frames. |
| A hitbox misses a fast target | Collision type and the released Lerped Hitbox implementation | Released Version 3 never clears its first-check flag, so Lerped Hitbox uses the current pose as both endpoints. Use ordinary Hitbox Collision or Sphere Overlap, or a project-fixed module that retains the previous pose and bounds its result count. |
| A project-fixed lerped hitbox throws when many colliders are crossed | **Density**, **Max Collision Count**, and unique results | The released union writes unique results into a fixed array without a bounds check. Clamp custom/interpolated results to the array capacity. |
| A hitbox collider becomes enabled after the first attack | Collider's initial enabled state | Released Hitbox Collision restores `enabled` to true rather than its previous value. Keep the configured collider enabled on a safe trigger/non-blocking layer, or restore its prior state in a custom module. |
| **Simple Attack > Single Hit** has no effect | Attacker field versus each `MeleeHitbox > Single Hit` | The attacker writes the value but released collision modules never read it. Use per-hitbox **Single Hit** for one accepted collision per use, or custom stop-on-first-impact logic. |
| The same target cannot take repeat damage during one active attack | **Multi Hit Frame Count** and the active-attack hit list | The released hit list suppresses that target until the next active attack, regardless of the frame count. Use Multi Attack for separate hit windows or a custom collision policy. |
| **Enable Disable Effects** does nothing at start or leaves objects reversed | Attack Effect filters | Its released start filter is inverted. Use Generic Item Effects with explicit start and completion groups, or Trail Effect, instead. |
| The sword hits itself or blocks movement | Collider layer, trigger choice, and Impact Layers | Put the hitbox on the intended non-blocking/trigger layer, exclude item layers from impacts, and verify each perspective reference. |
| Damage or force is wrong | Trigger force, attack **Strength Multiplier**, hitbox **Damage Multiplier**, and Impact Actions | Test all multipliers at `1`, then tune one layer at a time. Sphere Overlap has no hitbox multiplier. |
| The target takes no damage | Impact Layers, Collision hit, Generic Melee Impact filters, Conditions, and success group | First confirm Debug reports a collision. Reset filters to `-1`, verify Conditions, and configure the damage action in the success group. |
| Recoil never starts | Hit object, Shield durability, `RecoilObject`, Recoil row order, and Animator states | Add the required component or use a valid shield, keep Simple Recoil first enabled, and implement its recoil Item Substate Index. |
| A combo step is skipped or cannot chain | Trigger Animator Audio States and `OnAnimatorAllowChainAttack` timing | Use one state per step and place the chain event inside the intended input window. Do not use Multi Attack as a substitute for a combo. |
## Saving and multiplayer
The Melee Action, module rows, hitbox references, filters, perspective values, States, and event timing serialize with the Character Item or prefab. Treat the active use, combo step, pending animation waits, active attack State, hit list, collision data, recoil state, and spawned trail as transient runtime state. Finish or cancel an attack around a save/load boundary instead of resuming it midway.
With the multiplayer integration enabled, authority applies Impact modules and explicit calls replicate the main Attack, start-stage Attack Effects, impacts, and supported module results. Completion-stage Generic Item Effects, custom modules, trail lifecycle, and project-specific reactions are not automatically authoritative merely because they are in a Melee group. Test attack start/completion, hits, shields, recoil, trails, and perspective changes on owner, server, and remote clients.
## Related tasks
- [Create the Character Item](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-creation/)
- [Configure the shared Usable Action](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/)
- [Configure the Use item ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/use/)
- [Configure Item Effects](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/item-effects/)
- [Configure Impact Action Conditions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/impact-action-conditions/)
- [Configure Impact Actions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/impact-actions/)
- [Configure Block and parry](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/block/)
- [Configure In Air Melee Use](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/use/in-air-melee-use/)
- [Configure Melee Counter Attack](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/use/melee-counter-attack/)
- [Configure Surface Impacts](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-impacts/)
## Developer reference
`MeleeAction` derives from `UsableAction`. Its action-specific bases are `MeleeAttackModule`, `MeleeCollisionModule`, `MeleeAttackEffectModule`, `MeleeImpactModule`, `MeleeRecoilModule`, and `MeleeExtraModule`. `MainMeleeAttackModule`, `MainMeleeCollisionModule`, and `MainMeleeRecoilModule` return the first enabled rows.
`MeleeUseDataStream` carries `TriggerData`, `MeleeAttackData`, and `MeleeCollisionData`. The collision module creates a `MeleeImpactCallbackContext`, assigns the hitbox index as `SourceID`, sets Impact Strength and optional Surface Impact, and sends the context to `MeleeAction.OnAttackImpact`. Custom attack modules should pair every `OnActiveAttackStart` with `OnActiveAttackComplete` so attack States and all module callbacks remain balanced.
The [Event System](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/) publishes `OnMeleeRecoil(MeleeRecoilModule)` when Simple Recoil starts. The shared action and ability events are documented on [Usable Action](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/) and [Use](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/use/). The attack timing events are `OnAnimatorActiveAttackStart`, `OnAnimatorMeleeAttackComplete`, and `OnAnimatorAllowChainAttack`, each with the configured slot-aware alternative.
---
# Throwable
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/throwable/)
A Throwable Action turns an inventory-backed Character Item into a physical object that the character can throw. Use it for a grenade, rock, potion, or another object that needs a trajectory, collision, and a fresh visible item after each throw; unlike a Shootable Action, it has no clip and re-equips the next inventory unit instead of reloading.
## Create a throwable grenade
1. Open **Tools > Opsive > Ultimate Character Controller > Item Manager** and follow [Item Creation](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-creation/) to assign the Item Definition, first- and third-person objects, Inventory slot, and Animator Item ID.
2. In the action list, add **Throwable**, give the row a descriptive name, and select **Build Item** or **Update Item**.
3. Select the generated Character Item. Confirm that the Throwable Action **ID** is unique on the item, then match it with **Action ID** on the character's [Use item ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/use/). Use **Slot ID -1** for all equipped slots or choose the grenade's exact slot.
4. Keep an enabled first module in **Trigger**, **Thrower**, **Ammo**, **Projectile**, and **Re-Equipper**. The Item Manager recipe supplies **Simple**, **Projectile Thrower**, **Item Ammo**, **Spawn Projectile**, and **Simple Re-Equipper**.
5. Build the thrown prefab with **Tools > Opsive > Ultimate Character Controller > Object Manager**. Choose **Object Type Grenade** for a timed grenade. On its root, confirm that a Collider and the UCC **Grenade** component are present. A non-grenade throwable still needs a root Collider and a [Trajectory Object](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/).
6. In **Spawn Projectile**, assign the prefab to **Thrown Object**. For a Grenade prefab, add **Throwable Grenade** to the action's **Extra** group so use starts the fuse and can remove the pin.
7. Position **Throw Location** and **Trajectory Location** for every enabled perspective. If the grenade has a Pin, also assign each perspective's **Pin Attachment Location** and synchronize **Remove Pin Event** with the animation.
8. Set the Grenade's **Lifespan**, collision behavior, and **Spawned Objects On Destruction**. Put explosion damage and effects on the spawned [Explosion](https://opsive.com/support/documentation/ultimate-character-controller/objects/explosions/) or on the thrown prefab's Projectile impact path.
9. Add the Character Item's Item Definition to the character's inventory or Default Loadout. **Item Ammo** uses that same inventory count and removes one unit when the object is actually thrown.
10. Match **Use Event**, **Use Complete Event**, and **Reequip Event** to the animation. The use event is the release frame; the re-equip event is when the next visible item returns to the hand.
The released Version 3 Item Manager recipe also adds **Generic Throwable Impact**, **Throwable Visualize Trajectory**, **Slot Item Monitor Module**, a Trajectory Object on the Character Item, and enables **Full Inventory Drop**. It sets **Can Equip Empty Item** on the generated Simple Re-Equipper, but it does not add **Throwable Grenade** or a Throw Effect. Treat the generated modules as a starting point and configure the thrown prefab, transforms, events, visuals, and target result before testing.
## Understand the module pipeline
| Module group | Active modules | Purpose |
| --- | --- | --- |
| **Trigger** | First enabled | Chooses Simple, Charged, Repeat, or another inherited input pattern. |
| **Usable** | All enabled | Runs common Usable modules such as States, Attributes, or Item Effects. |
| **Thrower** | First enabled | Calculates the origin, direction, velocity, and trajectory data, then releases the object. |
| **Ammo** | First enabled | Decides whether an object is available and removes its inventory amount. |
| **Projectile** | First enabled | Pre-spawns and supplies the actual GameObject that will be thrown. |
| **Throw Effects** | All enabled | Runs Item Effects at the moment the object is released. |
| **Impact** | Serialized but not called by the released Version 3 built-in throw path | Do not rely on this group for the thrown object's collision result; use the prefab path described below. |
| **Re-Equipper** | First enabled | Waits for the next-item animation and restores the next inventory unit. |
| **Extra** | All enabled | Adds trajectory display, grenade pin/fuse behavior, or the Slot Item Monitor. |
Only the first enabled Trigger, Thrower, Ammo, Projectile, and Re-Equipper participates. Reorder or disable alternatives instead of expecting modules in one of those groups to combine. The action is invalid without an enabled Thrower, Ammo, Projectile, and Re-Equipper; the inherited Usable flow also requires a Trigger.
## Configure the throw
### Origin, direction, and trajectory
| Projectile Thrower field | Released Version 3 default | What it controls |
| --- | --- | --- |
| **Impact Layers** | Every layer except IgnoreRaycast, TransparentFX, UI, and Overlay | Look-source aiming and the pre-throw obstruction linecast. The thrown prefab's Trajectory Object or Projectile layers control its later collisions. |
| **Projectile Thrown Layer** | VisualEffect | Layer assigned after the object has left the hand. |
| **Layer Change Delay** | `0.1` seconds | Time before the spawned object changes from its start layer. |
| **Throw In Look Source Direction** | Disabled | Uses the Look Source position as the origin for a non-independent-look Movement Type and changes the reported fire direction. The built-in Projectile Thrower still rotates its launch velocity toward the Look Source when this is disabled. |
| **Throw Location** | Perspective property | Where the pre-spawned object is held and released. The module creates a `ThrowLocation` child for each visible perspective when added outside a prefab. |
| **Trajectory Location** | Perspective property | Origin used to calculate and display the arc. The module creates a `TrajectoryLocation` child beside each Throw Location. |
| **Trajectory Offset** | `(0, 0, 0)` | Offset from the selected Trajectory Location. |
| **Velocity** | `(0, 5, 10)` | Local launch velocity. The actual throw rotates it toward the Look Source, multiplies it by the Trigger force, and adds the character's forward local velocity. |
Use **Simple** when one press should release at **Use Event**. Use **Charged** when holding input should change `TriggerData.Force`; the actual launch speed is multiplied by that force. **Throwable Visualize Trajectory** shows the Character Item's Trajectory Object while input-driven [Aim](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/aim/) is active and clears it when use begins. Match its mass, gravity, speed, collider, and other trajectory settings to the thrown prefab, and configure a Line Renderer when a visible arc is required.
The preview and live launch are not identical in released Version 3: the built-in preview does not apply Trigger force or add the character's forward velocity. Tune the displayed arc while stationary with a Simple Trigger. A charged or moving throw needs a custom preview module if the line must predict the landing point exactly.
### Spawn, inventory, and re-equip
| Module or field | Released Version 3 behavior |
| --- | --- |
| **Spawn Projectile > Thrown Object** | Starts unassigned. Assign a prefab whose root contains both a Collider and a Trajectory Object-derived component. |
| **Disable Visible Object** | Disabled. When enabled, the held object remains hidden until **Activate Throwable Object Event** or its duration calls `OnAnimatorActivateThrowableObject`. |
| **Start Layer** | IgnoreRaycast. The object uses this layer while attached to the hand. |
| **Item Ammo** | Has no separate ammo definition or clip. It reads the Character Item's own Item Identifier amount and removes one at release. |
| **Simple Re-Equipper > Can Equip Empty Item** | The module default is disabled; the Item Manager's generated Throwable recipe enables it. In released Version 3, the built-in flow does not call this check: reaching zero still reports that the action should unequip and requests the next Item Set. Treat the field as an extension point rather than the built-in zero-count control. |
| **Substate Index Data** | Index `10`, priority `150` while the next item is being re-equipped. |
| **Reequip Event** | Timed at `0.5` seconds by default. Enable event waiting to use `OnAnimatorReequipThrowableItem` in the matching slot animation. |
| **Slot Item Monitor Module > Show** | Enabled. Displays the remaining amount of the Character Item's Item Identifier. |
There is no Throwable clip and the [Reload ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/reload/) is not part of this flow. When use completes and another inventory unit exists, Simple Re-Equipper waits for its event or duration, changes the Item Substate Index, and reveals the next object. When the count reaches zero, the action requests the next Item Set after use stops.
A thrown object is not automatically an inventory pickup. If the player should recover it, configure an [Item Pickup](https://opsive.com/support/documentation/ultimate-character-controller/objects/object-pickup/item-pickup/) as a separate result or add an appropriate pickup behavior to the object that remains after impact.
### Grenade, pin, impact, and feedback
The **Grenade** component is a Projectile-derived Trajectory Object. **Lifespan** defaults to `5` seconds and **Pin** is optional. Cooking starts when the item begins use, not when it leaves the hand, so the use animation and any time held before release count toward the fuse. Configure **Spawned Objects On Destruction** for an explosion prefab; use the Grenade/Projectile **Internal Impact** and Impact Action Group when the moving object itself should apply a collision result.
**Throwable Grenade** is an Extra module, not part of the generated recipe. Its released Version 3 defaults are **Animate Pin Removal** enabled and **Remove Pin Event** waiting for `OnAnimatorItemRemovePin` with a stored duration of `0.4` seconds. Assign **Pin Attachment Location** for both perspectives. The thrown prefab must use the **Grenade** component; this module starts cooking by treating the spawned Trajectory Object as a Grenade.
For release audio, particles, camera feedback, or States, add **Generic Item Effects** to **Throw Effects** and configure its [Item Effects](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/item-effects/). Those effects run when the object is actually thrown. Use the Trigger's Animator Audio State Set for the use animation and its synchronized audio, and use the Re-Equipper substate for the replacement animation.
The generated **Generic Throwable Impact** entry is not reached by the built-in released Version 3 Projectile Thrower or Throwable Action. Configure collisions, damage, force, surface response, and explosions on the thrown prefab's Trajectory Object, Projectile/Grenade **Internal Impact** path, spawned Explosion, or a custom caller. Adding [Impact Actions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/impact-actions/) only to the Throwable Action's Impact group does not make them run.
## How it runs
1. The Use ability finds the equipped Character Item by **Slot ID** and the Throwable Action by **Action ID**. The first enabled Trigger and inherited use fields control the timing.
2. On Start Use, **Spawn Projectile** creates the thrown prefab at the perspective's Throw Location, parents it under the visible item, places it on **Start Layer**, and disables its Trajectory Object. The original visible-object renderers are hidden so only the spawned object represents the item in hand.
3. If **Throwable Grenade** is enabled, it starts the Grenade's fuse immediately and schedules the configured pin event when the pin and visible object are available.
4. At **Use Event**, the Trigger tells Projectile Thrower to release. Spawn Projectile supplies the pre-spawned object, and Item Ammo removes one unit from the inventory.
5. Projectile Thrower detaches the object, enables its root Collider, applies the Trigger-scaled launch velocity plus character forward velocity, initializes the Trajectory Object, and changes the object's layer after **Layer Change Delay**.
6. The action invokes every enabled Throw Effect and raises its throw events. The thrown object's Trajectory Object, Projectile, Grenade, and spawned Explosion then own flight, collision, damage, and destruction.
7. At Use Complete, Simple Re-Equipper starts when another unit remains. It waits for **Reequip Event**, updates the Item Substate Index, and tells Spawn Projectile to show the next visible item.
8. When no unit remains, the action reports that it should unequip and requests the next Item Set after use stops. Item Set rules determine the resulting equipment.
Perspective changes select the matching Throw Location, Trajectory Location, Pin Attachment Location, and visible renderers. Test a throw in every perspective used by the item; a correct third-person origin does not prove that first-person arms are configured.
## Verify the throwable
### Editor checkpoint
Before Play Mode, confirm:
- the Throwable Action **ID** matches Use **Action ID**, and every action on the Character Item has a unique ID;
- Trigger, Thrower, Ammo, Projectile, and Re-Equipper each have an enabled first module;
- **Thrown Object** is assigned and its root has a Collider plus Trajectory Object, Projectile, or Grenade component;
- the Character Item inventory amount is positive;
- each perspective has the intended Throw Location, Trajectory Location, visible object, and optional Pin Attachment Location;
- **Use Event**, **Use Complete Event**, **Activate Throwable Object Event**, **Remove Pin Event**, and **Reequip Event** match their animation clips or use tested durations;
- the Character Item trajectory simulator matches the thrown prefab closely enough for the intended preview; and
- collision, damage, and explosion behavior is configured on the thrown prefab path rather than only in the inactive Throwable Impact group.
### Play Mode checks
1. Equip several copies of the item, expand the Throwable Action's **Debug** section, and record the remaining amount.
2. Start use without releasing immediately. Confirm the spawned object replaces the item mesh at the correct hand location. For a Grenade, confirm its fuse begins and the pin moves at the configured frame.
3. Release one throw. Confirm the inventory amount falls by exactly one at release, the object begins from the correct perspective, and its arc responds to the configured Velocity and Trigger force.
4. Aim while stationary and compare the displayed trajectory with the landing point. Then move or test a Charged Trigger to decide whether the released Version 3 preview limitation matters for the design.
5. Hit an allowed surface and an excluded surface. Confirm the thrown prefab bounces, settles, sticks, damages, or destructs according to its own Trajectory Object/Projectile settings, and confirm an Explosion appears only at the intended time.
6. Watch Item State and Item Substate Index after the throw. Confirm the next unit becomes visible at Reequip Event and that Use cannot begin another throw during re-equipping.
7. Throw the final unit. Confirm the next Item Set handoff matches the equipment rules, and verify any configured pickup can restore the inventory amount.
8. Switch perspective before use, while holding the object, and after re-equipping. Confirm origins, renderers, pin attachment, effects, and the Slot Item Monitor remain correct.
## Troubleshoot a Throwable Action
| Symptom | Check | Fix |
| --- | --- | --- |
| Use does not start | Required first modules, Character Item amount, action IDs, and slot | Enable a Trigger, Thrower, Ammo, Projectile, and Re-Equipper; add the Character Item's Item Identifier to inventory; and match Use **Action ID** and **Slot ID**. |
| The object is null, remains attached, or throws a component error | **Thrown Object**, root Collider, and Trajectory Object-derived component | Assign the prefab and put both a Collider and Trajectory Object, Projectile, or Grenade on its root. |
| The object begins in the wrong place | Perspective-specific **Throw Location**, visible-object hierarchy, and **Throw In Look Source Direction** | Position every Throw Location. Enable look-source origin only when that origin is wanted; the built-in launch velocity still aims toward the Look Source. |
| No trajectory line appears | Input-driven Aim, **Show Trajectory On Aim**, Character Item Trajectory Object, and Line Renderer | Start Aim from input, enable the module, and configure the simulator and Line Renderer on the Character Item. |
| The preview and landing point disagree | Charged Trigger force and character forward movement | Released Version 3 omits both from the built-in preview but applies them to the live throw. Tune while stationary with Simple, or use a custom preview module for exact charged/moving prediction. |
| The object collides while still in the hand or never changes layer | **Start Layer**, **Projectile Thrown Layer**, and **Layer Change Delay** | Keep the attached object on a non-colliding start layer such as IgnoreRaycast and choose an appropriate thrown layer and delay. |
| The object collides but causes no damage or explosion | Thrown prefab's Internal Impact, Impact Actions, destruction settings, and spawned Explosion | Configure the Trajectory Object/Projectile/Grenade path. The Throwable Action's built-in Impact group is serialized but is not called in released Version 3. |
| The pin never leaves the grenade | Grenade **Pin**, **Animate Pin Removal**, object visibility at Start Use, event, and attachment | Assign the Pin and both attachment locations, keep Animate Pin Removal enabled, and keep the spawned object visible when use starts. Supply `OnAnimatorItemRemovePin` or a tested duration. If the object must begin hidden or the built-in animation path is disabled, use a custom pin module or project code. |
| The grenade explodes before release | **Lifespan**, use timing, and time spent cooking | The fuse begins at Start Use. Lengthen Lifespan, shorten the pre-release animation, or make in-hand cooking an intentional part of the design. |
| Canceling use leaves an object in the hand or a fuse continues | Interruption between Start Use and the actual throw | In released Version 3, Spawn Projectile clears its reference on Stop Use without destroying the pre-spawned object, and a Grenade fuse already started keeps running. Prevent interruption during the cook/throw window or add project cleanup for the spawned object and fuse. |
| The next object never appears | Remaining inventory, **Reequip Event**, and Simple Re-Equipper state | Add another inventory unit and provide `OnAnimatorReequipThrowableItem` in the correct slot, or disable event waiting and use a tested duration. |
| The count reaches zero too early or a recovered object does not restore it | Item Ammo's Item Identifier and pickup behavior | Item Ammo consumes the Character Item's own Item Identifier at release. Configure a separate Item Pickup or inventory adjustment for recovery. |
| A first-person or third-person mesh disappears incorrectly | **Disable Visible Object**, activation event, and perspective properties | Assign both perspective objects and transforms. If the spawned object begins hidden, provide `OnAnimatorActivateThrowableObject` or a duration before the expected reveal. |
## Saving and multiplayer
The Character Item or prefab serializes the action, module order, thrown prefab, perspective properties, trajectory values, and event timing. Item Ammo is the Inventory amount of the Character Item's Item Identifier and can be persisted through the inventory/save integration. A pre-spawned held object, an active throw, a cooking fuse, pending animation events, and re-equip progress are transient runtime state; restore the durable inventory result and restart any interrupted presentation deliberately after load.
The multiplayer integration network-spawns the thrown prefab from the authority and lets the server manage the projectile. Built-in Throw Effects also have an explicit network invocation path. A custom impact caller, Item Effect, pickup, or grenade result is not replicated merely because it belongs to this action. Test inventory consumption, projectile authority, collision/explosion damage, pin and perspective visuals, re-equipping, and interruption on the owner, server, and remote clients.
## Related tasks
- [Usable Action](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/) explains Trigger choices, Use timing, Action IDs, and the shared module lifecycle.
- [Use](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/use/) and [Aim](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/aim/) configure the interacting item abilities.
- [Common Item Setups](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-creation/common-setups/) provides practical Character Item creation routes.
- [Trajectory Object](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/) configures the simulated path and moving object's collision behavior.
- [Grenade](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/grenade/) configures the timed thrown prefab, pin, and destruction result.
- [Explosion](https://opsive.com/support/documentation/ultimate-character-controller/objects/explosions/) configures the spawned overlap, damage, force, and effects.
- [Item Pickup](https://opsive.com/support/documentation/ultimate-character-controller/objects/object-pickup/item-pickup/) returns an Item Identifier amount to an Inventory.
- [Action Module Groups](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/) explains module order, States, and custom modules.
- [Item Effects](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/item-effects/) configures release feedback on the action.
- [Animation Event Trigger](https://opsive.com/support/documentation/ultimate-character-controller/animation/animation-event-trigger/) explains timed and Animator-event synchronization.
- [Animator Parameters](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/animator-parameters/) explains the Item State and Item Substate Index used by the throw and re-equip animations.
## Developer reference
`ThrowableAction` extends `UsableAction` and exposes `ThrowerModuleGroup`, `AmmoModuleGroup`, `ProjectileModuleGroup`, `ThrowEffectGroup`, `ImpactModuleGroup`, `ReequiperModuleGroup`, and `ExtraModuleGroup`. `MainThrowerModule`, `MainAmmoModule`, `MainProjectileModule`, and `MainReequiperModule` return the first enabled module. Runtime state is available through `IsThrowing`, `WasThrown`, `IsReequipping`, `RemainingAmmoCount`, `InstantiatedTrajectoryObject`, and `ThrowableObjectIsVisible`; `GetThrowPreviewData()` returns the current preview data.
The action raises `OnThrowEvent(ThrowableThrowData)`, `OnThrowUnityEvent`, and `OnReequipThrowableItemEvent`. The [Event System](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/) also publishes `OnThrowableItemAmmoChange(CharacterItem, ThrowableAmmoModule)`. The core animation event names are `OnAnimatorItemUse`, `OnAnimatorItemUseComplete`, `OnAnimatorActivateThrowableObject`, `OnAnimatorItemRemovePin`, and `OnAnimatorReequipThrowableItem`.
---
# Magic
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/magic/)
The Magic Action builds a spell from reusable casting, presentation, and impact modules. Use it for a Fire Wand projectile, a targeted effect, an area spell, a channeled beam, or a teleport instead of writing one item action for every spell.
## Before you begin
- Create the Character Item and add a **Magic** action through **Tools > Opsive > Ultimate Character Controller > Item Manager**. The [magic anchor setup](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-creation/common-setups/#magic-with-transform-anchors) is useful when a spell has no visible held model.
- Add or select the character's [Use item ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/use/). Its **Action ID** must match this Magic Action's **ID**, and its **Slot ID** must include the Character Item's slot.
- Add first- and third-person cast-origin transforms when effects should start from a hand, wand tip, or staff. **Character As Cast Origin** can be used for a body-centered spell.
- Add the required Animator states or use tested durations for the Use and cast event triggers. See [Animation Event Trigger](https://opsive.com/support/documentation/ultimate-character-controller/animation/animation-event-trigger/).
- If the spell spends mana, create the Attribute on the character before configuring **Character Use Attribute**. See [Attributes](https://opsive.com/support/documentation/ultimate-character-controller/attributes/).
## Build a Fire Wand spell
1. In the Item Manager, add a **Magic** action named `Fire Wand`, then select **Build Item** or **Update Item**.
2. Select the generated Character Item. Give the Magic Action a unique **ID**, then point the character's Use ability at that value. Released Version 3 leaves an Item-Manager-created Magic Action at the default ID `0`, unlike the other generated actions.
3. In **Trigger Action Module Group**, add **Simple** and make it the first enabled Trigger. A generated Magic Action does not receive a Trigger automatically.
4. In **Usable Action Module Group**, add **Character Use Attribute** when the spell should spend mana. Set **Character Use Attribute Name** to the exact character Attribute name and choose the amount spent by one use cycle.
5. In **Caster Module Group**, add **Simple Caster**. Leave **Direction** at **Forward** for a wand projectile, keep **Use Look Source** enabled, and assign the first- and third-person **Cast Origin** values. Only the first enabled Caster is active.
6. In **Begin Module Group**, optionally add a short **Play Audio Clip**, **Spawn Particle**, **Fade Materials**, **Toggle GameObject**, or **Generic Item Effects** row for the wind-up. These rows start with item use and stop when casting begins.
7. In **Cast Effects Module Group**, add **Spawn Projectile**. Assign a pooled projectile prefab with a `Projectile` component, then set its **Speed**, offsets, and **Parent To Origin** choice. The default speed is `1`, so tune it for the scene scale.
8. In **Impact Module Group**, add **Generic Magic Impact Module**. Its released-Version-3 defaults include the standard conditions and a default damage Impact Action group; replace or tune those actions for the spell.
9. In **End Module Group**, add only feedback that belongs after casting, such as a stop sound or object toggle. End modules start when casting stops and stop when item use ends.
10. Save the Character Item prefab and confirm that the Use, cast-start, cast-repeat, cast-end, and completion timing matches the spell's animations.
The legacy Inspector below shows a Teleport example with Simple Trigger and Caster modules, Begin feedback, three Cast Effects, and an End fade. Empty Impact and Extra groups are valid when the spell does not use them.
## Understand the module groups
| Group | Active-module rule | Responsibility |
| --- | --- | --- |
| **Trigger** | First enabled module | Decides whether one input performs a simple, repeat, burst, charged, or combo use cycle. |
| **Usable** | Every enabled compatible module | Applies shared item effects, Attributes, aiming substates, States, and other [Usable Action](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/) behavior. |
| **Caster** | First enabled module | Creates the cast origin, direction, target list, timing, and stop behavior. Released Version 3 includes **Simple Caster**. |
| **Begin** | Every enabled module | Runs presentation while the spell is winding up. |
| **Cast Effects** | Every enabled module | Produces the spell result and reports when its work is complete. |
| **Impact** | Every enabled module | Responds when a Cast Effect supplies an impact. Adding an Impact module does not detect a hit by itself. |
| **End** | Every enabled module | Runs presentation between the end of casting and the end of item use. |
| **Extra** | Every enabled module | Extension point for project-specific Magic modules. Released Version 3 has no concrete built-in Extra module. |
Module IDs identify rows for States and network bitmasks; the Magic Action **ID** is the value selected by the Use ability. Keep action IDs unique across one Character Item.
## How it runs
1. **Start Use** puts the Magic Action in its Begin phase and starts every enabled Begin module using preview cast data.
2. The shared Use and Trigger timing releases the action. **Simple Caster** checks grounding and target validity, creates `MagicCastData`, enters the Casting phase, and stops the Begin modules.
3. **Start Cast Event Trigger** releases every enabled Cast Effect. Each effect moves through pending, processing, and complete states while the Caster updates it.
4. A Physics Cast, Target Impact, projectile, or another impact-producing effect sends its hit through every enabled Impact module.
5. After the effects complete, the Caster waits for its selected stop timing. It marks the effects as about to stop, enters the End phase, and starts every enabled End module.
6. Item-use completion stops and resets the Cast Effects. **Stop Use** then stops the End modules and clears the current use cycle.
Begin and End use the same module types, but they run in separate phases. Keep the wind-up in Begin and recovery or cleanup in End so an interrupted spell has an understandable result.
## Choose the Simple Caster behavior
The action is invalid until at least one Trigger and one Caster are enabled. **Simple Caster** has the following important released-Version-3 defaults:
| Field | Default | Choose this based on |
| --- | ---: | --- |
| **Start Cast Event Trigger** / **Repeat Cast Event Trigger** / **End Cast Event Trigger** | Timed, `0` seconds | Whether an Animator event or duration controls each transition. The matching events are `OnAnimatorStartCast`, `OnAnimatorRepeatCast`, and `OnAnimatorEndCast`. |
| **Character As Cast Origin** | Off | Off uses the current perspective's **Cast Origin** and falls back to the character transform when it is unassigned. On always uses the character transform. |
| **Require Grounded** | On | Whether the spell may start in the air. |
| **Direction** | **Forward** | How the Caster creates its target position. |
| **Use Look Source** | On | Whether Forward casting follows the camera/look source instead of character forward. |
| **Max Distance** | `100` | Forward reach, Indicate reach, and the Target search radius. |
| **Radius** | `0.1` | Sphere-cast thickness for Forward and Indicate. |
| **Max Angle** | `30` degrees | Total forward target cone; the runtime checks half this value to either side. |
| **Max Collision Count** / **Max Target Count** | `100` / `1` | Search capacity and the maximum number of selected targets. |
| **Use Type** | **Single** | Single ends after one completed cast. Continuous remains active until it is allowed to stop. |
| **Minimum Continuous Use Duration** | `1` second | Minimum hold time for Continuous. Use `-1` to allow the first stop request immediately, or a positive duration. |
| **Continuous Cast** | Off | Whether completed Cast Effects continue receiving updates and can repeat during one cast. |
| **Interrupt Source** | **None** | Optionally force-stop on character movement, damage, or both. Jump and Fall count as movement. |
| **Cast Update On Cast** | Off | Off begins normal effect updates on the next item update; on performs the first update as soon as the start-cast event occurs. |
Choose the direction by the player-facing result:
| Direction | Use it for | Runtime result |
| --- | --- | --- |
| **None** | A body-centered aura or item-only effect | Uses character forward and position without searching for a surface or target. |
| **Forward** | Fireballs, rays, and look-directed spells | Sphere-casts from the look or character direction. With no hit, it uses the point at **Max Distance**. |
| **Target** | Lock-on or multi-target spells | Searches inside **Max Distance**, sorts candidates toward character forward, and supplies up to **Max Target Count** colliders. See the released-Version-3 targeting limitation below before using this for strict selection. |
| **Indicate** | Ground markers and teleport destinations | Requires a surface hit. An optional **Surface Indicator** follows the point and is hidden for remote players. |
For a single Fire Wand projectile, keep **Use Type** at **Single** and **Continuous Cast** off. For a held beam, use **Continuous**, turn on **Continuous Cast**, choose a positive minimum duration or `-1`, and give every repeated effect a deliberate interval. A **Character Use Attribute** charge occurs at the shared Use stage; it does not independently charge every Cast Effect update.
## Choose Cast Effects
Every Cast Effect has **Delay** `0`, **Initial Delay** `-1`, and, for multi-target effects, **Allow Multi Target** enabled by default. The runtime behavior is:
- **Initial Delay** controls the first cast when it is zero or positive. `-1` uses **Delay** for the first cast.
- **Delay** controls repeats after completion. A negative value prevents a repeat, `0` permits a repeat on the next eligible cast update, and a positive value waits that many seconds.
- Repeats require the Caster to keep updating the cast, normally with **Continuous Cast** enabled.
Released Version 3's serialized tooltips describe Delay and Initial Delay in the opposite order. Configure them according to the runtime behavior above.
| Cast Effect | Use it for | Important choices and defaults |
| --- | --- | --- |
| **Physics Cast** | Immediate ray, sphere, or area hits | **Mode** defaults to Raycast; **Distance** and **Radius** both default to `5`; **Max Collision Count** is `50`; **Allow Self Impact** is off. Each hit enters the Impact group. |
| **Play Audio Clip** | Cast-stage audio, including a loop | **Play At Origin** is on, **Loop** is off, and fade-out defaults to `0.1` seconds in `0.05` steps. |
| **Spawn Object** | A temporary prop or persistent spell object | **Parent To Origin** is off and **Destroy On Stop** is on. |
| **Spawn Particle** | A burst, beam, trail, or perspective-aware visual | Can parent to the origin, project direction, clear its parent on stop, scale a renderer to target distance, and fade in or out. |
| **Spawn Projectile** | A moving projectile that reports collisions | Assign a prefab with `Projectile`; **Speed** defaults to `1` and **Parent To Origin** is off. Projectile impacts enter the Magic Impact group. |
| **Start Effect** | A Character Effect that should begin with a cast | Select the Effect and optionally enable **Stop Effect** so cast cleanup stops it. |
| **Target Impact** | Apply the Impact group to the Caster's selected target without another physics query | Uses the current Cast Target Position and target collider data. |
| **Teleport** | Move the character to an indicated valid surface | Rejects slopes beyond the locomotion slope limit and locations without standing space. **Snap Animator** is off. |
| **Cast Item Effects** | Invoke a reusable [Item Effect group](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/item-effects/) | **Block Until Effects Can Be Used** is off. Enable it only when every contained effect must be available before the cast proceeds. |
| **Magic Cast Effect Nester** | Run a combination in parallel or sequence and repeat the combination | Parallel is the default; **Sequential** is off and **Repeat Count** is `0`. Nested effects keep their own timing. |
Use **Generic Magic Impact Module** to run [Impact Action Conditions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/impact-action-conditions/), the successful [Impact Action group](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/impact-actions/), or a separate failure group. Use **Ricochet Impact** when the same cast should find another nearby object and immediately recast its enabled effects from the ricochet data.
## Choose Begin and End feedback
Begin and End both accept every released-Version-3 `MagicStartStopModule`:
| Module | Use it for | Important behavior |
| --- | --- | --- |
| **Generic Item Effects** | Local item-side presentation or a UnityEvent | **On Start** is on and **On Stop** is off by default. |
| **Fade Materials** | Fade character renderers during a phase | Targets `_Color` by default, fades toward alpha `0` at speed `0.02`, and does not revert on stop unless enabled. |
| **Play Audio Clip** | Wind-up or recovery audio | **Play At Origin** is on and **Loop** is off. Stop ends the active AudioSource. |
| **Spawn Particle** | Spawn one phase-start particle | Can parent the particle to the cast origin, but its Stop callback does not stop, unparent, or return the object; plan explicit particle cleanup. |
| **Toggle GameObject** | Show or hide perspective objects during the phase | Each row selects first- and third-person objects and an on/off result; choose **Toggle On Start**, **Toggle On Stop**, or both. |
Do not use the Start/Stop **Spawn Particle** module as the sole owner of a looping particle. Give the particle its own auto-stop and pool-return behavior, or use another module or project component that explicitly cleans it up.
## Editor checkpoint
Before entering Play Mode, confirm that:
- the Magic Action has a unique **ID** and the Use ability selects it;
- the intended Trigger and Caster are the first enabled rows in their groups;
- each perspective has a valid **Cast Origin**, or the character fallback is intentional;
- **Direction**, grounding, layers, distance, target count, and surface indicator match the spell;
- every Cast Effect has its required prefab, Effect, Item Effect group, audio, or other reference;
- at least one impact-producing Cast Effect exists when the Impact group should run;
- Animator event waits have matching events on the correct slot, or use tested durations; and
- the mana Attribute exists on the owner read by **Character Use Attribute** or **Use Attribute**.
## Verify in Play Mode
1. Equip the Fire Wand, select its Magic Action, expand **Debug**, and press Use once.
2. Confirm Begin feedback starts first, stops at the start-cast event, and one projectile leaves the current perspective's wand-tip origin.
3. Confirm mana decreases by the configured amount once and the projectile's collision invokes the expected damage and surface response.
4. Watch the action move through Begin, Casting, End, and None. No particle, audio loop, temporary object, State, or collision-layer change should remain after Stop Use.
5. Switch perspectives and repeat. The projectile and feedback should use the matching first- or third-person origin without changing the gameplay target.
6. Test a miss, an obstructed target, an invalid teleport slope, an airborne start, movement interruption, and damage interruption for the settings that the spell enables.
7. For Continuous casting, hold longer than **Minimum Continuous Use Duration**, confirm the effect repeats at the configured **Delay**, then release and verify that End and Stop run once.
8. In multiplayer, repeat the test as owner, server, and remote observer, including a multi-target cast.
## Troubleshooting and released-Version-3 limitations
| Symptom | Check | Fix |
| --- | --- | --- |
| The generated Magic Action does nothing | Trigger and Caster groups | The Version 3 Item Builder creates the component but no starter modules. Add at least one enabled Trigger and **Simple Caster**. |
| Use runs the wrong action | Magic Action **ID**, Use **Action ID**, and other Character Item Action IDs | The Version 3 Magic builder leaves the ID at `0`. Assign a unique ID after every build or update and match the Use ability. |
| The first Cast Effect or its repeats occur at the wrong time | **Initial Delay**, **Delay**, and **Continuous Cast** | Ignore the reversed Version 3 tooltips. Use **Initial Delay** for the first cast and **Delay** for repeats; keep **Delay** negative when the effect must not repeat. |
| A Continuous cast never accepts release | **Minimum Continuous Use Duration** | Do not use exactly `0` in released Version 3. The stop condition accepts `-1` or a positive elapsed duration, but not zero. |
| Target mode reuses an old target or selects an occluded candidate | **Direction: Target** after a successful target, then an empty or obstructed scan | Released Version 3 does not clear the cached count on a zero-hit scan and counts in-angle candidates even when its line-of-sight test fails. Use Forward or Indicate when possible, or a custom validated Caster for strict targeting. |
| Character collision remains disabled after a rejected Forward or Indicate position | A Cast Effect validator such as Teleport rejects the candidate | Released Version 3 returns from that validation path before restoring the character collision layer. Avoid a rejecting validator in this path, or restore the collision layer explicitly in project code. |
| A Begin or End particle continues after its phase | Start/Stop **Spawn Particle** ownership | Its Stop callback only clears the cached transform. Configure the particle to stop and return itself, or use explicit cleanup. |
| The Inspector's **On Cast Event** never invokes | Magic Action event selection | Released Version 3 serializes the UnityEvent but never calls it. Register for Event System `OnMagicItemCast` instead. |
| Impact modules never run | Cast Effect type and enabled Impact rows | Add Physics Cast, Target Impact, Spawn Projectile, or another effect that actually calls the Magic Action's impact path; then enable the intended Impact modules. |
| A cast waits forever at start, repeat, or end | Animator events and slot mapping | Add `OnAnimatorStartCast`, `OnAnimatorRepeatCast`, or `OnAnimatorEndCast` to the correct animation, or disable event waiting and use tested durations. |
| A multi-target network cast invokes the wrong remote effect or throws an index error | More targets than Cast Effect modules in a networked cast | Released Version 3 builds the update-stage module bitmask with the target-loop index instead of the module-loop index. Keep authoritative spell results on the owner/server and replicate the result explicitly in project networking code; do not depend on the built-in update bitmask for multi-target spells. |
## Saving and multiplayer
Magic Action fields, module rows, perspective references, and State presets serialize with the Character Item or prefab. Treat the active Begin/Casting/End phase, current target slice, cast IDs and counters, pending timers, spawned transient effects, and current `MagicUseDataStream` as runtime state. Finish or cancel the cast around a save/load boundary instead of expecting it to resume midway.
With the multiplayer integration enabled, authority controls impacts and the action sends explicit network calls for Begin/End modules, Cast Effect start/update/end, impacts, projectiles, particles, and spawned objects where those modules implement support. Custom modules and arbitrary Item Effects are not automatically authoritative or replicated. Test each spell result, interruption, perspective change, and cleanup on every role; apply the multi-target update workaround in the table above.
## Related tasks
- [Create items and reusable magic anchors](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-creation/)
- [Use item ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/use/)
- [Configure the shared Usable Action](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/)
- [Organize Action Module Groups](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/)
- [Configure Item Effects](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/item-effects/)
- [Configure Impact Action Conditions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/impact-action-conditions/)
- [Configure Impact Actions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/impact-actions/)
- [Configure a Projectile](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/projectile/)
- [Map Animator parameters](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/animator-parameters/)
## Developer reference
`MagicAction` derives from `UsableAction`. Its action-specific extension bases are `MagicCasterModule`, `MagicStartStopModule`, `MagicCastEffectModule`, `MagicImpactModule`, and `MagicExtraModule`. A custom Caster supplies `MagicCastData`; the released type contains `CastOrigin`, `CastPosition`, `Direction`, `CastTargetPosition`, `StartCastTime`, `TargetIndex`, `Targets`, `CastID`, `CastNormal`, and `DetectLayers`.
`MagicAction.MainMagicCaster` is the first enabled Caster. `PerformImpact` builds or adopts an `ImpactCallbackContext`, assigns the cast ID as the source ID, and sends the context to enabled Impact modules. `MagicCastEffectModule` exposes `IsValidTargetPosition`, `StartCast`, `OnCastUpdate`, `OnCastLateUpdate`, `CastWillStop`, and `StopCast`; `MagicMultiTargetCastEffectModule` maintains one completion cache per supplied target.
The [Event System](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/) publishes:
- `OnMagicItemCast(CharacterItem)` after all effects report a completed cast;
- `OnMagicItemStartStopBeginEndActions(CharacterItem, bool beginActions, bool start)` whenever a Begin or End group starts or stops; and
- `OnAnimatorStartCast`, `OnAnimatorRepeatCast`, and `OnAnimatorEndCast` for the Simple Caster's animation-event triggers.
Use those Event System callbacks for project integrations. The serialized **On Start Stop Begin End Actions Event** is invoked, but the serialized **On Cast Event** has the released-Version-3 limitation described above.
---
# Shield
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/shield/)
The Shield Action turns an equipped item's visible collider into physical protection. It can absorb all or part of eligible damage, spend item durability, and request a block or parry reaction from the character's Block ability.
## Before you begin
A Shield Action is different from the character Health component's **Shield Attribute**. The Shield Action protects only through its equipped **Shield Collider**; the Health shield is a general value consumed by the Health damage pipeline.
Prepare these parts:
- A Character Item with a visible first-person and/or third-person shield object.
- A Collider and **Shield Collider** on the same visible GameObject. Built-in Simple Damage looks for the Shield Collider on the reported impact Collider object, not on one of its parents.
- A character with Inventory and Ultimate Character Locomotion item support.
- A **Block** Item Ability when the character should play a reaction. Damage absorption itself does not require Block.
- Animator states for the supplied block/parry item state indexes when an animated reaction is required.
- An attacker whose impact uses the built-in **Simple Damage** action, or custom damage code that deliberately calls the Shield Action. Direct Health damage does not discover a Shield Collider automatically.
## Build a shield with the Item Manager
1. Open **Tools > Opsive > Ultimate Character Controller > Item Manager**.
2. Create a Character Item or select an existing one. Assign the visible shield model for every supported perspective.
3. Under **Actions**, select **+**, choose **Shield**, and enter a useful action name.
4. Select **Build Item** for a new Character Item or **Update Item** for an existing one.
5. Select the main Character Item GameObject. Confirm it has a **Shield Action** with an **ID** that is unique among that item's actions. Block selects shields by item slot rather than Action ID, but the ID must still remain unique for the Character Item lookup.
6. Confirm the generated item has an **Attribute Manager** with a `Durability` Attribute. A fresh generated Attribute starts at minimum `0`, maximum `100`, current value `100`, and no automatic update.
7. Select each visible shield object. Confirm **Shield Collider > Shield Action** points to the generated action and a Collider is on that same GameObject. Resize the Collider to cover only the defensive surface.
8. Keep **Disable On Unequip** enabled unless a holstered shield should deliberately keep receiving hits.
9. If the item was built directly below a character, confirm Item Manager added **Block** to **Ultimate Character Locomotion > Item Abilities**. A reusable Character Item prefab has no parent character, so add Block to each character that equips it.
Item Manager adds a Box Collider when the visible shield object does not already have one. Replace or resize that starting collider when another shape matches the model better.
## Configure the Shield Action
Unlike Shootable, Melee, Throwable, and Magic actions, Shield Action has no Action Module Groups. Configure its protection fields directly on the component; the attacking action's Impact Action Group still determines how the hit and Simple Damage are reported.
| Field | Released-Version-3 default | Behavior |
| --- | --- | --- |
| **Require Aim** | Off | When on, protection and the reaction require an accepted Aim state. |
| **Absorption Factor** | `1` | `1` absorbs all eligible damage, `0` passes all damage through, and values between them split the amount. |
| **Absorb Explosions** | Off | When off, an impact whose source component is the built-in `Explosion` bypasses the shield. |
| **Apply Impact** | On | Starts the impact Animator/audio state and sends the event that asks Block to react. Absorption still works when this is off. |
| **Impact Animator Audio State Set** | Sequence selector | Selects the shield's Item Substate Index, State, and audio for each reaction. Add at least one configured state. |
| **Impact Complete Event > Wait For Animation Event** | Off | When off, Block completes the reaction after **Duration**. When on, an Animator event completes it. |
| **Impact Complete Event > Duration** | `0.2` seconds | Fixed-time fallback when not waiting for an Animator event. |
| **Impact Complete Event > Wait For Slot Event** | Off | Requests a slot-specific completion event. Keep this off in released Version 3; see the limitation below. |
| **Durability Attribute Name** | `Durability` | Exact name of an Attribute on an Attribute Manager on the Character Item. Empty or unresolved means the shield does not degrade. |
| **Drop When Durability Depleted** | Off | Removes one inventory amount and force-drops the Character Item when its durability reaches the minimum through damage. |
### Size and equip the Shield Collider
**Shield Collider** exposes two fields:
| Field | Default | Behavior |
| --- | --- | --- |
| **Shield Action** | None | Must reference the Shield Action on the main Character Item GameObject. |
| **Disable On Unequip** | On | Disables the Collider while this Character Item is not active. |
At runtime the component classifies itself as first person when it is on or below the visible first-person object; otherwise it is treated as third person. Only the Collider for the active perspective is enabled. Remote multiplayer characters are treated as third person by this component.
Keep **Disable On Unequip** on for normal equipment. Turning it off lets the Collider remain enabled while holstered whenever its perspective is active, so it may intercept damage even though the item is not equipped.
### Choose absorption and durability
For an eligible incoming amount, the Shield Action calculates:
```text
requested absorption = incoming damage * Absorption Factor
absorbed damage = minimum of requested absorption and current durability
damage passed to the character = incoming damage - absorbed damage
```
When **Durability Attribute Name** is empty or does not resolve, the shield is non-degrading and applies the absorption factor without spending a value. When the Attribute exists at its minimum, it absorbs nothing and the complete amount passes through. A partially depleted shield absorbs only the value it has left.
The generated `Durability` Attribute belongs to the Character Item, not the character. Configure its range and starting value on that item's Attribute Manager. Do not select the similarly named Health **Shield Attribute** unless the character also needs a separate general-purpose shield value.
### Configure the block or parry reaction
The **Impact Animator Audio State Set** starts when an eligible hit reaches a Shield Action with **Apply Impact** enabled. A new state row starts **Enabled**, allows movement, does not require grounded, has an empty **State Name**, uses **Item Substate Index** `0`, and has no selected Audio Config or clips. Configure the row to match the shield reaction implemented by the Animator.
The Block Item Ability starts and stops manually in response to Shield impacts. Its important defaults are:
| Block field | Default | Choice |
| --- | --- | --- |
| **Start Type** | Manual | Shield impacts start the ability; do not assign a player input. |
| **Stop Type** | Manual | The configured impact completion stops each reaction. |
| **Slot ID** | `-1` | Respond to shields in every inventory slot. Use one exact slot to limit this Block ability. |
| **Block Item State Index** | `8` | Item State Index used by a Shield-only defending item. |
| **Parry Item State Index** | `9` | Used when the defending Character Item also has a Melee Action. |
Parry is an animation choice, not a different damage rule. The same Shield Action performs absorption in both cases. Block does not filter by Action ID or item category, and it declines a new reaction while any Use Item Ability is active.
Use the shared **OnAnimatorItemImpactComplete** event when the animation should end the reaction, or leave event waiting off and tune the `0.2`-second duration. The Block guide covers the Animator parameter and ability-order details.
## How it runs
1. Equip activates the Shield Collider for the current perspective and disables the other perspective. Unequip disables it when **Disable On Unequip** is on.
2. A built-in Simple Damage impact checks the GameObject of its reported **Impact Collider** for **Shield Collider**.
3. Shield Action rejects protection when **Require Aim** is on but the accepted Aim state is absent, or when the source is a built-in Explosion and **Absorb Explosions** is off. The full amount then continues with no shield reaction.
4. With **Apply Impact** on, the action activates its selected State, advances the Animator/audio state set, plays audio on the visible item or character fallback, and sends `OnShieldImpact`.
5. The action applies **Absorption Factor**, subtracts the amount actually absorbed from durability, and returns the remaining damage to Simple Damage.
6. Block receives `OnShieldImpact`. A matching idle Block ability supplies Item State Index `8` for block or `9` for parry, plus the selected impact substate, then updates the Animator.
7. The configured duration or shared Animator event ends the reaction. Block calls `StopBlockImpact`, which clears the Shield Action's impact flag and deactivates its selected State.
8. At minimum durability, later hits pass through. When **Drop When Durability Depleted** is on, the item is removed and dropped when damage consumes the final value.
**Apply Impact** controls presentation, not protection. Turn it off for a shield that should absorb damage without playing a Block reaction.
## Editor checkpoint
Before entering Play Mode, confirm that:
- the Shield Action is on the main Character Item GameObject and has a unique **ID**;
- exactly one intended Attribute Manager contains an Attribute whose name exactly matches **Durability Attribute Name**;
- every perspective's Collider and Shield Collider are on the same visible GameObject and reference this Shield Action;
- each Collider is sized and layered so attacks can report it as the **Impact Collider**;
- **Disable On Unequip** is on for ordinary held equipment;
- a Block ability exists and accepts the Character Item's slot when **Apply Impact** is on;
- the Animator implements item state `8` and/or `9`, the selected impact substate, and the chosen completion timing; and
- attackers use Simple Damage or another explicit Shield Action integration.
## Verify in Play Mode
Use a known `10`-damage hit, watch character Health and item Durability, and keep Block visible in the Ultimate Character Locomotion Inspector.
| Test | Expected result |
| --- | --- |
| **Absorption Factor** `1`, durability above `10` | Durability loses `10`; character Health loses `0`; the reaction runs when **Apply Impact** is on. |
| **Absorption Factor** `0.5`, durability above `5` | Durability loses `5`; character Health loses `5`. |
| Durability has only `3` remaining with factor `1` | Durability reaches its minimum and the remaining `7` damage reaches the character. |
| Durability is already at its minimum | The full `10` reaches the character. The impact reaction can still play because presentation is selected before the durability check. |
| **Require Aim** on | A local player is unprotected without input-started Aim and protected while holding the Aim input. |
| **Absorb Explosions** off, then on | A built-in Explosion bypasses the first test and is absorbed in the second. |
| Switch first/third person, then unequip | Only the active perspective Collider is enabled; both are disabled after unequip when configured normally. |
| Defending item also has a Melee Action | Block supplies parry state `9`; a Shield-only item supplies block state `8`. Absorption remains identical. |
| **Apply Impact** off | Damage is still absorbed, but no impact State, audio, `OnShieldImpact`, or Block reaction starts. |
Repeat the depletion test with **Drop When Durability Depleted** enabled only after the Character Item has a valid Drop Prefab and inventory setup.
## Troubleshooting and released-Version-3 limitations
| Symptom | Check | Fix |
| --- | --- | --- |
| The hit reaches the character instead of the shield | The reported Collider may not have Shield Collider on the same GameObject, or the wrong perspective/unequipped Collider is disabled. | Move Shield Collider onto the Collider GameObject, assign **Shield Action**, resize it, and test the active equipped perspective. |
| A custom attack ignores the shield | Shield absorption is called by built-in Simple Damage, not by Health or every damage source. | Use Simple Damage with a valid **Impact Collider**, or have the custom authoritative damage path call `ShieldAction.Damage` before applying the remainder. |
| Item Manager fails while building a first-person shield with no visible item | Released Version 3 can enter the Shield builder when only **First Person Base** exists, then tries to add Shield Collider to a null **First Person Visible Item**. | Supply a first-person visible shield object, or omit that perspective and add its Collider/Shield Collider manually after the build. |
| An updated item has two Attribute Managers or durability never decreases | Released Version 3 adds a new Attribute Manager for every newly built Shield Action instead of reusing an existing manager. Shield Action reads one manager from the Character Item. | Consolidate the values into one intended Attribute Manager, keep one exact `Durability` entry, and remove the duplicate after checking references. |
| A misspelled durability name makes the shield absorb forever | Empty and unresolved Attribute names are treated as no durability. A missing manager with a nonempty name also logs an initialization error. | Match the Attribute name exactly, or deliberately leave it empty for a non-degrading shield. |
| A non-degrading shield absorbs damage but the attacking melee item does not use its blocked recoil | `DurabilityValue` reports `0` when no Attribute is resolved, and the built-in attacker recoil test requires a value above zero. | Use a real non-depleting/high-value Durability Attribute when the attacker must recognize blocked recoil, or implement a custom recoil test. |
| A regenerating shield drops when durability becomes full | With **Drop When Durability Depleted** on, Shield Action listens to `OnAttributeReachedDestinationValue`; the Attribute sends that event at both minimum and maximum. | Do not combine built-in auto-increase with the drop toggle. Leave dropping off or restore durability through project code that checks the minimum explicitly. |
| The shield absorbs damage but Block never appears | **Apply Impact** may be off, Block may be absent or reject the slot, or Use may currently be active. | Enable **Apply Impact**, add/configure Block, test with Use idle, and verify the Animator state indexes. |
| The shield's impact State remains active | Shield Action activates it before sending `OnShieldImpact`, but only a successful Block completion calls `StopBlockImpact`. A missing/mismatched Block or a Block request rejected during Use can leave it active. | Disable **Apply Impact** when no reliable Block reaction exists, avoid requesting the reaction during conflicting Use flows, or explicitly call `StopBlockImpact` from project cleanup code. |
| Block never completes with a slot-specific event | Released Version 3's slot-event handler rejects the `-1` all-slot configuration and can index outside its one-element arrays for a nonzero fixed **Slot ID**. | Keep **Wait For Slot Event** off. Use **Duration** or the shared **OnAnimatorItemImpactComplete** event. |
| An area hit is absorbed even with **Absorb Explosions** off | The bypass checks whether **Source Component** is the built-in `Explosion` type; a positive impact radius or a custom explosion-like source is not enough. | Identify custom explosion sources before Simple Damage or route them through project code that applies the intended shield rule. |
| Missing Collider causes an exception during initialization | Shield Collider caches `GetComponent()` and immediately controls its enabled state. | Put a Collider on the same GameObject before entering Play Mode. |
| The wrong block/parry animation plays | Block chooses parry whenever the defending Character Item also contains a Melee Action. | Remove the unintended Melee Action or configure the state `9` parry Animator path and the impact substate. |
## Saving and multiplayer boundaries
Shield configuration is serialized on the Character Item prefab or scene object. Runtime durability is an item-side Attribute value, while depletion can also change Inventory and drop state. Shield Action has no built-in save record for its current durability, selected impact state, or in-progress Block reaction. Make the chosen save integration persist and restore the relevant item Attribute and Inventory state, then resume from a neutral reaction state after load.
Shield Action and Block send local Opsive events and contain no damage-authority or replication call of their own. The multiplayer build uses the third-person Shield Collider for remote players, but the authoritative peer must still own the damage calculation, durability change, inventory removal, and drop. Replicate the resulting inventory/Attribute state and any reaction presentation required by other clients through the installed multiplayer integration or project code.
## Related tasks
- [Configure Block and parry](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/block/)
- [Create or update a Character Item](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-creation/)
- [Understand Character Item Actions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/)
- [Configure the Character Item hierarchy](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/)
- [Configure Animator Audio State Sets](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/animator-audio-state-set/)
- [Configure item Attributes](https://opsive.com/support/documentation/ultimate-character-controller/attributes/)
- [Configure Simple Damage and other Impact Actions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/impact-actions/)
- [Configure a Melee Counter Attack](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/use/melee-counter-attack/)
- [Review default Animator values](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/default-animator-values/)
## Developer reference
`ShieldAction.Damage(ImpactCallbackContext ctx, float amount)` returns the amount that remains after shield absorption. `SimpleDamage` calls it when `ctx.ImpactCollisionData.ImpactCollider.gameObject` contains a Shield Collider. Custom callers must provide a complete impact context, including the source component when explosion rules matter.
Useful Shield Action members include **RequireAim**, **AbsorptionFactor**, **AbsorbExplosions**, **ApplyImpact**, **ImpactAnimatorAudioStateSet**, **ImpactCompleteEvent**, **DurabilityAttributeName**, **DropWhenDurabilityDepleted**, the read-only **DurabilityValue**, and `StopBlockImpact()`.
The reaction uses these local events:
- `OnShieldImpact` with `(ShieldAction, ImpactCallbackContext)` starts Block after the Shield Action has selected its impact state.
- `OnAimAbilityStart` with `(bool aim, bool inputStart)` updates **Require Aim** eligibility.
- `OnAnimatorItemImpactComplete` ends reactions that use the shared Animator event.
- `OnAnimatorItemImpactCompleteSlot` is the intended slot-specific event, subject to the released-Version-3 limitation above.
- `OnInventoryEquipItem`, `OnInventoryUnequipItem`, and `OnCharacterChangePerspectives` control Shield Collider availability.
`WaitingForImpactCompleteEvent` exposes the trigger object's `IsWaiting` flag, but released Version 3 Block schedules its own duration or listens for Animator events without calling `ImpactCompleteEvent.WaitForEvent()`. Do not use that property as a reliable reaction-running indicator; inspect Block activity or maintain explicit project state instead.
---
# Action Modules & Groups
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/)
Action Modules let you change one stage of an item action without replacing the complete action. Use them to choose how a firearm fires, how an Iron Sword detects a hit, what an impact does, when an effect runs, or whether a use is allowed.
## Understand groups and modules
An Action Module is serialized inside a Character Item Action component; it is not another component on the item. Its Action Module Group determines which module types are valid and when they are called.
| Level | Responsibility |
| --- | --- |
| **Character Item Action** | Owns the complete operation, such as Shootable or Melee, and provides the Character Item, character, inventory, slot, and perspective context. |
| **Action Module Group** | Owns an ordered list for one stage, such as Trigger, Shooter, Collision, Impact, or Reload. The Inspector only offers module types compatible with that group. |
| **Action Module** | Implements one option in the stage. It can respond to lifecycle or action interfaces, use States and bindings, and access its owning action's context. |
| **Nested action/effect group** | Lets a module run an ordered set of Impact Actions, Impact Action Conditions, or Item Effects without turning each entry into another Action Module. |
The group owns the row order. Some stages invoke every enabled, active module that implements the requested interface. Others deliberately use the first enabled module as their main option. Order is therefore behavior, not just organization.
## Choose the right extension point
These related systems solve different problems:
| Goal | Use | Guide |
| --- | --- | --- |
| Change how an item starts, fires, collides, reloads, recoils, or performs another action stage | **Action Module** in the matching group | Continue on this page. |
| Apply damage, force, surface effects, events, or other results after a hit | **Impact Action** | [Impact Actions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/impact-actions/) |
| Allow, reject, or branch an impact according to its source or target | **Impact Action Condition** | [Impact Action Conditions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/impact-action-conditions/) |
| Play audio, toggle an object or light, spawn a prefab, or invoke a UnityEvent using item-action context but no hit context | **Item Effect** | [Item Effects](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/item-effects/) |
Use an Action Module when the logic must participate in the item's lifecycle or action sequence. Use the smaller nested types when a module only needs to execute a result or inspect an impact.
## Configure a module group
1. Select the main Character Item GameObject and open its Character Item Action component.
2. Expand the group for the stage you want to change. A Usable action always has **Trigger Action Module Group** and **Usable Action Module Group**; specialized actions add their own groups.
3. Under **Modules**, use the add control and choose a compatible module type. The type picker is constrained by the group, so a Collision module cannot be added to a Shooter group.
4. Select the new row to expose its settings below the list. A new Action Module starts **Enabled**, has an empty **Name**, and declares an **ID** default of `-1`; the released Version 3 Inspector assigns a newly added row the current last index as its ID.
5. Configure the module's required references and gameplay values. Expand **Bindings** when a property should follow an external runtime value, or **States** when named State presets should override values.
6. Drag rows to change their evaluation order. Use the row's **Enabled** toggle to keep a configuration without allowing it to participate.
7. Remove a row only after checking references to its module ID and any helper objects that its editor hook created.
### Understand IDs, order, and repeated types
Module IDs and row order are related when a row is first added, but they are not the same value:
- Adding through the Inspector assigns the new row's ID from its index.
- Reordering rows changes execution priority but does not renumber their IDs.
- Removing a row decrements the IDs of the rows that followed it.
- The Inspector allows more than one module of the same type when the group accepts it.
- Duplicate IDs are not rejected. `GetModuleByID` returns the first match, so keep IDs unique within a group whenever code looks modules up by ID.
Most no-code setups should select modules by their list order and type rather than editing IDs. Review IDs after a remove or reorder if project code stores them.
## Start from a built-in item
The Item Manager supplies a useful starting module set. Tailor that set instead of assembling every stage from an empty action.
| Stage | Firearm starting point | Iron Sword starting point |
| --- | --- | --- |
| Trigger | **Repeat** | **Repeat Combo** |
| Operation | **Hitscan Shooter**, **Item Ammo**, **Simple Clip**, and **Basic Projectile** | **Simple Attack** |
| Detection | Shooter and projectile configuration | **Hitbox Collision** |
| Result | **Generic Shootable Impact Module** | **Generic Melee Impact Module** |
| Feedback | **Muzzle Effect**, **Shell Effect**, **Recoil Effect**, and **Crosshairs Spread** | Attack, recoil, Animator/audio, and impact configuration |
| Follow-up | **Generic Reloader**, dry-fire effects, and slot monitoring | **Simple Recoil** and the next combo state |
For a firearm, first decide whether the shooter is hitscan or projectile based, then configure ammunition, clip, fire effects, impact, and reload around that choice. For an Iron Sword, confirm the hitbox belongs to the visible blade, then configure attack timing, impact results, recoil, and combo behavior.
Adding a second module does not automatically make it a fallback. Check how that group consumes its list: a main-module group may only use the first enabled row, while an interface-driven stage may invoke every matching enabled, active row.
## Use States and bindings
Every Action Module derives from the State and binding system:
- **States** apply serialized preset overrides while a named State is active. Use them for choices such as an alternate damage value, fire rate, effect, or enabled configuration.
- **Bindings** update a module property from an external runtime source. The built-in Attribute binding needs an Attribute Manager, an Attribute name, and a valid property path on the module.
- **Enabled** remains the basic participation gate. A module may also report inactive when its own rules require it to be the first enabled module.
In Play Mode the Inspector adds a status icon to each module row. Use its tooltip to distinguish **Active and Enabled**, **Enabled but Inactive**, and disabled states before changing gameplay values.
## Configure nested impact and effect lists
Impact Actions, conditions, and Item Effects use similar ordered Inspector lists, but their defaults and context differ.
### Impact Actions
An Impact Action starts **Enabled**, with **Delay** `0` and **Allow Multi Hits** disabled. The group invokes entries in list order. Each entry receives an `ImpactCallbackContext`: collision data is required and describes the source, target, hit, direction, strength, and related objects; damage data is optional.
With **Allow Multi Hits** disabled, one source ID cannot invoke the same Impact Action repeatedly on the same target until the group is reset. This is useful for casts that overlap the same collider across frames. A delayed action keeps a duplicate of the context until it runs and releases it during cleanup.
### Impact Action Conditions
Every enabled condition in a condition group must pass. A disabled condition is ignored. A **Conditional Impact Action** can run one Impact Action group on pass and another on failure; **Reset Damage Data On Fail** clears optional damage data before later processing continues.
Use source category or definition conditions when, for example, only an Iron Sword or only the Weapon category should damage a target. Use the target condition behavior when each target should own its acceptance rules.
### Item Effects
An Item Effect starts **Enabled** with **Delay** `0`. It receives the Character Item Action context but no collision context. The **Generic Item Effects** module can invoke its effect list at start use, use, use update, or use complete according to its toggles.
Choose Item Effects for feedback or simple item-side results. Choose Impact Actions when the result needs a hit target, damage data, surface information, or multi-hit control.
## How it runs
1. The Character Item Action collects its module groups in their declared order and assigns each group a runtime ID from that order.
2. Every module is initialized with its owning action and group, including disabled modules. This gives it access to the Character Item, character, Inventory, Slot ID, perspective, and installed network bridge before action execution begins.
3. Each group caches its enabled and disabled rows in list order. Changing **Enabled** in Play Mode refreshes those caches.
4. Pickup, equip, start-unequip, unequip, removal, and destruction notifications pass through the action to its modules. The base module registers runtime listeners only while it is both enabled and equipped.
5. During an action, the Character Item Action invokes modules by interface. Disabled modules are skipped; modules whose active rule fails are skipped; matching active modules run in group and row order unless the action explicitly asks for the first enabled option.
6. A collision module can pass an `ImpactCallbackContext` to an Impact Action group. Conditions inspect that context, then enabled Impact Actions run in order or after their configured delay.
7. A Generic Item Effects module invokes its enabled Item Effects at the configured use stage. Delayed built-in effects and impacts cancel scheduled work during destruction.
Do not call lifecycle hooks directly from ordinary gameplay code. Let the Character Item Action and its Item Ability coordinate them so equip state, Animator timing, interruption, and multiplayer integration remain consistent.
## Editor checkpoint
Before entering Play Mode, verify all of the following:
- Every module is in a compatible group and the intended main module is the first enabled row where that stage uses one main option.
- Repeated module types are deliberate, and no group contains duplicate IDs used by project code.
- Required first- and third-person locations, colliders, projectiles, attributes, audio, effects, and Item Identifiers are assigned.
- States have the intended presets and activation names. Bindings reference a valid source and writable module property.
- Impact lists place modifiers and conditions before the results that depend on them.
- **Allow Multi Hits**, **Delay**, and **Reset Damage Data On Fail** match the desired hit behavior.
- Animator/audio state sets and use events match the clips and event timing used by the item.
## Verify in Play Mode
1. Equip the item and confirm the intended module rows report active and enabled.
2. For a firearm, fire once with ammunition and once with an empty clip. Confirm the main Trigger, shooter, ammo, clip, fire or dry-fire effects, impact, and reload stages each produce the expected result.
3. For an Iron Sword, swing across one target and keep the hitbox overlapping for several frames. Confirm the attack produces the intended single impact when multi-hit is disabled and can hit again after the action resets.
4. Activate each relevant State or change the bound source. Confirm the visible module value and gameplay result change together.
5. Disable one feedback module at runtime. The action should continue without that module's audio, visual, recoil, or other contribution.
6. Unequip and re-equip. Event-driven modules should not react while unequipped and should register again after equip.
7. In multiplayer, repeat the visible result as owner and remote observer. Verify each custom effect, spawned object, and damage result that other peers must see is explicitly synchronized.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| The desired type does not appear in the add menu | The selected Action Module Group | Add it to a group whose declared module base type accepts it, or create a wrapper module for that group. |
| The configured module never runs | **Enabled**, Play Mode status icon, State overrides, and list order | Enable it, make its controlling State valid, and move it before another module when the stage uses the first enabled row. |
| Two copies of a module produce duplicate results | Repeated types and whether the stage invokes every matching interface | Remove or disable the unintended row. Keep multiple copies only when both results should run. |
| Custom code retrieves the wrong module | Duplicate module IDs | Assign unique IDs within that group. ID lookup returns the first matching row. |
| Project code stops finding a module after list edits | IDs after remove or reorder | Review stored IDs. Removal decrements later IDs; reordering changes row priority without changing IDs. Prefer type-based lookup when a stable numeric contract is unnecessary. |
| A firearm or throwable prefab has empty fire, muzzle, throw, trajectory, or hitbox references | Whether the module was added to a GameObject that is part of a prefab | Released Version 3's built-in editor hooks do not automatically create those helper objects on prefab assets or instances. Add the locations or colliders manually and assign both perspective values, or configure a non-prefab item through Item Manager before saving it as a prefab. |
| A hit occurs but damage or an effect does not | Impact context, enabled conditions, action order, and optional damage data | Inspect the context with a debug Impact Action, correct the failed condition, and place modifiers before actions that consume their result. |
| The same cast never hits the target again | **Allow Multi Hits** and the source-ID reset point | Enable multi-hit only when repeated hits are intended, or ensure the owning collision/action module resets its Impact Action group between attacks. |
| A delayed custom result survives cleanup | The custom type's `OnDestroy` implementation | Cancel scheduled work and call the base cleanup where applicable. Built-in delayed Impact Actions and Item Effects already cancel their scheduled callbacks. |
| A custom result appears only for the owning player | Network authority and replication | Use the installed network bridge where the built-in module supports it, and explicitly synchronize project-specific damage, spawned objects, UnityEvents, and mutable state. |
## Saving and multiplayer boundaries
Module, State, binding, Impact Action, condition, and Item Effect configuration is serialized with the Character Item scene object or prefab. Runtime module values, delayed work, hit history, custom counters, and other transient state are not a general save record. Add explicit save/restore support for custom runtime data that must survive loading.
When multiplayer support is compiled, an Action Module can access the owning action's network information and network inventory bridge. The base module's `NetworkSync` value defaults to false, and serializing a module does not replicate its behavior. Built-in modules synchronize only the paths implemented by the installed integration; custom effects and state need a deliberate authority and replication design.
## Related tasks
- [Item Actions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/) explains action IDs, Item Ability selection, and the complete action lifecycle.
- [Usable](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/) explains the common Trigger and Usable groups and their start/use/complete sequence.
- [Shootable](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/shootable/) covers firearm-specific module groups.
- [Melee](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/melee/) covers attack, collision, impact, and recoil groups for an Iron Sword.
- [Animator Audio State Set](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/animator-audio-state-set/) explains animation and audio selection used by many trigger and feedback modules.
## Developer reference
Choose the narrowest group base class and lifecycle interface for a custom module. For example, a Usable module that runs at the use point can implement `IModuleUseItem`:
```csharp
[Serializable]
public class DebugUse : UsableActionModule, IModuleUseItem
{
[Tooltip("The message to print when the item is used.")]
[SerializeField] private string m_Message = "Item used";
public void UseItem()
{
Debug.Log(m_Message, CharacterItemAction);
}
}
```
The type must be serializable for its fields to appear and persist. Use `InitializeInternal` for cached references, `UpdateRegisteredEventsInternal` for listeners that should exist only while enabled and equipped, and the pickup/equip/unequip/remove/destroy hooks only when that lifecycle stage is required. If one implementation must appear in several incompatible groups, keep the shared logic in a separate class and add a small group-specific module wrapper for each supported group.
`CharacterItemAction.GetFirstActiveModule()` returns the first enabled, active match across groups. `InvokeOnModulesWithType()` invokes every enabled, active module implementing the requested interface in group and row order. A group also exposes `GetModuleByID`, but IDs should remain unique when using that lookup.
---
# Impact Actions
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/impact-actions/)
Impact Actions turn one reported hit into gameplay results such as damage, force, particles, audio, states, or callbacks. Use an ordered Impact Action Group on a melee, shootable, throwable, or magic module so an Iron Sword, firearm, or explosion produces the same deliberate result every time.
## Configure an Impact Action Group
1. Select the Character Item and expand the module that reports the hit.
2. Expand **Impact Actions**. Use **Fail Impact Actions** only when the module's condition list needs a separate rejected-hit result.
3. Add actions with the **+** button and drag them into execution order.
4. Put gameplay changes first, presentation second, and callbacks last. A typical firearm order is **Simple Damage**, **Spawn Surface Effect**, **Spawn Particle** or **Play Audio Clip**, then **Impact Event**.
5. Configure the fields that the chosen action actually uses. An action with zero force, no prefab, an empty state name, or no event listener may run successfully without producing a visible result.
The legacy Inspector image remains accurate for released Version 3. The list is configurable; it is not the default group created by current source.
## Shared controls and ordering
Most actions expose the same controls before their type-specific fields:
| Field | Default | Behavior |
| --- | --- | --- |
| **Enabled** | On | A disabled action is skipped. |
| **Delay** | `0` seconds | Zero runs immediately. A positive value schedules that action independently. |
| **Allow Multi Hits** | Off | When the caller honors repeat tracking, the action remembers each target by **Source ID** until that ID is reset. |
| **Bindings** and **States** | Empty/default | Optional property bindings and State System overrides inherited by the action. |
An Impact Action Group visits its actions from top to bottom. Immediate actions share the same mutable `ImpactCallbackContext`, so an earlier action or callback can affect what a later action reads. A delayed action takes its own pooled snapshot when its row is reached; the group does not wait for it, and later zero-delay rows can finish first. Use **Delay** as timing, not as a sequencing guarantee.
**Allow Multi Hits has an important released-Version-3 boundary:** the built-in generic Melee, Shootable, Throwable, and Magic impact modules call their groups with forced impact enabled. Their actions therefore bypass the repeat suppression even when **Allow Multi Hits** is off. Use the module's hit detection/cooldown rules for those standard weapon flows. The toggle still matters for callers that pass forced impact as false, including receiver, nested conditional, and custom flows.
## Choose actions by outcome
Released Ultimate Character Controller Version 3 provides 17 concrete Impact Action types. The catalog below covers every one.
### Apply damage, healing, attributes, or states
**Simple Damage**
Use **Simple Damage** for a firearm hit, Iron Sword strike, or explosion that should affect an `IDamageTarget` and optionally push a non-damageable physics object.
| Field | Default | Meaning |
| --- | --- | --- |
| **Use Context Data** | Off | When on and `ImpactDamageData` exists, reads its processor, damage, force, force frames, and radius instead of the local values. |
| **Set Damage Impact Data** | On | Displayed in the Inspector, but released Version 3 does not read this field or write damage data from it. |
| **Invoke On Object Impact** | Off | Sends `OnObjectImpact` callbacks to the hit collider object, its distinct Rigidbody object, and the restored target when applicable. |
| **Damage Processor** | None | Uses `DamageProcessor.Default` when no local or context processor is supplied. |
| **Damage Amount** | `10` | Local damage before shield and optional strength scaling. |
| **Impact Force** | `2` | Force magnitude multiplied by **Impact Strength**. |
| **Impact Force Frames** | `15` | Character force duration. |
| **Impact Radius** | `0` | A positive radius changes Rigidbody force to explosion force. |
| **Scale Damage By Impact Strength** | Off | Multiplies damage by **Impact Strength**; useful for explosion falloff. |
The action lets a `ShieldCollider` adjust the damage, resolves an `IDamageTarget`, then uses a source `DamageProcessorModule`, the selected **Damage Processor**, or the default processor. When no damage target exists, it applies force to a parent `IForceObject` or the reported non-kinematic Rigidbody.
Supply a valid **Impact Collider**. The released action reads its GameObject during the shield check even when the hit has no shield.
In released Version 3, **Set Damage Impact Data** is serialized but unused. Populate `ImpactDamageData` in the source module/custom context when later actions need shared values, or leave **Use Context Data** off and use this action's local fields.
When **Invoke On Object Impact** is enabled and the original target is also the collider's attached Rigidbody GameObject, that GameObject can receive the callback once as the Rigidbody and again as the restored target. Prefer a single **Impact Event** target callback when a receiver must run exactly once.
**Heal**
**Heal** searches the target and then its parents for `Health`.
- **Amount** defaults to `10`.
- **Interrupt Impact On Null Health** defaults to on.
When Health is missing or refuses the heal, released Version 3 emits the source event named `ImpactInteruptedCallback`. The Impact Action Group itself does not stop and the package contains no built-in listener that stops later rows. Put **Heal** last when later actions must not run on failure, or use a condition/custom flow to select the result.
**Modify Attribute**
**Modify Attribute** searches the target's parents for an `AttributeManager`, clones the configured modifier from a pool, and changes the named attribute.
| Attribute Modifier field | Default |
| --- | --- |
| **Attribute Name** | Empty |
| **Amount** | `0` |
| **Auto Update** | Off |
| **Auto Update Start Delay** | `1` second |
| **Auto Update Interval** | `0.1` seconds |
| **Auto Update Duration** | `-1` |
An empty or unknown name does nothing. For a one-time stamina, mana, or shield change, leave **Auto Update** off. Released Version 3 registers timed modifier cleanup with `OnAttributeModifierAutoUpdateEnable` but the modifier emits `OnAttributeModifierAutoUpdateEnabled`; positive-duration auto updates therefore miss the cleanup callback. Use an immediate change here or a purpose-built timed attribute workflow until that package behavior is corrected.
**State Impact**
**State Impact** activates a State on the character root containing the target, or on the target itself when it is not part of an Ultimate Character Locomotion object.
- **Use Context Data** defaults to off.
- **Impact State Name** defaults to empty.
- **Impact State Disable Timer** defaults to `10` seconds. Set it to `-1` for manual deactivation.
When **Use Context Data** is on and damage data exists, both the name and timer come from that data. An empty context state name does not fall back to the local name.
**Character Knock Back**
**Character Knock Back** finds the target's parent Ultimate Character Locomotion and starts its **Impact Knock Back** ability.
- **Impact Knock Back ID** defaults to `0` and selects the response animation/configuration.
It does nothing when the target is not a character or does not have the ability.
### Apply physical motion
**Add Force**
**Add Force** prefers the target's parent Ultimate Character Locomotion, then a parent `IForceObject`, then the reported non-kinematic Rigidbody.
| Field | Default |
| --- | --- |
| **Use Source Direction** | Off |
| **Amount** | `(0, 0, 0)` |
| **Frames** | `5` |
| **Mode** | `Force` |
| **Add Force At Position** | Off |
With **Use Source Direction** off, the action scales **Amount** component-by-component with **Impact Direction**. With it on, it transforms **Amount** through the source GameObject. In both cases **Impact Strength** scales the amount. When context damage data has a positive **Impact Radius**, the Rigidbody path uses the squared magnitude of the strength-scaled **Amount** as explosion force and does not use **Mode** or **Add Force At Position**.
**Frames** applies to character and `IForceObject` paths. **Mode** and **Add Force At Position** apply only to the ordinary, non-explosion Rigidbody path.
**Add Torque**
**Add Torque** applies angular force with:
- **Amount** `(0, 0, 0)` by default.
- **Mode** `Force` by default.
Unlike **Add Force**, it looks for a Rigidbody directly on **Impact GameObject**, does not use the reported **Impact Rigidbody**, and does not scale by **Impact Strength**. Place the Rigidbody on the reported target or use a custom action when the collider reports a child object.
### Spawn surface, visual, and audio feedback
**Spawn Surface Effect**
**Spawn Surface Effect** asks the Surface Manager to select the configured effect for the hit.
- **Use Context Data** defaults to off.
- **Surface Impact** defaults to None.
When context use is enabled, a non-null context **Surface Impact** overrides the local asset; otherwise the local value is the fallback. The action uses the collision's `RaycastHit`, the source character's gravity and time scale, and the visible source item or source GameObject as originator. It suppresses a non-shield surface effect when context damage is exactly zero.
Supply a valid `RaycastHit`; a context built only from **Impact Position** is not sufficient. Also supply **Impact Collider** when context damage exists with an amount of zero, because the released suppression check reads that collider.
**Spawn Particle**
**Spawn Particle** creates a pooled particle at **Impact Position**, oriented along **Impact Direction**.
| Field | Default |
| --- | --- |
| **Particle Prefab** | None |
| **Position Offset** | `(0, 0, 0)` |
| **Rotation Offset** | `(0, 0, 0)` |
| **Parent To Impacted Object** | Off |
The prefab must contain a `ParticleSystem`. A looping particle is cached per **Source ID**, repositioned on another invocation with that ID, and stopped when the action is reset. Provide a nonzero impact direction so the rotation is well-defined.
**Play Audio Clip**
**Play Audio Clip** contains one **Audio Clip Set**, which can reference an **Audio Config** or an **Audio Clips** list and selects a random clip from that set. A newly added set has no selected config or clips.
Released Version 3 plays at `RaycastHit.point`, not **Impact Position**. This works for normal raycast firearm/melee contexts. For a manually constructed explosion or trigger context without a valid raycast, use a custom audio action at **Impact Position** or supply a valid hit.
**Generic Item Effects**
**Generic Item Effects** owns one **Effect Group** and invokes each configured Item Effect. It does not pass the impact context into those effects. Use it when an existing item effect already expresses the feedback or item-side change; see the separate Item Effects catalog rather than duplicating that configuration here. The group is initialized against the owning Character Item Action, so effects that require an item owner are not suitable for a context with no item action.
### Send callbacks or debug the result
**Impact Event**
**Impact Event** sends Opsive events through the impact context:
- **Call Impact Callback On Originator** defaults to on and sends `OnObjectImpactSourceCallback` to **Source GameObject**.
- **Call Impact Callback On Target** defaults to on and sends `OnObjectImpact` to **Impact GameObject**.
The originator callback runs first. Put this action after damage and feedback when listeners should observe the completed immediate result. A target-side **Conditional Impact Receiver** depends on the target callback.
A missing source or target logs a warning and skips that callback.
**Impact Unity Event**
**Impact Unity Event** exposes one **On Impact Event** UnityEvent carrying the full `ImpactCallbackContext`. It starts with no persistent listeners. Use it for a local Inspector connection; use **Impact Event** when source or target components listen through the Opsive event system.
**Debug Impact Context**
**Debug Impact Context** has one **Message** field, empty by default. It logs that message followed by the complete context. Place it before and after a suspicious row to compare shared data; remove it from shipping configurations that should not log every impact.
### Branch, reuse, or create secondary hits
**Conditional Impact Action**
**Conditional Impact Action** contains **Conditions**, **Impact Actions On Pass**, **Impact Actions On Fail**, and **Reset Damage Data On Fail** (off by default). Conditions are ANDed and the action invokes exactly one nested group. The fail group is invoked before optional damage-data reset. See [Impact Action Conditions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/impact-action-conditions/) for the complete condition catalog and released-Version-3 branch details.
**Use Impact Action Object**
**Use Impact Action Object** references one **Impact Action Object**, None by default. An `ImpactActionGroupObject` is a ScriptableObject containing a reusable group; create one with **Assets > Create > Opsive > Impact > Impact Action Group Object**. A new asset contains **Simple Damage**, **Spawn Surface Effect**, and **Impact Event**, with the first two configured to read context data.
In released Version 3 the wrapper overrides `TryInvokeOnImpact` and directly calls the asset. Its own displayed **Enabled**, **Delay**, and **Allow Multi Hits** values are not honored. Configure those controls on the actions inside the asset. The asset also owns one stateful set of action instances and reinitializes it for each call, so repeat maps, delayed work, and binding ownership are not isolated between simultaneous users. Use separate runtime assets/instances or a custom cloned group when concurrent characters require isolated state.
**Ricochet**
**Ricochet** finds nearby colliders and raises its C# `OnRicochet` event for each eligible secondary target.
| Field | Default |
| --- | --- |
| **Radius** | `10` |
| **Max Chain Count** | `1` (`-1` disables the limit) |
| **Max Collision Count** | `50` |
| **Merge Data Layers** | On |
| **Detect Layers** | Nothing |
With **Merge Data Layers** on, the local mask is ORed with the context's **Detect Layers**. With it off, a default Nothing mask finds nothing. Queries ignore trigger colliders and use a preallocated array sized by **Max Collision Count**.
The action centers its query on `RaycastHit.point` and raises data; it does not itself cast the next hit. In the released package, the built-in subscriber is the Magic **Ricochet Impact** module. A firearm needs a custom subscriber or its own ricochet module to turn that event into another shot. The implementation also accesses the owning Character Item Action while processing candidates without a null guard, so use this built-in only with an item action owner.
## Scenario recipes
### Firearm hit
1. Use **Simple Damage** with **Use Context Data** on when the shootable module supplies the shot's damage and force.
2. Add **Spawn Surface Effect** with context use on for material-specific feedback.
3. Add **Spawn Particle** for a dedicated impact particle, or **Play Audio Clip** when the hit has a valid raycast.
4. Add **Impact Event** last when the target or source needs a callback.
### Iron Sword strike
1. Use **Simple Damage** for health and force.
2. Add **State Impact** when the target should briefly enter a named hit state.
3. Add **Character Knock Back** only when the target character has the matching ability and ID.
4. Add audio/surface feedback, then **Impact Event**.
Use [Impact Action Conditions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/impact-action-conditions/) when only selected definitions, categories, or targets should take the pass result.
### Explosion
1. Set **Simple Damage > Impact Radius** to a positive value, or enable **Use Context Data** and supply a positive context radius.
2. Enable **Scale Damage By Impact Strength** when the explosion creator supplies falloff as **Impact Strength**.
3. Set **Impact Force** and verify the reported **Impact Rigidbody** or damage target receives it.
4. Add a non-looping **Spawn Particle**. For positional audio from a manually built context, avoid the built-in **Play Audio Clip** raycast-point limitation.
Do not add **Add Force** merely to duplicate the force already applied by **Simple Damage** unless the extra push is intentional.
## Editor checkpoint
Before entering Play Mode, confirm that:
- every action needed for the result is enabled and has a visible, nonzero or assigned value;
- data-dependent actions agree on **Use Context Data** and the source actually supplies `ImpactDamageData`;
- damage actions have a valid **Impact Collider** and every action has a valid **Impact GameObject**;
- **Impact Event** is after immediate gameplay actions when listeners need the final result;
- surface/audio actions have a valid `RaycastHit`, while particles have a valid position and nonzero direction;
- looping particles and repeat-sensitive custom callers reset the same **Source ID** they used for the hit; and
- shared Impact Action Group Objects are not unintentionally serving concurrent owners with stateful actions.
## Verify in Play Mode
Use one known damageable target, one plain Rigidbody, and one target without the expected component.
| Test | Expected result |
| --- | --- |
| Firearm hits the damageable target | Health changes once per module hit, feedback appears at the raycast hit, then callbacks run. |
| Iron Sword hits the character | Damage applies; the configured State or knock-back response appears only when its requirement exists. |
| Explosion reaches near and far targets | Positive radius produces explosion force; strength-scaled damage is lower where the source supplies lower strength. |
| Same group hits a plain Rigidbody | Damage is skipped, but configured force/particle feedback still uses the reported physics data. |
| Heal or Modify Attribute hits a target without its component | No value changes; later rows still run unless the flow explicitly branches. |
| An action has a positive Delay | Later zero-delay rows run first; the delayed result uses its scheduled snapshot. |
Add **Debug Impact Context** temporarily when the observed position, target, source, strength, or optional damage data differs from the expected row.
## Troubleshooting and released-Version-3 limitations
| Symptom | Check | Fix |
| --- | --- | --- |
| **Allow Multi Hits** off still permits repeated standard weapon hits | Generic Melee, Shootable, Throwable, and Magic modules force invocation. | Control repeats in the module's hit detection/cooldown, or use a custom caller that passes forced impact as false. |
| A delayed action sees damage data even though the original context had none | Delayed copies always obtain a pooled `ImpactDamageData`; copying null leaves that object at its current/default values. | Supply explicit damage data before scheduling, or keep actions that depend on optional-null semantics at **Delay** `0`. |
| **Set Damage Impact Data** changes nothing | The Simple Damage field is unused in released Version 3. | Supply context damage data from the source or use local Simple Damage fields. |
| A Conditional Impact Receiver runs twice for one Simple Damage hit | **Invoke On Object Impact** can notify the same attached Rigidbody and restored target twice. | Disable that field and use one **Impact Event** target callback when exactly-once delivery is required. |
| Heal failure does not stop later actions | **Interrupt Impact On Null Health** only emits `ImpactInteruptedCallback`; the group keeps iterating. | Put Heal last or select the result with a condition/custom group. |
| Timed Modify Attribute cleanup never completes | The registered and emitted event names differ by the `d` suffix. | Use an immediate modifier here or implement the timed change outside this action. |
| Audio plays at the world origin | **Play Audio Clip** uses `RaycastHit.point`. | Supply a valid hit or use a custom action at **Impact Position**. |
| Surface effect throws or appears at the wrong point in a manual context | **Spawn Surface Effect** reads **Impact Collider** and `RaycastHit`. | Initialize both values or use a context-appropriate custom effect. |
| Torque does nothing on a child collider | **Add Torque** checks only a Rigidbody directly on **Impact GameObject**. | Report the Rigidbody GameObject as target or use a custom action based on **Impact Rigidbody**. |
| **Use Impact Action Object** ignores its wrapper controls | Its override bypasses base action gating and timing. | Configure the contained actions or use a custom wrapper. |
| Ricochet finds targets but creates no new firearm shots | Only the Magic Ricochet Impact module subscribes in the released package. | Add a firearm-specific subscriber/module. |
| Ricochet throws in a non-item custom context | Candidate processing reads the owning Character Item Action without a null guard. | Invoke it with a valid Character Item Action or implement a context-safe custom ricochet. |
| A particle logs an error | **Particle Prefab** is missing or lacks `ParticleSystem`. | Assign a compatible pooled particle prefab. |
## Related tasks
- [Configure Impact Action Conditions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/impact-action-conditions/)
- [Configure Item Effects](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/item-effects/)
- [Organize Action Module Groups](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/)
- [Configure a Melee Action](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/melee/)
- [Configure a Shootable Action](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/shootable/)
- [Configure a Damage Processor](https://opsive.com/support/documentation/ultimate-character-controller/objects/damage-processor/)
- [Configure Surface Effects](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/)
- [Configure Attributes](https://opsive.com/support/documentation/ultimate-character-controller/attributes/)
- [Configure States](https://opsive.com/support/documentation/ultimate-character-controller/state-system/)
## Developer reference
### Impact callback data
Every action receives an `ImpactCallbackContext` containing:
- the owning **Character Item Action**, when one exists;
- required `ImpactCollisionData`; and
- optional `IImpactDamageData` for values supplied by a weapon, explosion, or custom source.
Current collision data includes **Source ID**, **Detect Layers**, `RaycastHit`, **Impact Position**, **Impact GameObject**, **Impact Rigidbody**, **Impact Collider**, **Impact Direction**, **Impact Strength**, damage target/source, source component/GameObject/character/item action, hit count/colliders, and **Surface Impact**. The old `SourceOwner` and `SourceRootOwner` fields are not members of released Version 3 `ImpactCollisionData`.
`IImpactDamageData` carries **Layer Mask**, **Damage Processor**, **Damage Amount**, **Impact Force**, **Impact Force Frames**, **Impact Radius**, **Impact State Name**, **Impact State Disable Timer**, and **Surface Impact**. The built-in actions consume only their documented subsets; in particular, the damage-data **Layer Mask** does not by itself filter **Simple Damage**.
A new `ImpactDamageData` uses damage `10`, force `2`, force frames `15`, radius `0`, an empty state name, state timer `10`, and no processor or surface. Its initial layer mask excludes Ignore Raycast, Water, SubCharacter, Overlay, and Visual Effect, but released built-in Impact Actions do not use that mask as a Simple Damage gate.
For positive **Delay**, the action duplicates collision and damage data from generic pools, schedules the duplicate, and returns it after invocation. Destroying the action cancels outstanding schedules and returns their contexts. Resetting a **Source ID** clears repeat tracking but does not cancel an already scheduled action.
### Create a custom action
Mark the class serializable, derive from `ImpactAction`, and override `OnImpactInternal`. The base class supplies enabled/timing/repeat handling unless you override `TryInvokeOnImpact`.
```csharp
using System;
using Opsive.UltimateCharacterController.Items.Actions.Impact;
using UnityEngine;
[Serializable]
public class LogImpactTarget : ImpactAction
{
[SerializeField] private string m_Label = "Impact";
protected override void OnImpactInternal(ImpactCallbackContext ctx)
{
var collision = ctx.ImpactCollisionData;
Debug.Log($"{m_Label}: {collision.ImpactGameObject} at {collision.ImpactPosition}");
}
}
```
Use `ImpactActionGroup.Initialize` before invoking a group that you own in custom code. Call `OnImpact(context, forceImpact)` with forced impact false when the contained actions should enforce their repeat maps, call `Reset(sourceID)` when that cast/use cycle ends, and call `OnDestroy()` so delayed contexts and nested resources are released.
---
# Impact Action Conditions
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/impact-action-conditions/)
Impact Action Conditions let an item accept, reject, or branch an impact before it applies damage, effects, or target reactions. Use them when an Iron Sword should affect only particular targets, a firearm should react differently to projectile and non-projectile impacts, or the target should own the rule.
## Choose where the rule belongs
| Goal | Use | Why |
| --- | --- | --- |
| Choose different actions on the attacking item | **Conditional Impact Action** | The source evaluates one condition list, then runs either its pass or fail actions. |
| Let each target decide whether the source may affect it | **Impact Condition Behaviour** on the target plus **Check Target Impact Condition Behaviour** on the source | One sword or firearm can respect different target-owned rules without listing every target on the item. |
| Let the target run its own pass or fail response | **Conditional Impact Receiver** on the target | The target receives the impact callback, evaluates its rules, and owns both result branches. |
| Gate an entire impact module | The module's **Conditions** list | Melee, shootable, throwable, and magic impact modules use the same condition-group behavior. |
Conditions in one list are combined with **AND**. Put the cheapest, most general test first so a failed test can stop the remaining checks.
## Branch actions on the source
Add **Conditional Impact Action** to an Impact Actions list when the item should choose what happens next.
1. Add the required entries to **Conditions**.
2. Add damage or other successful results to **Impact Actions On Pass**.
3. Add feedback for a rejected impact to **Impact Actions On Fail**. This list may be empty.
4. Enable **Reset Damage Data On Fail** only when later actions in the surrounding list must not reuse damage data prepared before this branch. It is disabled by default.
The fail branch is invoked before **Reset Damage Data On Fail** clears the damage data. With the Conditional Impact Action's default **Delay** of `0`, the reset therefore affects later sibling Impact Actions, not the actions already invoked inside the fail branch. If the Conditional Impact Action itself has a delay, outer actions can run before the delayed branch and reset. A failed condition selects the fail branch; it does not stop later actions in the outer Impact Actions list.
## Put reusable rules on the target
Use **Impact Condition Behaviour** when a target should describe what is allowed. For example, a reinforced crate can accept only an Iron Sword definition while another crate accepts the broader weapon category.
1. Add **Impact Condition Behaviour** to the hit GameObject or its Rigidbody GameObject.
2. Add one or more entries to **Impact Action Conditions**.
3. On the weapon's condition list, add **Check Target Impact Condition Behaviour**.
The released Version 3 Inspector below shows the definition condition before its **Item Definitions** list is populated. Add at least one definition before testing a whitelist.
**Check Target Impact Condition Behaviour** first looks on the reported impact GameObject, then on the impact Rigidbody GameObject. If neither has an `ImpactConditionBehaviourBase`, the check passes. It does not require every target to have the component and it does not search an arbitrary parent or child hierarchy.
### Let the target own the result
Use **Conditional Impact Receiver** when the target should run the result instead of merely approving a source-owned action.
1. Add **Conditional Impact Receiver** to the target.
2. Leave **Get Impact Conditions On Object** enabled to include other `IImpactCondition` components on the same GameObject. Add external components to **Impact Conditions Behaviours** only when needed.
3. Add local entries to **Impact Action Conditions**.
4. Configure **Impact Actions On Pass**, **On Object Impact Success**, **Impact Actions On Fail**, and **On Object Impact Fail**.
5. Make the attacking item send the target callback. An **Impact Event** does this when **Call Impact Callback On Target** is enabled; **Simple Damage** does it only when **Invoke On Object Impact** is enabled.
All discovered, assigned, and local conditions must pass. Do not assign the same behavior explicitly when **Get Impact Conditions On Object** already discovers it on the receiver GameObject, or the receiver will evaluate it twice.
## Built-in condition catalog
Every built-in condition has **Enabled**, **Bindings**, and **States**. **Enabled** defaults to on; turning it off makes that entry pass so the group ignores it.
### Respect target-owned rules
**Check Target Impact Condition Behaviour** has no additional fields. It evaluates an `ImpactConditionBehaviourBase` on the impact GameObject or, as a fallback, the impact Rigidbody GameObject. If no behavior is found, it returns true.
Use it on an Iron Sword or firearm when each target should define its own accepted weapon categories, definitions, or custom rules.
### Match a target by Object Identifier
**Object Identifier Impact Condition** accepts an impact only when it finds an `ObjectIdentifier` with the configured **Target ID**:
- **Target ID** defaults to `-1`, which matches nothing.
- **Search In Children** defaults to enabled. It searches the reported target and its children, including inactive children. Disable it to search the target and its parents instead.
This condition identifies the **target**, not the weapon or projectile source. In released Version 3 it forces an ID search, so assigning only the object-reference half of **Target ID** does not satisfy the condition. Add an `ObjectIdentifier`, give it the matching numeric ID, and choose the correct search direction.
### Filter by the source item
**Check Weapon Source Category** compares the source Character Item with **Item Categories**. Membership includes definitions inherited by a selected category.
- **Allow Non Weapon Impact** defaults to disabled. Enable it when impacts without a Character Item Action should pass.
- **Exclude Category** defaults to disabled. Disabled makes the list a whitelist: a matching category passes. Enabled makes it a blacklist: a matching category fails and a nonmatching category passes.
- **Item Categories** starts empty. With the default whitelist behavior, an empty serialized list accepts no weapon item.
Use a category rule when several definitions should share the result, such as every item in a melee-weapon category.
**Check Weapon Source Definition** applies the same logic to **Item Definitions** and inherited definition membership. Use it for a precise rule such as accepting Iron Sword but not every melee weapon.
- **Allow Non Weapon Impact** defaults to disabled.
- **Exclude Category** defaults to disabled and controls include-versus-exclude behavior.
- **Item Definitions** starts empty.
In released Version 3 the definition condition's include/exclude field is labeled **Exclude Category** even though it filters definitions. Treat that label as **Exclude Definition**; this is an Inspector-label mismatch, not a category filter.
### Filter projectile impacts
**Projectile Impact Action Condition** checks for a `Projectile` component directly on the impact context's source GameObject.
| Desired result | Allow Non Projectile Impact | Allow Projectile Impact |
| --- | --- | --- |
| Projectiles only | Off | On |
| Non-projectile impacts only | On | Off |
| Both | On | On |
| Neither | Off | Off |
Both fields default to off, so an unconfigured condition rejects every impact. The built-in check does not search the source's parents or children.
## Filters that need a different setup
Released Version 3 has no built-in Impact Action Condition for a layer, attribute, or surface. Use the closest source-owned setting when it expresses the rule, or add a custom condition when the decision must occur in this list.
| Filter | Practical choice |
| --- | --- |
| Target layer | Prefer the attack module's collision/detection layer controls so unwanted objects are never reported. A custom condition can instead inspect the layer of `ImpactGameObject`. `DetectLayers` in the context is the mask used for detection, not the target's layer. |
| Target attribute | Use a custom condition to find the target's attribute component from `ImpactGameObject` and evaluate the required value. |
| Surface | Use a custom condition to inspect `ImpactCollisionData.SurfaceImpact`. Surface-based effects do not by themselves accept or reject an impact. |
| Target identity | Use **Object Identifier Impact Condition** and a matching `ObjectIdentifier`. |
| Source category or definition | Use **Check Weapon Source Category** or **Check Weapon Source Definition**. |
## How evaluation runs
For every impact, the group checks its entries from top to bottom:
1. A disabled condition returns true and is skipped in practice.
2. The first enabled condition that returns false stops the group.
3. If every enabled condition passes, the group returns true. An empty condition list passes.
4. **Conditional Impact Action** runs one branch. **Conditional Impact Receiver** checks same-GameObject conditions first, then assigned behaviors, then its local condition group. It invokes the selected UnityEvent before the corresponding action branch.
There is no built-in OR mode within one group. To express OR, write one custom condition that owns the alternatives or restructure the outcome with separate conditional branches or receivers.
### Firearm example
To let a firearm run one impact result only for projectiles, add **Projectile Impact Action Condition**, enable **Allow Projectile Impact**, and leave **Allow Non Projectile Impact** disabled. Put the damage and surface effects in the pass branch and optional rejection feedback in the fail branch.
### Iron Sword example
To let each target decide whether Iron Sword may damage it, add **Check Target Impact Condition Behaviour** to the sword's condition list. On the protected target, add **Impact Condition Behaviour** with **Check Weapon Source Definition**, leave **Exclude Category** disabled, and add Iron Sword to **Item Definitions**. Targets without a behavior still pass, so add behaviors to every target that needs this policy or use an Object Identifier/custom requirement when the component must be present.
## Editor checkpoint
Before entering Play Mode, confirm that:
- every condition row is enabled and ordered from broad checks to specific checks;
- whitelist lists contain at least one category or definition;
- a projectile condition has at least one allow toggle enabled;
- target-owned rules are on the reported hit object or its Rigidbody GameObject; and
- a Conditional Impact Receiver has a source action that sends `OnObjectImpact` to the target.
## Verify in Play Mode
Test one passing and one failing case without changing the configuration between runs.
| Test | Expected result |
| --- | --- |
| Iron Sword hits a target whose definition whitelist includes it | Pass actions run; fail actions do not. |
| A different definition hits that target | The first failing definition condition stops the list and the fail result runs. |
| A projectile hits a projectiles-only branch | The projectile pass result runs. |
| A melee collider hits the same branch | The non-projectile fail result runs. |
| A source checks a target that has no Impact Condition Behaviour | **Check Target Impact Condition Behaviour** passes. |
| An Impact Event reaches a Conditional Impact Receiver | Exactly one of the receiver's success or fail events and action lists runs. |
When debugging a longer list, temporarily disable later entries. A disabled entry is ignored, so this isolates the first unexpected result without changing the list order.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| Every impact takes the fail branch | A projectile condition may still have both allow toggles off, or a source whitelist may be empty. | Enable the intended projectile result or populate the category/definition list. |
| A definition filter appears to use categories | Released Version 3 labels the definition condition's toggle **Exclude Category**. | Interpret it as include/exclude definition; leave it off for a whitelist. |
| Object Identifier never passes | The condition requires a numeric ID match and forces a hierarchy search. | Add `ObjectIdentifier`, match **Target ID**, and set **Search In Children** for the actual hierarchy direction. Do not rely only on the mapped object field. |
| A target-owned rule is ignored | **Check Target Impact Condition Behaviour** only checks the reported target and its Rigidbody GameObject. | Move the behavior to one of those objects or use a custom hierarchy-aware condition. |
| Conditional Impact Receiver never runs | The source may not invoke the target impact callback. | Add **Impact Event** with **Call Impact Callback On Target**, or enable **Invoke On Object Impact** on **Simple Damage**. |
| A receiver evaluates a rule twice | The same behavior may be auto-discovered and listed in **Impact Conditions Behaviours**. | Keep only one route to that behavior. |
| Damage data remains available after rejection | **Reset Damage Data On Fail** may be off, or a fail action is reading the data before the reset. | Enable the field when later outer actions must not reuse the data; remember that fail-branch actions run before it is cleared. |
## Related tasks
- [Configure Impact Actions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/impact-actions/)
- [Configure Item Effects](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/item-effects/)
- [Organize Action Module Groups](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/)
- [Configure a Melee Action](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/melee/)
- [Configure a Shootable Action](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/shootable/)
- [Understand Character Item Actions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/)
## Developer reference
Create a serializable class derived from `ImpactActionCondition` and override `CanImpactInternal`. The context supplies the reported target, source, collider, Rigidbody, detection mask, surface data, Character Item Action, and any prepared damage data. Returning false stops the remaining conditions in that group.
This example adds the missing target-layer filter:
```csharp
using System;
using Opsive.UltimateCharacterController.Items.Actions.Impact;
using UnityEngine;
[Serializable]
public class TargetLayerImpactCondition : ImpactActionCondition
{
[SerializeField] private LayerMask m_AllowedLayers = ~0;
protected override bool CanImpactInternal(ImpactCallbackContext ctx)
{
var target = ctx.ImpactCollisionData?.ImpactGameObject;
return target != null &&
(m_AllowedLayers.value & (1 << target.layer)) != 0;
}
}
```
Derive a reusable target component from `ImpactConditionBehaviourBase` when the rule belongs to the target rather than an item condition list. Implement `CanImpact(ImpactCallbackContext ctx)` and place the component where **Check Target Impact Condition Behaviour** can find it.
---
# Item Effects
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/item-effects/)
Item Effects add item-side feedback or changes at a chosen point in a Character Item Action, such as playing a firearm sound, showing a muzzle flash, toggling an Iron Sword object, or invoking a local callback. Use an **Effect Group** when the result depends on the owning item action and character; use [Impact Actions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/impact-actions/) when the result must use the object that was hit.
## Configure an Effect Group
1. Select the Character Item and expand the Character Item Action that should produce the result.
2. Open the relevant Action Module Group. Add or select **Generic Item Effects**, **Cast Item Effects**, or another module that exposes an **Effect Group**.
3. Expand **Effect Group**, select **+**, and choose an Item Effect type.
4. Configure the selected row. For a perspective-aware field, assign both first-person and third-person values or their **Object Identifier** IDs when the item supports both perspectives.
5. Drag the rows into a readable order. Put the item-side change first, presentation next, and a callback or temporary debug row last.
6. Choose the containing module's start, update, complete, stop, fire, throw, or cast setting. This decides when the entire group is invoked.
The legacy Inspector image remains accurate for released Version 3. Each row belongs to the same owning Character Item Action; an Item Effect does not receive a shot, collision, or impact target.
## Choose the invocation point
An Item Effect is a one-shot operation. It has no continuous update or stop phase of its own. The module containing the **Effect Group** decides which item lifecycle event invokes it.
| Item workflow | Exact controls and released-Version-3 defaults | Invocation |
| --- | --- | --- |
| General usable action, **Generic Item Effects** | **On Start Use** off, **On Use** on, **On Use Update** off, **On Use Complete** off | At each enabled use stage. **On Use Update** may invoke the group repeatedly during one use. |
| Shootable **Fire Effects** or **Dry Fire Effects**, **Generic Item Effects** | One **Effect Group** | When the containing fire or dry-fire module is invoked. |
| Melee **Attack Effects**, **Generic Item Effects** | **On Start Attack** on, **On Complete Attack** off, **Substate Index** `-1`, **Attack ID** `-1` | At the active attack start and/or completion. Negative filters match every attack. |
| Throwable **Throw Effects**, **Generic Item Effects** | One **Effect Group** | When the throwable item is thrown. |
| Magic **Generic Item Effects** | **On Start** on, **On Stop** off | When the containing magic start/stop module starts and/or stops. |
| Magic **Cast Item Effects** | **Block Until Effects Can Be Used** off | During that cast. When blocking is on, every effect must report that it can run. |
| **Aim Substate** | Separate **On Start Aim Effect Group** and **On Stop Aim Effect Group** | When input starts or stops aiming. |
| **Generic Item Effects** Impact Action | One **Effect Group** | At impact, but the contained Item Effects still receive only the owning Character Item Action, not the impact context. |
Choose one deliberate lifecycle point first. For example, a muzzle flash belongs in **Fire Effects**, not **On Use Update**; a sword trail can start with the active attack and use a separate completion or stop group to turn it off.
## Shared controls and execution
| Field | Default | Behavior |
| --- | --- | --- |
| **Enabled** | On | Intended to gate the row. In released Version 3, only **Enable Disable Object** and **Spawn Prefab** honor this field; see the limitations below. |
| **Delay** | `0` seconds | Zero invokes immediately. A positive value schedules that row independently. |
| **Bindings** | Empty | Optional property bindings inherited from the bound State object. |
| **States** | Default/empty | Optional State System presets that can override serialized effect values on the owning action GameObject. |
The group visits rows from top to bottom. Immediate rows run in that order. A delayed row is scheduled and the group immediately continues, so a later zero-delay row runs before it. There is no group-level wait or parallel switch: delayed rows simply overlap subsequent work.
Every effect is initialized with a valid Character Item Action. Perspective-aware effects resolve their current first-person or third-person value when invoked. If a feature must change the hit target, apply force, modify a target attribute, activate a target State, or use impact data, configure an [Impact Action](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/impact-actions/) instead.
## Built-in Item Effects
Released Ultimate Character Controller Version 3 contains six concrete Item Effect types. The sections below cover every built-in type.
### Change a perspective object
**Enable Disable Object** changes one GameObject on the current perspective item.
| Field | Default | Behavior |
| --- | --- | --- |
| **Object** | First- and third-person IDs `-1`; references unassigned | Resolves an assigned object or an **Object Identifier** below the current perspective item. A missing object is a no-op. |
| **Enable Object** | Off | Off deactivates the object; on activates it. |
| **Revert Time** | `-1` seconds | A positive value schedules the opposite active value. Zero or less leaves the requested value in place. |
Use separate start and stop groups when an object must follow a lifecycle precisely. For example, enable an Iron Sword trail at attack start and disable it at attack completion instead of relying on a timer.
### Spawn a visual object
**Spawn Prefab** creates a pooled object from the current perspective configuration.
| Field | Default | Behavior |
| --- | --- | --- |
| **Prefab** | First- and third-person references unassigned | Chooses the prefab for the active perspective. A missing prefab is a no-op. |
| **Origin** | First- and third-person IDs `-1`; references unassigned | Uses the selected perspective transform. With no resolved origin, it falls back to the character transform. |
| **Parent To Origin** | On | Keeps the spawned object under the origin. Off unparents it after creation. |
| **Local Position** / **Local Rotation** | `(0, 0, 0)` | Offsets the object from the chosen origin. |
| **Local Scale** | `(1, 1, 1)` | Applies the final local scale after parenting or unparenting. |
| **Life Time** | `-1` seconds | A positive value returns a pooled object to its pool, or destroys a non-pooled object. Zero or less leaves it alive. |
Use this effect for a short muzzle flash, cast ornament, or sword swipe that belongs to the item action. The effect uses the Opsive object pool when the prefab is pooled.
### Set light or audio feedback
**Light Effect** assigns one intensity value to a Light on the current perspective item.
| Field | Default | Behavior |
| --- | --- | --- |
| **Light** | First- and third-person IDs `-1`; references unassigned | Resolves the Light for the active perspective. |
| **Light Intensity Curve** | Unassigned | Supplies the intensity returned by the curve. |
| **Light Intensity Time** | `0` | Evaluates the curve once at this time and assigns the result to `Light.intensity`. |
This effect does not animate the curve over time and does not enable or disable the Light component or GameObject. Use two rows or lifecycle groups with different curve samples for an on/off change.
**Play Audio Clip** contains one **Audio Clip Set**. A new set has no **Audio Config** or **Audio Clips** selected. When invoked, it selects from the configured set and plays on the owning Character Item Action GameObject. It is a one-shot effect; the Item Effect does not expose a matching stop control. Use an [Audio Config](https://opsive.com/support/documentation/ultimate-character-controller/audio/) when the sound needs the shared audio settings rather than a local clip list.
### Invoke a callback or inspect the flow
**Invoke Unity Event** exposes **On Invoke Effect**, with no persistent listener by default. It invokes a no-argument UnityEvent; it does not pass the item action, character, or impact context to the listener.
**Debug Item Effect** exposes **Message**, blank by default. It logs the message followed by the owning Character Item Action and uses that action as the Unity Console context. Add it temporarily after another row to confirm that the group reached that point.
## Choose the correct target system
Item Effects are intentionally limited to the owning item action. Use the adjacent system when the desired result needs different data.
| Desired result | Use |
| --- | --- |
| Play item-side audio | **Play Audio Clip** Item Effect. |
| Toggle or inspect the current perspective item | **Enable Disable Object**, **Light Effect**, **Spawn Prefab**, or a local UnityEvent. |
| Damage, force, target attributes, target States, surface feedback, or a hit callback | [Impact Actions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/impact-actions/), which receive the impact context. |
| Camera shake or another camera response | A camera/view module, a deliberately wired UnityEvent, or a custom Item Effect. There is no built-in camera Item Effect. |
| Change an owning item or character State | The effect's inherited **States** can override its values; use the [State System](https://opsive.com/support/documentation/ultimate-character-controller/state-system/) or a custom effect when gameplay must explicitly activate a named State. There is no built-in set-state Item Effect. |
## Scenario recipes
### Firearm muzzle feedback
1. In the Shootable Action, add **Generic Item Effects** to **Fire Effects**.
2. Add **Spawn Prefab**. Assign first- and third-person muzzle-flash prefabs and origins, keep **Parent To Origin** on, and give the effect a short positive **Life Time**.
3. Add **Play Audio Clip** with the firearm's **Audio Config** or clip set.
4. Add **Invoke Unity Event** last only when another local component needs a fire callback.
5. Configure a separate **Dry Fire Effects** group for an empty-weapon click rather than branching inside this group.
The flash and sound are item-side presentation. Keep projectile hits, damage, force, and surface response in the Shootable Action's Impact module.
### Iron Sword attack feedback
1. In **Attack Effects**, add **Generic Item Effects**.
2. Leave **On Start Attack** on. Set **Attack ID** or **Substate Index** only when the effect belongs to one attack animation.
3. Add **Enable Disable Object** for a trail object, or **Spawn Prefab** for a short swipe effect, using perspective-aware origins.
4. Add **Play Audio Clip** for the swing sound.
5. Use **On Complete Attack** or another stop-stage group to turn a persistent trail off. Use Impact Actions for damage and the target's hit reaction.
## Editor checkpoint
Before entering Play Mode, confirm that:
- the Effect Group is inside the module and lifecycle stage that actually runs for this item;
- every perspective-aware effect has a valid first-person and/or third-person reference or **Object Identifier** ID;
- **Spawn Prefab** has a prefab, a deliberate origin, and a positive **Life Time** when the object should be temporary;
- **Light Effect** has both a Light and an intensity curve;
- **Play Audio Clip** has an **Audio Config** or at least one clip;
- delayed rows do not depend on a later row waiting for them; and
- target-side gameplay remains in an Impact Action rather than an Item Effect.
## Verify in Play Mode
| Test | Expected result |
| --- | --- |
| Fire the configured firearm once | The item-side flash and audio occur once at the selected fire stage; impact damage remains independent. |
| Switch between first- and third-person views, then fire | Each view uses its own configured prefab, origin, object, or Light. |
| Dry-fire the weapon | Only the **Dry Fire Effects** result runs. |
| Perform the matching and nonmatching Iron Sword attacks | A filtered **Attack ID** or **Substate Index** invokes the group only for the matching attack. |
| Give one row a positive **Delay** | Later zero-delay rows run first; the delayed result appears after its own timer. |
| Strike two different targets | Item Effects repeat from the owning sword action but never read or alter either target unless an Impact Action does so. |
Use **Debug Item Effect** temporarily when you need to distinguish "the group did not run" from "the chosen object, clip, curve, or listener produced no visible result."
## Troubleshooting and released-Version-3 limitations
| Symptom | Check | Fix |
| --- | --- | --- |
| An effect never appears | Confirm that the containing module and its exact lifecycle toggle run for this item, then check the current perspective reference. | Move the group to the correct module/stage and assign the missing object, origin, prefab, Light, clip, or listener. |
| **Enabled** is off but an effect still runs | **Invoke Unity Event**, **Debug Item Effect**, **Light Effect**, and **Play Audio Clip** override the availability check and ignore **Enabled** in released Version 3. | Remove that row, clear its listener/data, or use a custom effect whose availability check calls the base implementation. |
| A magic cast remains blocked by a disabled row | **Enable Disable Object** and **Spawn Prefab** do honor **Enabled**, so **Cast Item Effects > Block Until Effects Can Be Used** reads them as unavailable. | Remove the disabled row or turn blocking off; do not use **Enabled** as a temporary mixed-type group switch in this flow. |
| A delayed effect fires more times than expected | The same row was invoked again before its delay elapsed, commonly through **On Use Update**. Released Version 3 tracks only the most recently scheduled delay handle even though earlier callbacks remain scheduled. | Invoke the group once per intended event, keep the row at **Delay** `0`, or implement explicit repeat/cancellation control in a custom module. |
| **Revert Time** restores the wrong active value | **Enable Disable Object** schedules the opposite of **Enable Object**, not the GameObject's actual prior `activeSelf` value. Its revert schedule is also separate from the effect's normal destroy cleanup. | Start from a known object state or use explicit start and stop groups instead of **Revert Time**. |
| **Light Effect** throws or does nothing | The Light or **Light Intensity Curve** is unassigned, or the curve sample equals the current intensity. The released effect has no null guard and performs only one assignment. | Assign both fields and test a clearly different curve value at **Light Intensity Time**. |
| A spawned object remains in the scene | **Life Time** is `0` or negative. The positive-lifetime callback is scheduled separately and is not canceled when the effect is destroyed. | Use a positive lifetime for temporary feedback and make the spawned prefab safe to return later, or manage its lifecycle in a custom effect. |
| Audio comes from the wrong place | **Play Audio Clip** plays on the owning Character Item Action GameObject, not the hit point or the selected perspective origin. | Use an impact audio action for hit-position audio, or a custom item effect when another item transform must own the sound. |
| Force, damage, an attribute, a target State, or camera shake is missing | No built-in Item Effect performs those target/camera operations. | Use Impact Actions, a camera/view module, a wired UnityEvent, or a focused custom effect. |
## Related tasks
- [Configure Impact Actions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/impact-actions/)
- [Configure Impact Action Conditions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/impact-action-conditions/)
- [Organize Action Module Groups](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/)
- [Configure a Melee Action](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/melee/)
- [Configure a Shootable Action](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/shootable/)
- [Configure a Throwable Action](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/throwable/)
- [Configure a Magic Action](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/magic/)
- [Configure Audio](https://opsive.com/support/documentation/ultimate-character-controller/audio/)
- [Configure States](https://opsive.com/support/documentation/ultimate-character-controller/state-system/)
## Developer reference
`ItemEffect` derives from `BoundStateObject` and is initialized with a non-null `CharacterItemAction`. The base implementation gates with **Enabled**, schedules **Delay** through the Opsive Scheduler, and clears its tracked delay when `InvokeEffectInternal` runs. `ItemEffectGroup` initializes every row against the same action, checks availability with `CanInvokeEffects`, invokes every row with `TryInvokeEffect`, and forwards `OnDestroy` for cleanup.
A group does not stop when one row returns false; it continues to later rows. If a custom Item Effect adds a condition, combine it with `base.CanInvokeEffect()` so the shared **Enabled** control still works. Call `base.InvokeEffectInternal()` before the custom result so the base delay tracking is cleared, and call the base cleanup when overriding `OnDestroy`.
Mark a custom Item Effect serializable so its values appear and persist in the Inspector:
```csharp
using System;
using Opsive.UltimateCharacterController.Items.Actions.Effect;
using UnityEngine;
[Serializable]
public class LogItemUseEffect : ItemEffect
{
[SerializeField] private string m_Message = "Item effect";
protected override void InvokeEffectInternal()
{
base.InvokeEffectInternal();
Debug.Log($"{m_Message}: {m_CharacterItemAction}", m_CharacterItemAction);
}
}
```
When custom code owns an `ItemEffectGroup`, initialize it with the relevant Action Module or Character Item Action before invocation, and call `OnDestroy()` when its owner is destroyed so tracked delayed work is canceled.
---
# Inventory
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/inventory/)
The Inventory records which items a character owns, how many of each item are available, and which Character Item is active in each slot. Use the built-in Inventory for controller-focused loadouts, pickups, equipment, ammunition, and drops.
## How the inventory fits together
The built-in inventory separates the item data from the object that appears on the character:
- An **Item Collection** contains the project's item categories and Item Types.
- An **Item Type** is the built-in Item Definition and Item Identifier. It supplies the identity, capacity, categories, and Character Item prefab references; the Inventory stores the owned amount.
- A **Character Item** is the runtime item object for one Item Definition and slot. It contains the visible first- or third-person item, item actions, equip timing, and optional **Drop Prefab**.
- The **Inventory** owns Item Identifier amounts, maps each Item Identifier to its Character Items, and records the active Character Item in each slot.
- The **Item Set Manager** uses Item Set Rules to decide which owned Character Items form valid equipment combinations. Equip and unequip requests should normally go through this manager rather than changing an Inventory slot directly.
An item such as an Iron Sword therefore has an Item Type that identifies the owned count, a Character Item for the sword held in a hand slot, and an Item Set that makes the sword an equippable choice. A consumable identifier such as Bullet can exist only as an Inventory amount when it does not need its own visible Character Item.
## Before you begin
The character needs item support created by the Character Manager, an Item Collection, and at least one Item Set Rule for anything that can be equipped. Create the Item Types and Character Items first by following [Item creation](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-creation/).
Use the built-in Inventory only when UCC owns the item data. If Ultimate Inventory System owns the inventory, follow the [Ultimate Inventory System integration](https://opsive.com/support/documentation/ultimate-character-controller/integrations/ultimate-inventory-system/) instead; that integration replaces the standard Inventory and Item Set Manager with bridge components.
## Add inventory support to a character
1. Open **Tools > Opsive > Ultimate Character Controller > Character Manager**.
2. Select the character. Enable **Items**, assign the character's **Item Collection**, and assign an **Item Set Rule**.
3. Select **Build Character** for a new character or **Update Character** for an existing one.
4. Confirm that the character has an **Inventory** and **Item Set Manager**, and that its hierarchy contains the **Items** object used for Character Items. A player-controlled character also receives the item input handling and standard item abilities.
5. Select the Inventory. Expand **Default Loadout** and confirm that every entry belongs to the same Item Collection assigned to the Item Set Manager. The Inspector reports an error when a loadout definition comes from another collection.
### Editor checkpoint
Before entering Play Mode, the character should have one Inventory, one Item Set Manager using the intended Item Collection, and a Character Item prefab for every visible or equippable item. Each Character Item's **Slot ID** must match the slot used by its Item Set Rule. Count-only definitions such as ammunition do not need a Character Item prefab.
## Create useful starting loadouts
### Start with an Iron Sword
1. Create an **Iron Sword** Item Type in **Tools > Opsive > Ultimate Character Controller > Item Type Manager**.
2. Open **Tools > Opsive > Ultimate Character Controller > Item Manager**. Build the sword for the character with **Item Definition** set to Iron Sword and the intended hand **Slot ID**. Keep **Add to Default Loadout** enabled when the character should begin with it.
3. On the Inventory, expand **Default Loadout** and set Iron Sword to an amount of **1**.
4. Configure the Item Set Rule so the sword produces a valid set in that slot.
5. Set **Loadout Equip** to **First Loadout Item** for a simple one-item loadout, or choose **Item Set Name** when a named combination such as Sword and Shield must be selected.
The first loadout entry matters when **First Loadout Item** is selected. The Inventory adds the definitions first, then asks the first Item Set Group to equip the set that contains that entry. **Item Set Index** also addresses the first group; prefer **Item Set Name** when the project has multiple groups or the generated order can change.
### Start with a firearm and ammunition
Create one Item Type and Character Item for the firearm. When its Shootable Action uses an **Item Ammo** module, create a separate ammunition Item Type, assign it as that module's **Ammo Item Definition**, and add the starting ammunition amount to **Default Loadout**. The firearm needs a Character Item prefab; ammunition usually remains a count-only Inventory entry.
For example, add Rifle with amount **1** and Bullet with the desired reserve amount. The Rifle's Character Item can be spawned and equipped, while reload removes Bullet amounts from the Inventory. The Bullet Item Type's **Capacity** limits how much reserve ammunition the Inventory can accept.
See [Shootable](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/shootable/) for the clip, ammo, and reload module workflow.
## Add a pickup and a drop
### Place a pickup in the scene
1. Create an Item Pickup with **Tools > Opsive > Ultimate Character Controller > Object Manager**, or add **Item Pickup** and a trigger Collider to a suitable prefab.
2. Add Iron Sword, Rifle, Bullet, or another definition to **Item Definition Amounts** and set the amount the object grants.
3. Keep **Pickup On Trigger Enter** enabled for automatic collection. Disable it when the Pickup ability or another interaction should initiate collection.
4. Enable **Equip** when collecting the object should request an equipment change. Set **Item Set Name** and **Item Set Group** when a particular set must be selected; otherwise the pickup tries a valid set containing one of the collected Character Items.
5. Set **Trigger Enable Delay** deliberately for dropped physics objects. A scene pickup without a Rigidbody is available immediately on its first initialization; a dropped Rigidbody waits until it settles and the delay expires.
On collection, the pickup adds each definition to the Inventory, spawns any configured Character Item prefabs, updates the Item Sets, and optionally requests an equip. The definition's capacity can reduce the amount accepted.
### Make an item drop and become collectible again
Assign a **Drop Prefab** on the Character Item. That prefab must contain an **Item Pickup**-based component so the Inventory can place the dropped definition and amount on it. Add the [Drop ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/drop/) to remove the active Character Item and spawn that prefab. Use **Wait For Unequip** when the visible item should finish its unequip transition before it leaves the character.
A shootable Character Item can also contribute related identifiers, such as its ammunition, to the dropped pickup. Test the exact amount you want to transfer rather than assuming all reserve ammunition should leave with one weapon.
## Choose the Inventory behavior
### Choose what loads and equips
- **Default Loadout** adds Item Definitions and amounts when the Inventory initializes. It runs again after respawn only when **Load Default Loadout On Respawn** is enabled.
- **Loadout Equip** defaults to **First Loadout Item**. **None** unequips the groups, **Item Set Name** or **Item Set Index** selects a specific set, and **Do Nothing** leaves the existing equipment unchanged.
- **Auto Spawn Destroy Runtime Character Items** is enabled by default. Adding an identifier spawns the Character Item prefabs referenced by its Item Type; removing the last amount can destroy runtime-spawned Character Items.
- **Auto Remove Character Items** is enabled by default. When an amount reaches zero, the corresponding Character Items leave the valid Inventory and an equipped item is handed back through the normal Item Set transition.
Use **Loadout Equip > Item Set Name** instead of a generated index when a stable, meaningful Item Set state name is available. Runtime Item Set indexes can change as the owned items and rules change.
### Choose what happens on death and respawn
- **Unequip All On Death** is disabled by default. Enable it to unequip every active slot when the character dies.
- **Remove All On Death** is disabled by default. Enable it to remove the removable Character Items and their amounts and attempt to drop them with their configured drop prefabs. Add definitions to **Remove Exceptions** when they must survive this removal. A count-only identifier that is not associated with a Character Item is not enumerated by `RemoveAllItems`; clear it explicitly when that resource must also be lost on death.
- **Load Default Loadout On Respawn** is disabled by default. Enable it to add the configured default amounts again and then apply **Loadout Equip**.
Avoid using **Remove All On Death** and a persistent save restore as two independent authorities. Decide whether death, the save system, or another game system owns the final restored amount, then apply that state once.
### Use the Unequipped state
**Unequipped State Name** defaults to `Unequipped`. The Inventory activates this state while no Character Item is active and deactivates it when an item is equipped. Leave the field empty only when the project intentionally does not use an inventory-wide unequipped state.
## Verify in Play Mode
1. Select the character and expand **Inventory > Current Inventory**. Confirm the Iron Sword or Rifle and its expected count appear. Active entries are bold and show their slot numbers.
2. Confirm the Item Set Manager creates a valid set for the visible Character Item and that **Loadout Equip** activates the intended set.
3. Collect an Item Pickup. Confirm the count increases only up to the Item Type's capacity, its Character Item appears when required, and the configured equipment change occurs.
4. For a firearm, fire and reload. Confirm the reserve Bullet amount decreases while the firearm remains owned and active.
5. Drop the active item. Confirm its Inventory amount decreases, the Character Item is removed or replaced through the Item Set Manager, and the spawned object can be collected again after its trigger delay.
6. Test death and respawn. Confirm only the selected unequip, remove, exception, loadout, and re-equip behavior occurs.
## Troubleshoot inventory items
- **The Current Inventory is empty:** check that you are in Play Mode, the definition is in **Default Loadout** or is actually collected, and the Inventory component is enabled. The Current Inventory foldout is read-only runtime information.
- **The amount does not increase:** check the Item Type's **Capacity**, the pickup's **Item Definition Amounts**, and whether the character is entering the trigger with its main collider. Fix the capacity or pickup definition rather than adding a duplicate Item Type.
- **The character owns an item but no Character Item appears:** check that the Item Type references a Character Item prefab and **Auto Spawn Destroy Runtime Character Items** is enabled. Also confirm the prefab has the same Item Definition and a valid Slot ID.
- **The item appears but does not equip:** inspect the Item Set Manager in Play Mode. Fix the Item Set Rule, Item Category, slot mapping, or disabled Item Set, then confirm the matching [Equip Unequip](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/item-set/equip-unequip/) ability can run.
- **A pickup adds ammunition but equips the wrong weapon:** disable **Equip** for an ammo-only pickup, or assign the intended **Item Set Name** and **Item Set Group**. Also check the Equip Unequip ability's Auto Equip choices.
- **Dropping removes the item but spawns nothing:** check the Character Item's **Drop Prefab** and confirm that prefab contains an Item Pickup component. A null or incompatible prefab cannot receive the dropped Item Definition amounts.
- **The dropped object cannot be collected immediately:** check **Trigger Enable Delay**, the trigger Collider, and the object's velocity. Dropped Rigidbody objects deliberately wait until they settle and the configured delay completes.
- **Items duplicate after respawn or load:** check **Load Default Loadout On Respawn** and the order of the project's save restore. Make one system responsible for adding the final amounts.
## Persistence, multiplayer, and UIS ownership
The built-in UCC Inventory does not include a general persistence component that saves arbitrary inventory amounts. A project save system should record each stable Item Type ID and amount, resolve those IDs through the same Item Collection, restore them with the Inventory API, and then restore or request the intended Item Set after the Character Items have been created.
UCC includes conditional multiplayer hooks for authoritative item addition, removal, equipment, pooling, and dropped-object spawning. Those hooks do not provide a transport or complete inventory replication layer by themselves; use the supported networking integration and perform mutations on the authoritative instance.
Ultimate Inventory System is a different ownership model. It provides collections, mutable item data, equipment UI, shops, crafting, and its own saving workflow. In the UCC integration, UIS owns those items and the bridge presents them to UCC as Character Items and Item Sets. Do not keep both the standard UCC Inventory and the UIS character inventory bridge active on the same character.
## Related tasks
- [Item creation](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-creation/) builds Item Types and Character Item prefabs.
- [Item Type, Definition, and Category](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-type-definition-category/) explains the identifiers, capacity, and category data used by Inventory.
- [Character Item](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/) configures slots, visible objects, item actions, and drop prefabs.
- [Item Set and Rules](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-set-rules/) controls valid equipment combinations.
- [Item Pickup](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-pickup/) covers pickup object settings.
- [Equip Unequip](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/item-set/equip-unequip/) controls animated equipment transitions.
- [Drop](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/drop/) removes equipped items and spawns their pickup prefabs.
- [Ultimate Inventory System integration](https://opsive.com/support/documentation/ultimate-character-controller/integrations/ultimate-inventory-system/) replaces built-in inventory ownership with UIS.
## Developer reference
Depend on `InventoryBase` when code should work with the standard Inventory or a supported inventory bridge. The standard `Inventory` implementation stores the amounts, active items, default loadout, removal exceptions, and loadout-equip behavior.
### Query and change amounts
`GetAllItemIdentifiers()` returns the identifiers currently owned. `GetAllCharacterItems()` returns the spawned Character Items, which is a different collection and can contain the slot-specific objects for an identifier.
```csharp
using Opsive.Shared.Inventory;
using Opsive.UltimateCharacterController.Inventory;
using UnityEngine;
public static class InventoryExample
{
public static void AddAndRemove(GameObject character, IItemIdentifier itemIdentifier)
{
var inventory = character.GetComponent();
if (inventory == null || itemIdentifier == null) {
return;
}
var amountBefore = inventory.GetItemIdentifierAmount(itemIdentifier);
var amountAdded = inventory.AddItemIdentifierAmount(itemIdentifier, 1);
var amountRemoved = inventory.RemoveItemIdentifierAmount(itemIdentifier, 1);
Debug.Log($"{amountBefore} before, {amountAdded} added, {amountRemoved} removed.");
}
}
```
`AdjustItemIdentifierAmount(itemIdentifier, amount)` accepts a positive amount to add or a negative amount to remove. The returned value is the actual adjustment, so capacity and removal rules can make it smaller than the request.
Call `PickupItem` when the caller must supply a slot, immediate-pickup choice, or force-equip choice. The two-argument `AddItemIdentifierAmount` follows the Inventory's automatic Character Item spawning setting; with automatic spawning enabled, it routes through `PickupItem` and sends pickup notifications. The overload that accepts `spawnCharacterItems` performs the amount and optional spawn change without those pickup notifications.
### Equip and drop through the owning systems
Use `ItemSetManagerBase.TryEquipItemSet` for normal equipment requests:
```csharp
var itemSetManager = character.GetComponent();
var equipped = itemSetManager != null &&
itemSetManager.TryEquipItemSet("IronSword", -1, true, false);
```
The group index **-1** searches the groups for a matching Item Set name. The final two arguments request a forced transition and a non-immediate transition. Use the Character Item Drop Prefab and the Drop ability for a player-facing drop. Lower-level code can use `RemoveItemIdentifierAmount(itemIdentifier, slotID, amount, true)` or `DropCharacterItem`, but it is then responsible for the intended authority and animation timing.
### Listen for inventory events
The Inventory Inspector exposes Unity Events for add, pickup, equip, amount adjustment, unequip, and remove. The Opsive Event System provides the corresponding runtime messages, including:
- `OnInventoryAdjustItemIdentifierAmount` with `(IItemIdentifier, int previousAmount, int newAmount)`;
- `OnInventoryPickupItemIdentifier` with `(IItemIdentifier, int amount, bool immediatePickup, bool forceEquip)`;
- `OnInventoryPickupItem` with `(CharacterItem, int amount, bool immediatePickup, bool forceEquip)`;
- `OnInventoryWillAddItem` and `OnInventoryAddItem` with `(CharacterItem)`;
- `OnInventoryEquipItem` and `OnInventoryUnequipItem` with `(CharacterItem, int slotID)`;
- `OnInventoryRemoveItem` with `(CharacterItem, int slotID)`; and
- `OnInventoryLoadDefaultLoadoutComplete` and `OnInventoryRespawned` without parameters.
Register and unregister the same signature on the character GameObject. See [Events](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/) for the shared registration pattern.
---
# Item Slots
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-slots/)
Item Slots give each equipment location a stable ID so Inventory, Item Sets, visible models, abilities, and animation all agree about where an item belongs. The normal humanoid mapping is right hand **0** and left hand **1**.
## Understand the slot map
Four similar values have different jobs:
| Value | What it controls |
| --- | --- |
| **Character Item Slot > ID** | Identifies an attachment location on a character model or first-person arm rig. |
| **Character Item > Slot ID** | Selects the Inventory position and the matching first- or third-person attachment location. |
| **Character Item > Animator Item ID** | Identifies the item's animation family. It is written to `SlotItemID`; it is not a Slot ID. |
| An Item Set Rule's array position | Specifies which Item Definition is allowed in that Slot ID. |
Inventory scans every Character Item Slot below the character, including inactive objects. Its slot count is the highest nonnegative ID plus one, with a minimum of one. Keep IDs contiguous: IDs `0` and `3` create four Inventory positions even when `1` and `2` are unused.
Several available Character Items can be assigned to one slot, but only one can be active in that slot at a time. A second hand, independent utility location, or another simultaneously equipped item therefore needs another Slot ID.
## Configure slots in Character Manager
1. Open **Tools > Opsive > Ultimate Character Controller > Character Manager**.
2. Select or configure the scene character and enable **Items**.
3. Assign the full-body model and any **First Person Arms** that will display held items.
4. Select **Adjust Slots** beside **Item Slots**.
5. Under **Model**, add the transform that should own each attachment point. For a humanoid, use the right hand as **Right** ID `0` and the left hand as **Left** ID `1`.
6. Choose **Other** and enter `2` or higher for a project-specific location. Keep IDs nonnegative and contiguous unless an empty Inventory position is intentional.
7. Under every **First Person Arms** entry, add the equivalent attachment transforms and reuse the same logical IDs.
8. Resolve every validation message. A parent must be below the displayed model or arm rig, and each parent and ID must be unique within that hierarchy.
9. Select **Close**, then **Build Character** for a new character or **Update Character** for an existing one.
Character Manager creates a child named `Items` under each selected attachment transform and adds **Character Item Slot** with the chosen **ID**. This is different from the controller-level `Items` object: the controller-level object has **Item Placement** and stores Character Item roots, while the hand-level objects mark where their visible models attach.
### Editor checkpoint
Before creating an item, expand every model and arm rig in the Hierarchy. Each intended attachment transform should contain one `Items` child with one Character Item Slot. Right-hand locations should use the same ID in every relevant perspective and model, as should left-hand and custom locations.
## Match first- and third-person slots
A Character Item has one Slot ID even when it renders different objects in first and third person. Each perspective therefore needs a Character Item Slot with that same ID:
- The third-person perspective searches the active character model for its matching slot.
- The first-person perspective searches the selected First Person Base Object and its arm hierarchy.
- Item Manager blocks an on-character build when the selected first- and third-person slots use different IDs.
- A character that switches models needs the same logical slot map on every model that can display the item.
The transforms do not need identical names or positions. They represent the same logical location: for example, a third-person right hand and the corresponding first-person right arm can both be slot `0`.
Keep a third-person representation for AI or multiplayer characters that other cameras must see, even when the local player uses a first-person view. A first-person representation is only needed for a first-person camera path.
## Assign a Character Item to a slot
Use **Tools > Opsive > Ultimate Character Controller > Item Manager** after the character's slot map is stable.
### Build a reusable prefab
1. Leave **Character** empty so Item Manager shows **Slot ID**.
2. Assign **Item Definition** and enter the Slot ID that the prefab can occupy.
3. Set **Animator Item ID** to the animation mapping implemented by the character's Animator Controller. Do not copy the Slot ID into this field unless that happens to be the intended animation mapping.
4. Enable **Add First Person Item** and **Add Third Person Item** only for the perspectives the prefab supports.
5. Keep **Add Item Prefab to Item Definition** enabled so Inventory can find this slot-specific prefab at runtime.
6. Build the item, then inspect its **Character Item > Slot ID** before adding it to a loadout.
One Item Definition can reference more than one Character Item prefab. For example, a pistol definition can reference a right-hand prefab with Slot ID `0` and a left-hand prefab with Slot ID `1`. Inventory uses the definition and slot together; do not add two prefabs with the same definition and Slot ID.
### Build directly on a character
When **Character** is assigned, Item Manager derives the Slot ID from the selected perspective parents. Choose the first-person **Item Parent** and the humanoid third-person **Hand**, or select an **Item Parent** for a custom rig. The manager requires the two selected Character Item Slots to have the same ID before it enables the build.
Changing **Animator Item ID** through **Update Item** does not move an existing item to another slot. When the slot must change, update the Character Item's Slot ID, both perspective parents, its Item Set Rules, and its Animator setup as one controlled change; rebuilding a copy is safer for a complex item.
## Build common equipment layouts
| Scenario | Slot map | Character Items and Item Set |
| --- | --- | --- |
| Rifle or one-handed firearm | Right hand `0`; left hand `1` may stay empty | Build the firearm for slot `0`. The Item Set Rule places its definition at array position `0`. |
| Sword and shield | Sword/right hand `0`; shield/left hand `1` | Build separate Character Items for the two definitions and place each at its exact Item Set position. Their Animator Item IDs normally differ. |
| Two matching pistols or swords | Right hand `0`; left hand `1` | Add two slot-specific Character Item prefabs to the same definition, require an Inventory amount of two, and put that definition in both Item Set positions. Both Character Items may use the same Animator Item ID. |
| Independent utility item | Existing hand slots plus a contiguous custom ID | Add the same custom ID to every perspective that displays it, create a Character Item for that ID, and give it an Item Set Group or rule that can stay active with the main equipment. |
A holster is not usually another Inventory slot. Use the third-person item's **Holster Target** when one Character Item should move between its equipped and holstered positions without becoming an independently equipped item.
## Connect Item Sets, actions, and abilities
The Slot ID follows the item through the complete runtime flow:
1. An Item Definition owns one or more slot-specific Character Item prefabs.
2. Inventory creates the matching Character Items and stores them by Slot ID.
3. An Item Set Rule places definitions at exact slot positions. It cannot move a Character Item from one slot into another.
4. Equip Unequip activates the Character Item selected for each changed slot.
5. The Character Item Action belongs to that slot-specific Character Item. Its **ID** selects an action on the item; it does not select a slot.
6. Use and Reload can target **Slot ID -1** for every eligible equipped item or a specific Slot ID for independent hand controls.
7. Drop uses **Slot ID -1** to target all slots by default; enter one Slot ID when the ability should drop only that position.
An Item Pickup adds an Item Definition amount. Its Character Item prefabs and the Item Set Rules decide which slot-specific representations become available and which combination equips. A pickup does not relocate one Character Item between hands.
## Add Animator parameters for custom slots
The supplied Animator setup covers slots `0` and `1`. For every additional slot `X`, add this complete group to each Animator Controller that needs to animate it:
- `SlotXItemID` (**Int**)
- `SlotXItemStateIndex` (**Int**)
- `SlotXItemStateIndexChange` (**Trigger**)
- `SlotXItemSubstateIndex` (**Int**)
Animator Monitor considers a slot supported when it finds `SlotXItemID`, then writes all four values for that slot. Keep the group together. Adding the parameters does not create animation states or transitions; add conditions for the new item's Animator Item ID, item ability state, and substate.
For dual pistols, `Slot0ItemID` and `Slot1ItemID` can contain the same Animator Item ID because the parameter names keep the two hands separate. For a sword and shield, the two parameters normally contain different Animator Item IDs.
## Verify in Play Mode
1. Open the runtime **Item Set Manager** and confirm each generated set places its Character Items in the intended array positions.
2. Equip a single right-hand item. Confirm only slot `0` becomes active and the visible object appears under the correct third-person or first-person attachment.
3. Switch perspective. Confirm the same Character Item resolves the equivalent slot instead of moving to another hand or disappearing.
4. Equip a sword and shield or another two-item set. Confirm one active Character Item occupies each slot.
5. Test a dual-wield definition with an Inventory amount of two. Confirm the right and left prefabs resolve independently and both Slot Item ID parameters show the intended Animator value.
6. Run slot-specific Use, Reload, and Drop inputs. Confirm only the requested hand responds; then test an all-slot value of `-1` deliberately.
7. Pick up, unequip, re-equip, and drop the item. Confirm the Item Set becomes valid or invalid without changing the Character Item's assigned slot.
8. For a custom slot, watch its four Animator parameters and confirm its states enter and leave cleanly.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| The item appears in the wrong hand. | Compare **Character Item > Slot ID** with the Character Item Slot ID on every active model and arm rig. | Give corresponding attachment points the same ID and rebuild or correct the Character Item's perspective parents. |
| **Build Character** or **Update Character** is disabled. | Open **Character Item Slots** and look for an invalid parent, duplicate parent, or duplicate ID within one model or arm group. | Assign a child of the displayed hierarchy and keep every parent and ID unique in that group. |
| **Build Item** reports that perspective slots do not match. | Compare the selected first- and third-person Character Item Slot IDs. | Select the equivalent locations or correct their IDs in Character Manager. |
| Inventory has more slots than expected. | Find the highest Character Item Slot ID and look for gaps or an obsolete component in an inactive hierarchy. | Remove the obsolete slot or make the intended IDs contiguous, then rebuild or reload the character before testing again. |
| The character owns the definition but no valid Item Set appears. | Check whether the definition has a Character Item prefab for the rule's exact array position and whether Inventory owns enough copies. | Add the missing slot-specific prefab, correct the rule position, or add the required amount. |
| The item is visible in one perspective only. | Check the active model or First Person Base Object for a matching Character Item Slot. | Add the missing logical slot and update the character, or remove support for the unused perspective from the Character Item. |
| The item equips but the Animator does not change. | Distinguish Slot ID from Animator Item ID and inspect the full four-parameter group. | Use the Animator Item ID expected by the controller and add the exact parameters and transitions for that slot. |
| One input uses or reloads both hands. | Inspect the ability's **Slot ID**. | Replace `-1` with the intended slot, or use separate slot-specific abilities and inputs. |
| Drop removes more equipment than intended. | Inspect **Drop > Slot ID**. | Replace the default `-1` with the one slot that the ability should drop. |
## Persistence and multiplayer
Treat Slot IDs as stable project data. A save system should restore Item Definition amounts and the intended Item Set, then let Inventory rebuild its slot-specific Character Items. Do not save scene Transform references or assume that a generated runtime Item Set index remains stable after its rules change.
The base Inventory forwards authoritative equip and unequip changes to a supported multiplayer integration with the Item Identifier and Slot ID. Every peer still needs the same slot map, Character Item prefabs, Item Definitions, and Item Set Rules. Keep third-person objects configured for remote observers; first-person objects remain a local-view concern unless the integration documents another ownership model.
## Related tasks
- [Item Creation](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-creation/) builds a slot-specific Character Item prefab or an item directly on a character.
- [Inventory](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/inventory/) owns Item Definition amounts and creates Character Items for their slots.
- [Item Type, Definition, and Category](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-type-definition-category/) explains the data identity shared by slot-specific Character Item prefabs.
- [Item Set and Rules](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-set-rules/) defines the combinations that may occupy the slot array.
- [Dual Wielding](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-creation/dual-wielding/) configures two hand slots, two Character Items, abilities, and animation together.
- [Character Item](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/) explains Slot ID, Animator Item ID, perspective objects, and equip timing.
- [Item Pickup](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-pickup/) adds definitions and can request a named Item Set.
- [Use](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/use/), [Reload](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/reload/), and [Drop](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/drop/) explain slot-specific ability targeting.
- [Equip Unequip](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/item-set/equip-unequip/) performs Item Set transitions across the changed slots.
- [Animator Parameters](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/animator-parameters/) documents the four per-slot parameters and their runtime values.
## Developer details
Use Inventory's slot-aware methods when code needs to inspect or change equipment:
```csharp
int slotCount = inventory.SlotCount;
CharacterItem activeItem = inventory.GetActiveCharacterItem(slotID);
CharacterItem item = inventory.GetCharacterItem(itemIdentifier, slotID);
inventory.EquipItem(itemIdentifier, slotID, immediateEquip: false);
inventory.UnequipItem(slotID);
```
Ordinary player equipment changes should still go through Item Sets and item abilities so animation, State System, timing, and networking remain coordinated.
The main slot-aware Inventory events are `OnInventoryEquipItem` and `OnInventoryUnequipItem`, each with `(CharacterItem, int slotID)`, plus `OnInventoryRemoveItem` with the removed Character Item and its Slot ID. Character Item registers `OnAnimatorItemEquip`, `OnAnimatorItemEquipComplete`, `OnAnimatorItemUnequip`, and `OnAnimatorItemUnequipComplete` as slot-filtered animation events.
In released Version 3.2.0, Inventory determines its array size from Character Item Slot components during initialization. The count can grow when a higher ID is discovered, but the same initialized Inventory instance does not reduce its stored count after a high-ID component is removed. Configure slots before Play Mode and recreate or reload the character after reducing the highest ID.
Runtime lookup does not enforce the Character Manager's uniqueness rules. Manually added duplicate IDs can make a perspective resolve the first matching component, and negative Character Item Slot IDs are not valid array positions. Prefer Character Manager, contiguous nonnegative IDs, and one component per logical location.
---
# Animator Audio State Set
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/animator-audio-state-set/)
An Animator Audio State Set lets an item action choose an animation variation, an optional UCC State, and audio as one coordinated result. Use it when equipping, using, reloading, recoiling, or impacting should not always produce the same presentation.
## Before you begin
- Create a working Character Item and the action that owns the behavior. The state set does not start an item action by itself.
- Confirm that the character Animator has transitions for the intended `SlotItemSubstateIndex` values. See [Animator Parameters](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/animator-parameters/).
- Decide which consumer owns this choice. **Equip Animator Audio State Set** and **Unequip Animator Audio State Set** belong to the Character Item; use, reload, melee recoil, and shield impact sets belong to their corresponding action or module.
- Keep the optional **State Name** separate from the Animator state. It names a UCC State to activate on the character while this entry is selected.
## Configure an Iron Sword attack sequence
This example alternates an Iron Sword between a right slash and a left slash. The example substate values `2` and `3` must correspond to transitions in your Animator Controller.
1. Select the Iron Sword Character Item and expand its Melee Action.
2. In **Trigger Modules**, select the enabled combo trigger and expand **Use Animator Audio State Set**.
3. Set **Selector** to **Sequence**.
4. Leave **Reset Delay** at `-1` when the sequence should continue across uses. Set a positive delay when the next attack after a pause should return to the first entry.
5. Add two entries to **Animator Audio States** and keep both **Enabled**.
6. Select the first entry and set **Item Substate Index** to `2`. Select the second and set it to `3`.
7. Leave **Allow During Movement** enabled unless a slash must be skipped while moving. Enable **Require Grounded** only for an attack that cannot run in the air.
8. Expand **Audio Clip Set**, assign its **Audio Config**, and add the clips that may accompany that entry. Multiple clips let the audio set choose a clip without changing the selected animation entry.
9. Leave **State Name** empty for a normal slash. Assign a State only when that variation must temporarily change another property, such as the attack's damage preset.
10. On the trigger module, choose whether **Play Audio On Start Use** should play the clip as the use begins or whether the owning use timing should play it when the item is used.
A Simple Combo or Repeat Combo trigger advances the set for each chained use. The state set selects the variation; the trigger and [animation event timing](https://opsive.com/support/documentation/ultimate-character-controller/animation/animation-event-trigger/) still decide when the attack starts, is applied, and completes.
### Editor checkpoint
Before entering Play Mode, the enabled trigger should show **Selector: Sequence**, two enabled entries, substate values `2` and `3`, and Animator transitions for both values. Each entry should have at least one selectable condition and only the audio and optional UCC State that belong to that variation.
## Configure firearm variations
For a firearm, use **Random** when several firing animations or sounds are interchangeable:
1. Expand the firearm's trigger module and its **Use Animator Audio State Set**.
2. Set **Selector** to **Random** and add one entry for each firing variation.
3. Give every entry an **Item Substate Index** that the firearm's Animator supports, then configure its **Audio Clip Set**.
4. Expect Random to choose with replacement, so the same variation can occur twice in a row.
5. Keep **State Name** empty unless you have accounted for the released-Version-3 initialization limitation described below.
Configure reload presentation separately under the shootable action's **Reload Animator Audio State Set**. A full-magazine reload normally needs one entry; a shell-by-shell reload can advance its set as each round is inserted. Do not combine firing and reload substates merely because both belong to the same firearm.
## Key choices
| Selector | Use it when | Important behavior |
| --- | --- | --- |
| **Sequence** | Attacks, equips, or reload stages should advance in order. | This is the default selector. **Reset Delay** defaults to `-1`, which never resets the sequence because of elapsed time. Invalid or disabled entries are skipped and the list wraps. |
| **Random** | Any eligible variation may play next. | A choice may repeat. Movement, grounded, and enabled checks are applied before the entry is accepted. |
| **Matching Recoil** | A melee recoil should correspond to the Use variation that caused the hit. | Released Version 3 uses the final numeric Use substate directly as a zero-based recoil entry index. Keep that value in range and align the recoil list accordingly; a blocked recoil then adds the configured blocked offset. |
| **Sequence Recoil** | Recoil variations should advance in order. | It has the same reset behavior as Sequence and defaults **Blocked Recoil Item Substate Index** to `20`. |
| **Random Recoil** | Recoil variations may be chosen randomly. | It uses the same blocked offset and eligibility checks as the other recoil selectors. |
Each entry starts with **Enabled** and **Allow During Movement** on, **Require Grounded** off, **State Name** empty, and **Item Substate Index** `0`. Disable an entry to keep its configuration without selecting it. Always leave at least one enabled entry whose movement and grounded requirements can be met.
Leave **State Name** empty on Matching Recoil entries in released Version 3. The recoil owner starts selection before copying the current Use substate into that selector, so a named State can be activated or deactivated from the previous row rather than the current hit.
The selected entry controls two independent choices:
- **Item Substate Index** contributes the variation value used by the owning item ability or action. The Animator must already know what that value means.
- **Audio Clip Set** chooses audio from that entry when the owner requests playback. It does not choose a different Animator entry.
## How it runs
The owning Character Item or action initializes the set with its Character Item and Ultimate Character Locomotion. When the operation starts, the owner starts selection and advances the selector. The selector skips entries that are disabled, disallow the character's current movement, or require a grounded character when the character is airborne.
After an entry is selected, its **State Name** is activated through the UCC State System and its **Item Substate Index** is returned to the owner. The owner combines that value with its own item-state data and updates the slot's Animator parameters. It also decides when to call the entry's Audio Clip Set and which visible item or character GameObject emits the clip. When the operation stops or the selector changes entries, the previous named State is deactivated.
Equip and unequip are timed by `OnAnimatorItemEquip`, `OnAnimatorItemEquipComplete`, `OnAnimatorItemUnequip`, and `OnAnimatorItemUnequipComplete`, or their configured delays. Use, reload, and shield impact have their own animation-event or duration controls. The Animator Audio State Set supplies the selected variation; it does not replace those timing controls or call an Animator trigger directly.
### Persistence and multiplayer
The selector type, entries, conditions, State names, substate values, Audio Config, and clips serialize with their owning item or action. The current and next runtime indexes are not save data; after loading or respawning, let the owning item/action initialize and select again.
Animator Audio State Set has no built-in network message for its chosen index or random audio clip. A networking integration can synchronize the owning action and Animator parameters, but separate Random selectors are not guaranteed to make the same choice. If an exact variation affects gameplay or must match across clients, synchronize that decision through the game/network integration instead of relying on local randomness.
## Verify in Play Mode
1. Equip the Iron Sword and watch its live `SlotItemStateIndex` and `SlotItemSubstateIndex` parameters in the Animator.
2. Perform two valid combo attacks. The first should use substate `2`, the second `3`, with the matching clip and no unrelated UCC State left active afterward.
3. Wait longer than a positive **Reset Delay** and attack again. The sequence should return to its first eligible entry; with `-1`, it should continue wrapping normally.
4. Test while moving and airborne. Entries should be skipped only when their **Allow During Movement** or **Require Grounded** settings require it.
5. Fire the firearm repeatedly. Every selected substate must have a valid transition, audio must occur at the chosen start/use timing, and repeated Random choices should remain valid.
6. Reload the firearm and confirm the reload set, not the firing set, controls its substate and audio.
7. If multiplayer is enabled, compare the authoritative and remote character. Confirm that any gameplay-significant variation is explicitly synchronized.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| The action runs but the animation does not change. | Watch the live slot Item State and Item Substate parameters and compare them with the Animator transitions. | Add or correct the transition for the complete value produced by the action and selected entry. |
| Sequence always appears to use one entry. | Confirm that every list row is enabled and that the owning trigger advances the set for each use. | Enable the intended rows and use a combo/repeat workflow when multiple chained uses are expected. |
| No entry can be selected. | All entries may be disabled or rejected by movement and grounded requirements. | Keep at least one enabled entry valid for the current locomotion state. |
| The wrong entry plays while moving or airborne. | Inspect **Allow During Movement** and **Require Grounded** on that entry. | Set the two conditions to match the gameplay rule and retest both locomotion states. |
| The correct animation plays but audio is silent. | Check **Audio Config**, the clip list, the visible item, and **Play Audio On Start Use** versus the owner's event timing. | Assign valid audio, then choose the start/use moment that the owning action actually reaches. |
| A UCC State stays active longer than expected. | **State Name** may be assigned to the wrong entry, or the owning operation may not reach its stop path. | Remove unnecessary State names and verify that the use, equip, reload, recoil, or impact completes normally. |
| A Random entry's State is active before the item is used. | In released Version 3, Random and Random Recoil call `NextState()` during initialization, which can activate the first valid entry's **State Name**. | Leave **State Name** empty on those selectors or manage that State from the owning action. |
| Matching Recoil returns no variation or changes the wrong UCC State. | The Use substate may not be a zero-based, in-range recoil entry index, or the recoil entries may have **State Name** values. | Align the Use values with the recoil list and leave Matching Recoil **State Name** empty in released Version 3. |
| Clients show different Random variations. | The set does not network its random choice. | Synchronize the chosen variation through the networking integration when the exact result must match. |
## Related tasks
- [Character Item](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/)
- [Usable Item Action](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/)
- [Melee Action](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/melee/)
- [Shootable Action](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/shootable/)
- [Use ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/use/)
- [Reload ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/reload/)
- [Block ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/block/)
- [Equip Unequip](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/item-set/equip-unequip/)
- [State System](https://opsive.com/support/documentation/ultimate-character-controller/state-system/)
## Developer reference
`AnimatorAudioStateSet` exposes `Awake`, `StartStopStateSelection`, `GetStateIndex`, `GetNextStateIndex`, `SetNextStateIndex`, `GetItemSubstateIndex`, `PlayAudioClip`, `NextState`, and `OnDestroy`. Array-index variants are also available for a custom selector that owns more than one pending choice.
To add a selection policy, derive from `AnimatorAudioStateSelector`. The released Version 3 initialization signature is `Initialize(GameObject, UltimateCharacterLocomotion, CharacterItem, AnimatorAudioStateSet.AnimatorAudioState[], int count)`. Override the current/next index accessors and `NextState()` as needed; `NextState()` returns whether selection changed successfully. Override `GetAdditionalItemSubstateIndex()` when a context such as blocked recoil must add an offset.
The set itself raises no public gameplay event. Its optional named State is changed through `StateManager`, while the owning Character Item or action controls animation events, audio timing, and any network or save integration.
---
# Item Pickup
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-pickup/)
Item Pickup adds one or more Item Definitions to a character's Inventory from a world object. Use it for scene loot, ammunition bundles, and items that a character can drop and collect again.
## Before you begin
- Create the Item Definitions that the pickup will grant. An equippable definition also needs a Character Item prefab, a compatible slot, and a valid Item Set Rule on the character.
- Confirm the character has an enabled [Inventory](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/inventory/). Equipping also requires an Item Set Manager.
- Use a visual model rather than an already built Character Item when creating the pickup.
## Create the pickup object
1. Open **Tools > Opsive > Ultimate Character Controller > Object Manager**.
2. In **Object Builder**, enter a **Name** and assign the visible model to **GameObject**.
3. Set **Object Type** to **Item Pickup** for loot placed in the scene. This route adds an Item Pickup, a trigger collider, a solid collider, and a Respawner.
4. Set **Object Type** to **Dropped Item** when the prefab will be assigned to a Character Item's **Drop Prefab**. This route adds an Item Pickup, colliders, and a Trajectory Object instead of a Respawner.
5. Select **Build Object**, choose where to save the prefab, and then select the created object.
6. On **Item Pickup**, add an entry to **Item Definition Amounts** for every definition and quantity that a scene pickup should grant.
7. Size the trigger collider around the interaction area. The trigger must be on the same GameObject as Item Pickup.
### Editor checkpoint
A scene pickup should have **Item Pickup**, one collider with **Is Trigger** enabled, a solid collider for its physical shape, and **Respawner** when it should return. A dropped-item prefab should have **Trajectory Object** and normally leaves **Item Definition Amounts** for the Drop workflow to fill at runtime.
## Configure what the pickup grants
Each **Item Definition Amounts** row adds that definition up to its Item Type's configured **Capacity**.
### Iron Sword pickup
1. Add the Iron Sword Item Definition with an amount of `1`.
2. Enable **Equip** when the sword should become active immediately after collection.
3. Leave **Item Set Group** at `-1` to search all groups, or enter the group that owns the sword.
4. Leave **Item Set Name** empty to use the first valid set containing the sword. Enter a name only when the pickup must select a specific Item Set State; the text must match that State name exactly.
Disable **Equip** when the sword should enter the Inventory without changing the current loadout.
### Firearm and ammunition pickup
Add the firearm Item Definition with an amount of `1`, then add its ammunition Item Definition with the desired quantity. Enable **Equip** to select a valid firearm Item Set after both definitions are added. The firearm needs a Character Item prefab in the appropriate slot; count-only ammunition does not need a visible Character Item.
The Inventory limits each amount by the Item Type's **Capacity**. Test a nearly full Inventory so the object and the accepted amounts match the intended game design.
## Choose how collection starts
### Collect on contact
Keep **Pickup On Trigger Enter** enabled for the default no-input workflow. When an eligible character enters the trigger, Item Pickup finds its Inventory, adds the configured definitions, optionally selects an Item Set, and then depletes the world object. The character does not need the Pickup ability for this route.
Use this for ammunition, automatic loot, and other objects where walking through the trigger is the complete interaction.
### Play a pickup animation
Disable **Pickup On Trigger Enter** when the character should press an input and play a reach animation.
1. Add the [Pickup ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/detect-object-ability-base/pickup/) to the character.
2. Keep **Allowed Pickups** set to **Item**, and ensure the ability's **Detect Layers** includes the pickup layer.
3. Use **Pickup Event** to add the item at the contact frame. The included event name is `OnAnimatorPickup`.
4. Use **Pickup Complete Event** to finish the ability. The included completion event is `OnAnimatorPickupComplete`.
An empty **Pickup Item Definitions** list lets any detected Item Definition use the animation. If only selected definitions should animate, use a single filter entry and verify the result in Play Mode; see the released-version note under [Developer details](#developer-details).
### Reuse a Character Item as a world drop
1. Build the prefab with **Object Type > Dropped Item**.
2. Assign it to the Character Item's **Drop Prefab** field.
3. Add a [Drop ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/drop/) to the character.
At runtime, Drop replaces the prefab's **Item Definition Amounts** with the unit removed from the Inventory and any additional identifiers supplied by the Character Item's actions, such as ammunition. If the prefab has a Trajectory Object, Drop also initializes its motion from the character.
## Key choices
| Choice | Starting value | Use it when |
| --- | --- | --- |
| **Trigger Enable Delay** | `4` seconds | A reused or dropped pickup must wait before it can be collected again. On its first scene activation, the trigger is enabled immediately. |
| **Pickup On Trigger Enter** | Enabled | Contact should collect the object. Disable it for the Pickup ability workflow. |
| **Always Pickup** | Disabled | Enable it when the object should be consumed even when the Inventory cannot accept more. The released Version 3.2.0 capacity behavior has a limitation described under [Developer details](#developer-details). |
| **Equip** | Enabled | A valid Item Set containing a collected Character Item should become active. Use and Reload can prevent the equip change while they are active. |
| **Item Set Group** | `-1` | All Item Set groups should be searched. Enter a group index to constrain selection. |
| **Item Set Name** | Empty | The first valid set containing the item is acceptable. Enter an exact State name to request one set. |
| **Destroy Delay** | `0` | The collected object should be removed immediately. Use a positive value for delayed removal; `-1` leaves a depleted object present and does not make it repeatable. |
Use **Rotation Speed** for a simple display rotation. **Pickup Audio Clip Set**, **Pickup Message Text**, and **Pickup Message Icon** provide collection feedback. **On Select** and **On Deselect** are useful when the Pickup ability detects the object before the input is pressed.
For a reused pickup with a Rigidbody, **Trigger Enable Delay** starts after the Rigidbody settles. The Object Manager's **Dropped Item** uses Trajectory Object without adding a Rigidbody, so its delay starts when the drop is initialized rather than when the trajectory visibly stops. Set a delay long enough for the flight, or add a project-specific gate when collection must wait for landing.
## Verify in Play Mode
1. Keep the character's Inventory and the pickup's Item Pickup component visible.
2. Enter an automatic pickup trigger. Confirm the configured Item Definition amounts increase once, the world object is removed or deactivated, and **Equip** selects the intended Item Set when enabled.
3. Repeat with the Inventory close to the Item Type's **Capacity**. Confirm only the allowed amount is added and review the capacity limitation below if the world object is consumed after adding zero.
4. For an animated pickup, enter the detection trigger and press the configured input. Confirm the object remains until the pickup event, the Inventory changes on `OnAnimatorPickup`, and the ability stops on `OnAnimatorPickupComplete` or its configured duration.
5. Drop an equipped Iron Sword or firearm. Confirm the world object receives the dropped definition and quantity, cannot be recollected during **Trigger Enable Delay**, and restores the item when collected.
6. For a scene pickup with Respawner, wait for its configured respawn time and confirm it returns ready to collect again.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| Contact does not collect the item. | Check for a trigger collider on the Item Pickup GameObject, an enabled character Inventory, the pickup and character layers, and **Pickup On Trigger Enter**. | Restore the trigger and collision-layer interaction. Enable contact pickup, or complete the Pickup ability setup for an input-driven object. |
| The item is collected before its animation. | **Pickup On Trigger Enter** is still enabled. | Disable it and let the Pickup ability perform the transfer at **Pickup Event**. |
| The Inventory changes but no held item appears. | Check the Character Item prefab, slot, Item Set Rule, **Equip**, **Item Set Group**, and **Item Set Name**. Also check whether Use or Reload is active. | Complete the Character Item and Item Set setup, correct the exact State name, and retry when the conflicting ability is inactive. |
| Pickup starts but the Inventory never changes. | **Pickup Event** may be waiting for a missing `OnAnimatorPickup`. | Add the event to the active clip, or disable event waiting and use a duration. |
| The Inventory changes but Pickup stays active. | **Pickup Complete Event** may be waiting for a missing `OnAnimatorPickupComplete`. | Add the completion event, or use duration mode. |
| A dropped item is collected while still moving. | **Trigger Enable Delay** may expire before a Trajectory Object finishes moving. | Increase the delay or add a landing-aware project-specific gate. |
| The model remains but cannot be collected again. | **Destroy Delay** may be `-1`; the object remains depleted after collection. | Use Respawner or explicitly reinitialize the object instead of treating `-1` as repeatable mode. |
| The object is consumed even though capacity prevented an addition. | This is a released Version 3.2.0 Item Pickup result-check limitation. | Avoid relying on **Always Pickup** for full-capacity persistence; precheck capacity or use a corrected custom Item Pickup when the world object must remain. |
## Persistence, pooling, and multiplayer
The Object Manager's scene **Item Pickup** includes a Respawner, so a non-pooled object can be reactivated after it is disabled. A pooled pickup returns through the Opsive object pool and resets when reused. Verify the selected lifetime path returns the pickup once with the expected delay.
Item Pickup does not by itself save world depletion or respawn timers. A save integration must persist both the authoritative Inventory and any pickup state that should survive loading; otherwise a saved Inventory can coexist with a newly restored copy of the world item.
The multiplayer hooks are compiled only with a supported UCC multiplayer integration. That integration owns Inventory replication and network object spawning or destruction. Item Pickup alone is not a transport or authority system, so verify collection and dropped-prefab ownership with the chosen integration.
## Related tasks
- [Inventory](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/inventory/) configures capacities, Character Item prefabs, and runtime item ownership.
- [Item Creation](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-creation/) builds the Item Definition and Character Item used by an equippable pickup.
- [Item Set Rules](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-set-rules/) determine which collected items form a valid loadout.
- [Character Item](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/) explains the held item and its **Drop Prefab**.
- [Pickup ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/detect-object-ability-base/pickup/) configures input, detection, and animation timing.
- [Drop](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/drop/) removes an equipped unit and initializes its pickup prefab.
- [Trajectory Object](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/) controls motion on a dropped-item prefab.
- [Respawner](https://opsive.com/support/documentation/ultimate-character-controller/spawn-system/respawner/) controls when a scene pickup returns.
## Developer details
`ItemPickup` derives from `ItemPickupBase`, which derives from `ObjectPickup`. The public pickup flow wraps the inventory transfer with `OnItemPickupStartPickup` and `OnItemPickupStopPickup`; a completed object pickup sends `OnObjectPickedUp`. Inventory additions send `OnInventoryPickupItemIdentifier`, and a spawned Character Item also sends `OnInventoryPickupItem`.
`Destroy Delay` equal to `0` removes the pickup immediately, a positive value schedules removal, and a negative value leaves it active but depleted. Pooled objects use `ObjectPoolBase.Destroy`; a supported multiplayer build uses its network object pool. Non-pooled objects are deactivated so a Respawner can restore them.
The released Version 3.2.0 source has two pickup edge cases to account for:
- Item Pickup treats an Inventory return value of `0` as a successful transfer. Because `0` is also returned when capacity accepts none of a valid definition, the world object can become depleted even while **Always Pickup** is disabled. Precheck capacity or use a corrected `ItemPickupBase` implementation when the object must remain.
- With more than one **Pickup Item Definitions** filter entry on the Pickup ability, a nonmatching first entry can prevent later entries from selecting the animated path. Prefer one entry per Pickup ability and verify multi-definition filters before shipping.
---
# Animation
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/animation/)
Ultimate Character Controller uses Unity's Animator for authored character and item clips, Animator Monitor to connect controller values to Animator parameters, Animation Event Triggers to coordinate gameplay timing, and springs for procedural camera and item motion. Start with the supplied Animator Controller as a working reference, then customize one behavior at a time and verify it in Play Mode.
## Understand the animation parts
- **Animator Controller:** Owns animation states, transitions, layers, masks, and clips for locomotion, abilities, and item actions. [Animator](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/) is the entry point for this workflow.
- **Animator parameters and Animator Monitor:** Animator Monitor transfers movement, ability, and item values to the Animator. A custom controller can use a different state-machine layout, but it must include the parameters required by the character and item setup.
- **Animation Event Trigger:** Lets an ability or item action wait for a named animation event or use a duration instead. This keeps gameplay actions synchronized with authored clips without putting gameplay logic in the Animator Controller.
- **Item animation selection:** Animator Item ID, Movement Set ID, Item State Index, and Item Substate Index select the equipped-item stance and action variation. Visible first-person or third-person items can also have their own Animator Controller.
- **Procedural motion:** [Springs](https://opsive.com/support/documentation/ultimate-character-controller/animation/springs/), bobs, and noise add responsive motion such as first-person item sway, camera movement, and recoil without replacing an animation clip.
## Follow the recommended workflow
1. Build or select a working character through [Character Creation](https://opsive.com/support/documentation/ultimate-character-controller/character/character-creation/), then enter Play Mode with the supplied Animator Controller unchanged.
2. Test idle, movement, jump and fall, one ability, and one item. This baseline separates setup problems from later animation changes.
3. Read [Animator Controller](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/animator-controller/) to understand the supplied layers, then use [Animator Parameters](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/animator-parameters/) and [Default Animator Values](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/default-animator-values/) when building a project-specific controller.
4. Keep a project-owned copy of the controller before replacing clips. Use [Replacing Animations](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/replacing-animations/) to preserve all affected layers and event timing.
5. Review every changed clip for its required [Animation Event Trigger](https://opsive.com/support/documentation/ultimate-character-controller/animation/animation-event-trigger/). When an event is not appropriate, deliberately configure the trigger to use its duration instead.
6. Configure item animation IDs, controllers, states, and variations through [Item Creation](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-creation/) and [Animator Audio State Set](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/animator-audio-state-set/).
7. Add procedural spring, bob, or noise motion only after the authored clips and gameplay timing work correctly.
## Replace supplied clips safely
For a small change, replace the clip in every Animator layer and state that uses it. A locomotion or item clip may appear in multiple masked layers, so changing only the Base Layer can cause the upper and lower body to disagree.
For a larger replacement set:
1. Open **Tools > Opsive > Ultimate Character Controller > Animation Replacer**.
2. Assign the project-owned controller to **Animator Controller**.
3. Optionally assign a **Replacement Template**, or assign replacement clips individually.
4. Leave **Replace Events** enabled when the replacement clips should receive the events from the supplied clips.
5. Review the replacement mapping, select **Replace**, then test the changed controller before replacing another group.
The Animation Replacer updates clips; it does not decide whether a replacement pose, mask, transition, or event time is correct for the project.
## Coordinate gameplay with animation events
Use [Animation Event Trigger](https://opsive.com/support/documentation/ultimate-character-controller/animation/animation-event-trigger/) for ability timing such as the point when Jump applies its force. With **Wait For Animation Event** enabled, the clip must send the event expected by that field. In Unity's Animation window, set the event **Function** to `ExecuteEvent` and its **String** value to the expected event name.
Use [Animation Slot Event Trigger](https://opsive.com/support/documentation/ultimate-character-controller/animation/animation-event-trigger/animation-slot-event-trigger/) when item timing must distinguish between item slots. For a character with both perspectives, update the event on every first-person and third-person clip that can perform the action.
If the timing is wrong, enable **Log Events** on Animator Monitor. The Console call stack shows whether the event came from the Animator or from the duration-based Scheduler path.
## Configure item animations
Treat an item animation as three connected choices:
1. **Which item is equipped:** **Animator Item ID** drives the slot's Item ID parameter.
2. **Which action and variation should play:** Item State Index and Item Substate Index select actions such as equip, use, or reload and their variations. [Animator Audio State Set](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/animator-audio-state-set/) controls how a variation is selected.
3. **Which model animates:** A visible first-person or third-person item can use its own Animator Controller in addition to the character's controller.
When both perspectives are supported, verify the character body, first-person arms, and visible item together. Generic first-person arm rigs cannot use Unity's humanoid retargeting; see [First Person Arms](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/first-person-arms/) before replacing that rig or its clips.
## Add procedural motion
Use [Springs](https://opsive.com/support/documentation/ultimate-character-controller/animation/springs/) when the result should react continuously instead of playing a fixed skeletal clip. Stiffness controls how strongly the value returns toward rest, while damping controls how quickly its velocity settles. Bobs provide repeating sinusoidal movement, and noise provides irregular motion.
Tune one source at a time. First verify the authored animation with springs, bobs, and noise minimized; then add procedural motion and confirm that it returns to rest without persistent drift or excessive camera movement.
## Continue by task
- **Understand or replace Animator content:** [Animator](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/) routes to the supplied controller structure, parameters, default values, first-person arms, and clip replacement.
- **Synchronize an ability or item action:** [Animation Event Trigger](https://opsive.com/support/documentation/ultimate-character-controller/animation/animation-event-trigger/) covers named events, duration fallback, logging, and slot-aware item events.
- **Add camera or item motion without another clip:** [Springs](https://opsive.com/support/documentation/ultimate-character-controller/animation/springs/) covers springs, bobs, noise, and their tuning fields.
## Verify in Play Mode
1. Open the Animator window and select the active character. Movement parameters should change as the character starts, stops, turns, and changes speed, and the controller should return cleanly to idle.
2. Run each changed ability. Confirm that its Ability Index and data parameters select the expected state and return when the ability ends.
3. Equip, aim, use, reload, and unequip each changed item. Confirm the correct slot Item ID, Item State Index, and Item Substate Index, plus matching body and visible-item animation.
4. Test animation-driven events at normal speed and during rapid input. The ability or item action should not complete before the intended frame or remain stuck waiting for an event.
5. When both perspectives are present, repeat the action in first person and third person and confirm that both sets of clips and events agree.
6. Re-enable procedural motion and confirm that recoil, sway, bob, and noise react as intended and settle back to rest.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| The character does not leave idle or uses the wrong state. | Required Animator parameters or transitions may be missing from the custom controller. | Compare the controller with [Animator Parameters](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/animator-parameters/) and watch the live values in the Animator window. |
| An ability or item remains active indefinitely. | An Animation Event Trigger may be waiting for an event the replacement clip never sends. | Add the expected `ExecuteEvent` event and String value, or disable **Wait For Animation Event** and configure a deliberate duration. |
| A replacement affects only part of the body. | The old clip may still be used on another masked layer. | Search every layer for the old clip and replace each intended occurrence. |
| The wrong item animation plays. | Animator Item ID, Movement Set ID, slot Item State Index, or Item Substate Index may not match the Animator states. | Compare the live parameters with the item's configured IDs and Animator Audio State Set. |
| First-person arms distort or do not retarget. | The arms may use a generic rig. | Use clips authored for that rig or follow the alternatives in [First Person Arms](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/first-person-arms/). |
| Camera or item motion oscillates for too long. | Spring stiffness and damping may not be balanced. | Minimize other motion sources, tune stiffness and damping together, then restore bob and noise one at a time. |
---
# Springs
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/animation/springs/)
Springs add responsive camera and item motion without requiring an animation clip. Use them for movement sway, landing impact, recoil, and other motion that should return to a rest position or rotation.
## Find the spring controls
The same Spring controls appear inside several Ultimate Character Controller features. Start with the object whose motion you want to change:
1. For camera motion, select the camera with the **Camera Controller** component, expand **View Types**, and select the active first- or third-person View Type.
2. Expand **Primary Spring** to tune regular position and rotation response. Expand **Secondary Spring** for brief reactions such as recoil.
3. For first-person item motion, select the item object with the **First Person Perspective Item** component and expand its **Position Spring**, **Rotation Spring**, or pivot spring.
4. Enter Play Mode with the supplied values first. Change one spring and one axis at a time so that authored animation, head motion, bob, and shake are not mistaken for spring motion.
## Choose the motion source
| Desired result | Controls to use | Why |
| --- | --- | --- |
| Regular camera or item response while moving | **Primary Spring** | Its Position and Rotation Springs handle continuous motion around their rest values. |
| Recoil or another brief impulse | **Secondary Spring** | It is intended to receive a short force and return to equilibrium. |
| A repeatable walking rhythm | **Bob** | Rate sets how quickly the cycle repeats; amplitude sets how far it moves. |
| Irregular breathing, instability, or camera shake | **Shake** | Speed and amplitude generate continuous smooth variation rather than a repeating cycle. |
| A deliberate pose or repeatable action such as reloading | An animation clip, optionally combined with subtle procedural motion | Springs react to forces; they do not replace authored action timing. |
### Bob
Bob adds sinusoidal motion to the first-person camera or item. A small vertical amplitude can suggest footsteps, while carefully balanced horizontal and vertical amplitudes can make a large character feel heavier.
Use **Bob Positional Rate** and **Bob Roll Rate** for frequency, and use their amplitude fields for strength. **Bob Input Velocity Scale** changes how strongly character speed feeds the effect, while **Bob Max Input Velocity** prevents extreme movement speeds from producing extreme bob. Keep **Bob Require Ground Contact** enabled when normal walking bob should stop in the air.
### Shake
Shake adds smooth, irregular rotation to the first-person view. It is useful for restrained breathing motion, status effects, or a brief unstable-camera presentation, but large continuous values can make the view uncomfortable.
Use **Shake Speed** to change how quickly the variation develops and **Shake Amplitude** to limit its strength on each axis. Start with a very small amplitude and test while moving and aiming, not only while idle.
## Tune a spring
Expand a Spring property to reveal its shared settings:
| Setting | What it changes in Version 3 |
| --- | --- |
| **Stiffness** | Controls the pull toward the rest value. The current calculation uses `1 - Stiffness`, so a lower value produces a stronger return and a higher value produces a weaker return. |
| **Damping** | Multiplies the remaining velocity on every update. A lower value removes velocity faster; a higher value preserves it longer and can allow more oscillation. |
| **Velocity Fade In Length** | Scales newly applied forces from zero to their full strength for this duration after the spring initializes, reducing an abrupt start. |
| **Max Soft Force Frames** | Limits how many frames a soft force can be distributed across. More frames spread the same force over a longer interval. |
| **Min Velocity** | Sets the final snap-to-rest tolerance. Increase it slightly when tiny residual movement takes too long to finish. |
| **Max Velocity** | Caps the magnitude of the spring velocity so a large force cannot produce an unlimited response. |
| **Min Value** and **Max Value** | Clamp the resulting position or rotation on each axis. Use them as safety limits, not as the main way to shape the motion. |
Because **Stiffness** and **Damping** follow the shipped Spring calculation, their tuning direction may be different from what their everyday names suggest. Change one of them at a time and judge the complete return-to-rest motion in Play Mode.
## Tune common scenarios
### Recoil
Use the Secondary Position or Rotation Spring for the short impulse. Begin with a small force, lower **Damping** if the camera or item keeps ringing, and use value limits to prevent an extreme kick. The motion should return to its original framing without a lasting offset.
### Landing impact
On a first-person camera, **Position Fall Impact** pushes the position spring when the character lands, and **Rotation Fall Impact** adds roll. Their **Softness** fields distribute that force across a number of frames. Increase softness for a less abrupt reaction; reduce the impact values if normal jumps are distracting.
### Movement sway
Use the primary position and rotation springs for regular camera or first-person item response. On an item, the sway, slide, and input-velocity fields determine which character movement feeds those springs. Establish the spring return first, then introduce look sway, strafe sway, or slide one source at a time.
### Heavy footsteps
Use Bob for the repeating step rhythm. The camera's **Bob Min Trough Vertical Offset** identifies the lower part of the cycle, and **Bob Trough Force** can add a short secondary reaction there. Keep the force small and verify it at every supported movement speed.
## Verify in Play Mode
1. Stand still after the character and camera initialize. The tested object should settle at its rest position or rotation without drifting.
2. Walk, run, strafe, jump, and land. Regular motion should remain controlled and return to rest after input stops.
3. Trigger recoil or the feature that adds a secondary force. The impulse should be readable, then finish without a permanent offset or repeated vibration.
4. Test the lowest and highest supported movement speeds. Bob and sway should not grow beyond the intended range.
5. Switch perspectives, equip and unequip items, and pause or change the character time scale if those actions are supported. Motion should resume from a stable state rather than carrying an unrelated force into the new state.
6. Repeat the test while aiming at a small target. The effect should communicate motion without obscuring gameplay or making the camera uncomfortable.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| Motion oscillates for too long. | **Damping** may be preserving too much velocity, or several motion sources may be active together. | Lower **Damping**, then disable bob, shake, and authored motion temporarily to isolate the spring. |
| The object returns too slowly. | A high **Stiffness** weakens the return in the Version 3 calculation. | Lower **Stiffness** in small steps and retest the full motion. |
| Motion snaps when the scene starts. | **Velocity Fade In Length** may be too short for forces applied immediately after initialization. | Increase the fade-in length and replay the scene from its initial state. |
| A landing or other event snaps. | Its soft force may be applied across too few frames. | Increase that feature's **Softness** value without changing the total force, then repeat the event. |
| Tiny movement never appears to finish. | The **Min Velocity** snap-to-rest tolerance may be too small, or another bob or shake source may still be running. | Increase the tolerance slightly and isolate the other procedural motion groups. |
| Fast movement produces a large sway or bob spike. | Input velocity may be scaled too strongly or allowed to grow too high. | Reduce the relevant input velocity scale and set a suitable maximum input velocity. |
| Walking bob continues while airborne. | **Bob Require Ground Contact** is disabled. | Enable it when bob should be driven only by grounded movement. |
| A spring does not move. | The force or amplitude may be zero, the value may already be clamped, or the character or global time scale may be zero. | Confirm the source value, limits, active View Type or item, and time scale before changing the spring response. |
## Related tasks
- [Configure a first-person View Type](https://opsive.com/support/documentation/ultimate-character-controller/camera/view-types/included-view-types/first-person/)
- [Configure a third-person View Type](https://opsive.com/support/documentation/ultimate-character-controller/camera/view-types/included-view-types/third-person/)
- [Configure a first-person perspective item](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/first-person-perspective/)
- [Add first-person leaning](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/first-person-lean/)
- [Set up the Animator](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/)
- [Configure inverse kinematics](https://opsive.com/support/documentation/ultimate-character-controller/inverse-kinematics/)
## Developer reference
`Spring` is initialized as positional or rotational and schedules its update in either Update or Fixed Update. Each update pulls the current value toward `RestValue`, multiplies the accumulated velocity by **Damping**, clamps the velocity and value, and resets when the remaining distance is within **Min Velocity**. A soft force divides its total force across the requested number of frames, capped by **Max Soft Force Frames**. Spring updates stop while the spring's local time scale or the global `TimeUtility.TimeScale` is zero.
---
# Animator
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/)
Use the Animator workflow to connect Ultimate Character Controller gameplay to a humanoid or generic model, then customize states, clips, and first-person arms without breaking the controller's parameter contract.
## Start with a working character
The Character Manager is the supported starting point because it assigns the Animator Controller, adds Animator Monitor, and ensures the controller contains the required parameters.
1. Open **Tools > Opsive > Ultimate Character Controller > Character Manager**.
2. Select the character and enable **Animator**.
3. For each configured model, choose **Model Type**:
- Choose **Humanoid** for a valid humanoid Avatar. The supplied Animator Controller can provide a working baseline.
- Choose **Generic** for a non-humanoid rig. Assign an Animator Controller made for that rig; the supplied humanoid controller cannot be used as its animation source.
4. Assign the controller in **Animator Controller**.
5. Select **Build Character** for a new character or **Update Character** for an existing one.
6. Select the configured model in the Hierarchy. It should have both **Animator** and **Animator Monitor** components when it uses full-body animation.
7. Enter Play Mode before changing the supplied controller. Confirm idle, movement, turning, one ability, and one equipped-item action so the original setup provides a known-good baseline.
A first-person-only character can operate without a full-body Animator. Animator Monitor still holds the controller values and can forward them to supported item animators.
## Follow the recommended customization route
1. Read [Animator Controller](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/animator-controller/) to understand the supplied layers, masks, and the difference between locomotion, ability, and item states.
2. Keep the names and types documented in [Animator Parameters](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/animator-parameters/). A custom state-machine layout is allowed, but its transitions still depend on the controller values that Animator Monitor updates.
3. Use [Default Animator Values](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/default-animator-values/) when matching an Ability Index, Item State Index, Animator Item ID, or Movement Set ID to a transition.
4. Make a project-owned copy of the working controller before editing states or clips.
5. Change one behavior at a time. Watch the live parameters and active state in Unity's Animator window before moving to the next change.
6. Use [Replacing Animations](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/replacing-animations/) for clip changes, including every affected layer and required animation event.
7. Treat [First Person Arms](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/first-person-arms/) as a separate rig decision. The supplied first-person arms use a generic rig, so their clips must be authored for that rig rather than humanoid-retargeted automatically.
## Make the important choices
### Supplied or custom controller
Use the supplied controller to establish a working baseline and as a reference for parameters, layers, masks, and transition conditions. Use a project-owned controller when the game's state layout or animation set differs substantially. The layout itself is flexible; the required parameter names, types, IDs, and event timing are the compatibility points.
### Humanoid or generic model
Humanoid models can use Unity retargeting and the supplied humanoid controller. Generic models need clips and an Animator Controller made for their hierarchy. Changing **Model Type** to **Generic** in Character Manager intentionally clears the supplied controller selection so a compatible controller can be assigned.
### Full body or separate first-person arms
A full-body model normally has Animator Monitor beside its Animator. Visible first-person arms or item objects can use their own Animator and Child Animator Monitor. When both perspectives are supported, verify the character body, arms, and visible items because they can use different controllers and clips.
### Animator Monitor tuning
Keep **Animator Speed** at `1` unless all animation playback on that Animator should be scaled. **Update Mode** is passed to Unity's Animator. The **Time** foldout contains damping for Horizontal Movement, Forward Movement, Pitch, and Yaw; change these only when the live parameter response needs to be smoother or more immediate. **Yaw Multiplier** affects turning in place, and **Moving Speed Parameter Value** defines the Speed value Animator Monitor uses while the character is moving.
## Continue by task
- [Animator Controller](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/animator-controller/) explains the supplied state-machine and layer structure and how to approach a custom controller.
- [Animator Parameters](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/animator-parameters/) defines the movement, ability, and per-slot item values that Animator Monitor updates.
- [Default Animator Values](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/default-animator-values/) lists the supplied Ability Index, Item State Index, Animator Item ID, and Movement Set ID mappings.
- [First Person Arms](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/first-person-arms/) explains the generic first-person rig and its animation options.
- [Replacing Animations](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/replacing-animations/) covers replacing clips without losing layer coverage or animation-event timing.
## Verify in Play Mode
1. Select the active character model and open **Window > Animation > Animator**.
2. Enter Play Mode and move the character. **HorizontalMovement**, **ForwardMovement**, **Speed**, **Moving**, and **Yaw** should respond, and the active state should move between idle and locomotion as expected.
3. Start an ability such as Jump. **AbilityIndex** and **AbilityChange** should drive the intended ability state and return to the normal locomotion flow when the ability ends.
4. Equip and use an item. The relevant `SlotItemID`, `SlotItemStateIndex`, and `SlotItemSubstateIndex` values should match the equipped item and action.
5. Repeat the changed action while stationary and moving so every intended masked layer is exercised.
6. If the character supports both perspectives, switch perspectives and confirm that the body, first-person arms, and visible item all select the intended animation.
For focused diagnostics, expand **Editor** on Animator Monitor. **Log Ability Parameter Changes**, **Log Item Parameter Changes**, and **Log Events** write their corresponding updates to the Console in the Unity Editor. Disable them after testing to avoid unnecessary output.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| The Console says the Animator is not designed for Ultimate Character Controller. | The controller is missing required parameters; Version 3 specifically validates `HorizontalMovement`, `ForwardMovement`, and `AbilityChange` during initialization. | Run **Update Character** with the intended Animator Controller or add the complete parameter set documented on [Animator Parameters](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/animator-parameters/). |
| Parameters change but the model stays in the wrong state. | The transition conditions, parameter types, or expected Ability/Item IDs may not match the controller configuration. | Compare the live Animator values with [Default Animator Values](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/default-animator-values/), then correct the affected transition. |
| A replacement clip affects only part of the body. | Another masked layer may still use the old clip or an incompatible motion. | Review every layer that can override that body region and follow [Replacing Animations](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/replacing-animations/). |
| A custom generic model does not animate correctly. | It may be using the supplied humanoid controller or clips authored for a different hierarchy. | Assign a controller and clips authored for the generic rig. |
| First-person arms do not animate or retarget as expected. | The arms may use a generic rig or their own Animator Controller. | Follow [First Person Arms](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/first-person-arms/) and assign clips made for that rig. |
| An ability or item waits indefinitely at an animation point. | The active clip may be missing the event expected by its Animation Event Trigger. | Add the correct `ExecuteEvent` marker or configure a deliberate Duration on [Animation Event Trigger](https://opsive.com/support/documentation/ultimate-character-controller/animation/animation-event-trigger/). |
## Related pages
- [Animation](https://opsive.com/support/documentation/ultimate-character-controller/animation/) explains how Animator content, events, item animation selection, and procedural motion fit together.
- [Character Creation](https://opsive.com/support/documentation/ultimate-character-controller/character/character-creation/) covers building or updating the character through Character Manager.
- [Animation Event Trigger](https://opsive.com/support/documentation/ultimate-character-controller/animation/animation-event-trigger/) coordinates gameplay timing with clip events or a duration.
- [Item Slots](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-slots/) explains the Slot IDs used by per-item Animator parameters.
## Developer reference
`AnimatorMonitor` is the Version 3 bridge between Ultimate Character Controller and Unity's Animator. It hashes and updates the standard movement, aiming, ability, and item-slot parameters, applies the configured damping values, and raises the change triggers used by Animator transitions. The Character Manager calls the Animator parameter builder for the assigned controller during character creation or update.
When an Animator is present, Animator Monitor applies **Animator Speed** and **Update Mode** directly to it. When a first-person setup has no full-body Animator, the monitor still stores the parameter state so child item animators can receive the updates. `ChildAnimatorMonitor` also filters animation events by the active perspective before forwarding them to the character.
---
# Animator Controller
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/animator-controller/)
Use the supplied Animator Controller as a working reference, or build a project-specific controller that keeps Ultimate Character Controller's parameter, ID, and animation-event contracts.
## Before you edit the controller
- Confirm the character works with the supplied controller in Play Mode.
- Make a project-owned copy of any controller you plan to modify.
- Decide whether the model is **Humanoid** or **Generic**. Generic rigs need a controller and clips authored for their hierarchy.
- Review [Animator Parameters](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/animator-parameters/) and [Default Animator Values](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/default-animator-values/) before changing transition conditions.
The controller does not require the demo's exact state-machine or layer layout. Animator Monitor updates named parameters; your transitions decide how those values select states. Keeping the demo layout is usually the quickest route when the project uses similar locomotion, abilities, and items.
## Assign a controller to the character
1. Open **Tools > Opsive > Ultimate Character Controller > Character Manager**.
2. Select the character and enable **Animator**.
3. For each model, choose **Model Type** and assign the project-owned controller in **Animator Controller**.
4. Select **Build Character** for a new character or **Update Character** for an existing character. The manager adds the standard Ultimate Character Controller parameters when they are missing.
5. Select the configured model and confirm that its **Animator** uses the intended controller and that **Animator Monitor** is present.
6. Open **Window > Animation > Animator** and verify that the Parameters list contains the movement, ability, and item-slot parameters used by the project.
The Version 3 parameter builder adds 22 standard parameters, including two item slots. A project with more item slots can add the corresponding `Slot...` parameters; Animator Monitor updates a slot only when that controller contains its Slot Item ID parameter.
## Add or change a state-machine flow
1. Choose the layer by the body region and blend behavior the animation needs. Use the Base Layer for locomotion or a full-body baseline, a masked override layer for a body region, an additive layer for motion added over the current pose, or the Full Body Layer for an action that must replace the whole pose.
2. Add a state or sub-state machine with a name that identifies the ability, item, or locomotion mode.
3. Assign clips compatible with the model's Avatar or generic hierarchy.
4. Create entry conditions from the relevant values:
- Locomotion commonly uses **HorizontalMovement**, **ForwardMovement**, **Speed**, **Moving**, **Aiming**, and **MovementSetID**.
- Character abilities use **AbilityIndex**, **AbilityChange**, and, when needed, **AbilityIntData** or **AbilityFloatData**.
- Item actions use the matching `SlotItemID`, `SlotItemStateIndex`, `SlotItemStateIndexChange`, and `SlotItemSubstateIndex` values.
5. Add a deliberate return path to the layer's idle or locomotion state. Test both a normal completion and an interrupted action.
6. Preserve every required Animation Event when replacing or moving a clip. The event must exist on every clip that can drive that action, unless its [Animation Event Trigger](https://opsive.com/support/documentation/ultimate-character-controller/animation/animation-event-trigger/) is deliberately configured to use Duration.
7. Test the change before modifying another layer.
## Understand the supplied 13-layer layout
The Version 3 demo controller currently contains these layers, in this order:
| Layer group | Supplied layer names | Purpose |
| --- | --- | --- |
| Baseline | **Base Layer** | Provides idle, movement, aiming movement, crouch, and core ability flows such as Fall, Interact, Jump, Quick Turn, and Ride. Ability transitions are selected with the ability parameters. |
| Hand overrides | **Left Hand Layer**, **Right Hand Layer** | Holds hand and finger poses without replacing the rest of the body. |
| Two-arm overrides | **Arms Layer**, **Upperbody Layer** | Applies two-arm item actions. The Arms mask avoids replacing torso motion, while Upperbody includes the torso when the action needs it. |
| One-side overrides | **Left Arm Layer**, **Right Arm Layer**, **Left Upperbody Layer**, **Right Upperbody Layer** | Allows one arm, or one arm plus its upper-body contribution, to act independently. This supports dual-wield and secondary-item arrangements. |
| Additive overlays | **Additive Layer**, **Additive Left Arm Layer**, **Additive Right Arm Layer** | Adds motion such as recoil or a reaction over the pose selected by lower layers. These three layers use additive blending. |
| Full replacement | **Full Body Layer** | Overrides the complete pose for actions such as death, revive, or a full-body attack. |
Layer order and Avatar Masks matter. A later override layer can replace motion chosen below it, while an additive layer expects a compatible additive clip. Do not copy a state into another layer without also checking its mask, blend mode, transition conditions, and exit path.
## Choose a customization approach
### Keep the supplied structure
Use this approach when the game needs similar locomotion, abilities, item categories, and body-region layering. Add project-specific states under the existing sub-state machines and keep the supplied parameters and layer masks. This minimizes the number of interacting transitions that must be rebuilt.
### Start from a minimal controller
Use a new controller when the game's animation flow is fundamentally different or it does not need the demo's item and body-region layers. Begin with the required parameters and one working locomotion flow, then add one ability or item action at a time. You do not need to recreate all 13 demo layers.
### Replace clips without redesigning transitions
Use [Replacing Animations](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/replacing-animations/) when the state logic is already correct and only the motions need to change. Replace every occurrence across the relevant masked layers and keep **Replace Events** enabled when the new clips should receive the supplied animation events.
## Verify in Play Mode
1. Select the active model and keep the Animator window visible.
2. Move, stop, turn, crouch, and aim. The live parameters should select the intended Base Layer states without rapid unwanted transitions.
3. Start each changed ability. Confirm the expected **AbilityIndex** and any data parameter, watch the intended layer enter its state, and verify that it returns cleanly when the ability ends.
4. Equip and use each changed item while stationary and moving. Confirm that the correct slot parameters select matching states on the hand, arm, and upper-body layers.
5. Trigger an additive reaction and a full-body action. The additive result should retain the underlying pose; the full-body action should replace it.
6. Repeat interrupted actions, perspective changes, and rapid inputs. No layer should remain stuck in an action state, and required events should occur once at the intended frame.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| The Console reports that the Animator is not designed for Ultimate Character Controller. | `HorizontalMovement`, `ForwardMovement`, or `AbilityChange` is missing, and other feature parameters may also be absent. | Run **Update Character** with the intended controller or add the full set from [Animator Parameters](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/animator-parameters/). |
| Parameters change but an ability state never starts. | The transition may use the wrong **AbilityIndex**, parameter type, or trigger condition. | Compare the live values with [Default Animator Values](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/default-animator-values/) and correct the transition. |
| An item action works while stationary but not while moving. | The action may exist on **Upperbody Layer** but not the corresponding **Arms Layer**, or vice versa. | Add the intended state and transition to every masked layer the action needs. |
| A one-handed action moves both arms or the torso. | The state may be on a layer with the wrong Avatar Mask. | Move it to the appropriate left/right arm or upper-body layer, or correct that layer's mask. |
| An additive action distorts the pose. | The layer or clip may not be configured for compatible additive blending. | Verify the layer's blending mode and the clip's additive reference pose. |
| An action starts but never returns. | The exit condition, animation event, or return transition may be missing. | Add a return path and verify the event expected by the trigger, or intentionally use Duration timing. |
| A replacement changes only part of the visible result. | Another layer or perspective may still reference the original clip. | Search the full controller and all first-person or item controllers for the old clip, then follow [Replacing Animations](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/replacing-animations/). |
## Related tasks
- [Animator](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/) provides the recommended route through Animator setup and customization.
- [Animator Parameters](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/animator-parameters/) defines the exact parameter names, types, and meanings.
- [Default Animator Values](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/default-animator-values/) lists the supplied ability and item ID mappings.
- [Replacing Animations](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/replacing-animations/) covers the Animation Replacer workflow and event preservation.
- [First Person Arms](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/first-person-arms/) explains the generic first-person rig and its separate controller needs.
- [Animator Controller overview video](https://www.youtube.com/watch?v=J5KClzxpCzE) provides a visual walkthrough of the supplied structure.
## Developer reference
`AnimatorMonitor` does not search for specific layer or state names. It hashes and writes the standard parameter names, including movement, ability, and item-slot values. `AnimatorBuilder.AddParameters` adds the Version 3 baseline of 22 parameters: 13 shared character parameters, four parameters each for slots `0` and `1`, and `LegIndex`.
The shipped `Demo.controller` currently defines 13 layers. Its Base, hand, arm, upper-body, and full-body layers use override blending; the three Additive layers use additive blending. The masked layers use separate Avatar Mask assets, and the Base, Upperbody, and Full Body layers enable IK Pass. These are implementation choices in the supplied demo controller, not mandatory layer names for a custom controller.
---
# Animator Parameters
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/animator-parameters/)
Animator parameters connect Ultimate Character Controller's movement, abilities, and equipped items to transitions and blend trees in a Unity Animator Controller.
## Add the Version 3 parameters
1. Open **Tools > Opsive > Ultimate Character Controller > Character Manager**.
2. Select the character, enable **Animator**, and assign the intended **Animator Controller**.
3. Select **Build Character** for a new character or **Update Character** for an existing one. Character Manager adds each missing standard parameter to the assigned controller.
4. Open the controller in **Window > Animation > Animator** and select the **Parameters** tab.
5. Compare every name and type with the tables below. Names are case-sensitive.
6. Build transition conditions around the values the character actually uses, then verify them in Play Mode before editing another flow.
The Version 3 parameter builder adds 22 parameters: 13 shared character parameters, four parameters for each of slots `0` and `1`, plus `LegIndex`. If a parameter already exists with the correct name but the wrong type, the builder does not replace it; correct that parameter manually.
## Movement and look parameters
| Name | Type | Version 3 behavior and common use |
| --- | --- | --- |
| `HorizontalMovement` | Float | Receives the horizontal component of the locomotion input vector. Use it as the horizontal axis of a locomotion blend tree. Animator Monitor applies **Horizontal Movement Damping Time**. |
| `ForwardMovement` | Float | Receives the forward component of the locomotion input vector. Use it as the forward axis of a locomotion blend tree. Animator Monitor applies **Forward Movement Damping Time**. |
| `Pitch` | Float | Receives the active look source's pitch when a look source is present. Use it for vertical aim or look poses. Animator Monitor applies **Pitch Damping Time**. |
| `Yaw` | Float | Receives the character's rotational change multiplied by Animator Monitor's **Yaw Multiplier**. Use it for turn-in-place or turning blends rather than as an absolute world rotation. Animator Monitor applies **Yaw Damping Time**. |
| `Speed` | Float | Normally becomes **Moving Speed Parameter Value** while the character is moving and `0` while stopped. An ability can temporarily override it, such as Speed Change. It is not a direct world-speed measurement. |
| `Height` | Float | Receives a height value set by an ability. Height Change can set its configured height when active and restore `0` when it stops. |
| `Moving` | Bool | Becomes true or false when the character starts or stops moving. Use it for clear idle-versus-movement decisions. |
| `Aiming` | Bool | Follows the character's aiming event and is forwarded to equipped item animators. Do not assume it is always true in first person; verify the live value for the project's Aim setup. |
| `MovementSetID` | Int | Receives **Animator Movement Set ID** from the dominant equipped Character Item. Use it to select stance families such as default, melee, or bow movement. |
| `LegIndex` | Float | Used by the supplied controller's transition conditions to choose a leg-compatible entry back into movement. Keep it when retaining those transitions; a custom controller that does not use leg-aware entry conditions does not have to reference it. |
`HorizontalMovement` and `ForwardMovement` describe controller input, not the character's measured velocity. Use `Speed`, `Moving`, or a project-specific parameter when a transition needs a different meaning.
## Ability parameters
| Name | Type | Version 3 behavior and common use |
| --- | --- | --- |
| `AbilityIndex` | Int | Receives the **Ability Index Parameter** from the highest-priority active ability that supplies one. `0` represents no selected ability in the standard flow. Use it to select an ability state or sub-state machine. |
| `AbilityChange` | Trigger | Is set when `AbilityIndex` changes. Use it with the index condition so the Animator can enter or re-enter the correct ability flow when the selection changes. |
| `AbilityIntData` | Int | Carries ability-specific integer detail in addition to `AbilityIndex`. For example, Interact exposes **Ability Int Data Value** so different interaction animations can share one ability index. |
| `AbilityFloatData` | Float | Carries ability-specific continuous or variant data. Current abilities use it for values such as fall velocity, steering input, or idle variation. An ability can request damping when updating it. |
The first active ability by priority that supplies each value wins. Do not use `AbilityIntData` or `AbilityFloatData` without defining what that value means for the selected `AbilityIndex`.
## Item-slot parameters
Version 3 adds this group for slot `0` and slot `1`. Replace `` with the numeric Slot ID:
| Name pattern | Type | Version 3 behavior and common use |
| --- | --- | --- |
| `SlotItemID` | Int | Receives **Animator Item ID** from the Character Item equipped in that slot. `0` represents no equipped item in the standard flow. Use it to select the item family. |
| `SlotItemStateIndex` | Int | Receives the state index from the highest-priority active item ability for that slot. Use it to select actions such as Use, Reload, Equip, or Unequip. |
| `SlotItemStateIndexChange` | Trigger | Is set when the slot's item or item state changes to a nonzero value. Use it with the ID and state-index conditions to enter or re-enter the intended item action. |
| `SlotItemSubstateIndex` | Int | Carries the action's variation within the selected item state, such as an attack sequence or another Animator Audio State Set choice. |
For example, a pistol with Animator Item ID `2` performing the standard Use item ability in slot `0` can expose `Slot0ItemID = 2` and `Slot0ItemStateIndex = 2`; the substate distinguishes the selected use variation.
If the inventory uses slot `2` or above, add all four matching parameters manually. Animator Monitor treats a slot as available in a controller when it finds that slot's `SlotItemID`; keep the full four-parameter group together.
## Choose parameters by use case
- **Directional locomotion:** Drive a two-dimensional blend tree with `HorizontalMovement` and `ForwardMovement`, then use `Moving` for clean entry and exit conditions.
- **Turn-in-place:** Use `Yaw` with suitable positive and negative thresholds. Tune **Yaw Multiplier** and **Yaw Damping Time** on Animator Monitor before changing many transitions.
- **Ability selection:** Pair `AbilityChange` with the intended `AbilityIndex`. Add `AbilityIntData` or `AbilityFloatData` only when one ability needs multiple animation choices.
- **Equipped stance:** Use `MovementSetID` for a broad stance and `SlotItemID` when the animation is specific to an item family.
- **Item action:** Pair `SlotItemStateIndexChange` with the Slot Item ID and Item State Index. Use the substate only for a variation inside that action.
- **Return to movement:** Use the live movement values and, when keeping the supplied leg-aware transitions, `LegIndex` to choose a compatible re-entry pose.
## Verify in Play Mode
1. Select the active character model and open **Window > Animation > Animator**.
2. On **Animator Monitor**, expand **Editor** and enable **Log Ability Parameter Changes** and **Log Item Parameter Changes**.
3. Enter Play Mode and move in every direction. Watch `HorizontalMovement`, `ForwardMovement`, `Moving`, `Speed`, `Pitch`, and `Yaw` respond.
4. Start an ability. Confirm that `AbilityIndex` and `AbilityChange` select the expected state, and inspect any ability data value used by its transitions.
5. Equip and use an item in each supported slot. Confirm its Slot Item ID, Item State Index, change trigger, and substate match the intended item and action.
6. Stop the action, unequip the item, and return to idle. The active indexes should return to their standard neutral values and the Animator should leave the action state.
7. Disable the logging options after testing.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| The Console says the Animator is not designed for Ultimate Character Controller. | Version 3 validates `HorizontalMovement`, `ForwardMovement`, and `AbilityChange` during Animator Monitor initialization. | Add the missing parameters with the exact names and types, then check the complete table rather than stopping at the three validation names. |
| Character Manager ran, but a transition still reports a type mismatch. | A parameter with that name may already have the wrong type. | Delete or rename the incorrect parameter and recreate it with the type in this page; the parameter builder only adds missing names. |
| The character moves but `Speed` remains `1`. | The default **Moving Speed Parameter Value** is `1`; Speed is not measured velocity. | Use the directional parameters for blend magnitude, tune Moving Speed Parameter Value, or provide a deliberate ability override. |
| An ability index changes but its state does not restart. | The transition may test only `AbilityIndex` and ignore `AbilityChange`. | Add the change trigger to the intended entry transition. |
| An item equips but the item state never changes. | The controller may lack the complete slot group, or its transition may omit `SlotItemStateIndexChange`. | Add all four parameters for that slot and use the change trigger with the ID and state index. |
| A slot above `1` never updates. | The standard builder creates only slot `0` and slot `1`. | Add the four correctly named parameters for the additional Slot ID. |
| Aiming transitions are wrong in first person. | The controller may assume `Aiming` is permanently true. | Watch the live value and build transitions around the Aim ability behavior used by the project. |
| The parameters are correct but the wrong state plays. | The configured ability, item, or movement-set ID may not match the transition threshold. | Compare the Inspector values with [Default Animator Values](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/default-animator-values/) and correct the ID or transition. |
## Related tasks
- [Animator Controller](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/animator-controller/) explains how to organize layers, states, and transitions around these parameters.
- [Default Animator Values](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/default-animator-values/) lists the supplied Ability Index, Item State Index, Animator Item ID, and Movement Set ID mappings.
- [Animator](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/) provides the full setup and customization route.
- [Abilities](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/) explains ability priority and **Ability Index Parameter**.
- [Item Slots](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-slots/) explains the Slot IDs used in item parameter names.
## Developer reference
`AnimatorBuilder.AddParameters` checks each standard name and adds it only when no parameter with that name exists. It creates the 22-parameter Version 3 baseline but does not verify or replace the type of an existing parameter. `AnimatorMonitor` hashes these exact names and writes values through Unity's Animator API.
Movement and look values update during the character's animation update. Ability and item-ability selections are marked dirty and resolved by active-ability priority at the synchronized update point. `AbilityChange` and each `SlotItemStateIndexChange` are Unity Trigger parameters rather than persistent booleans.
For item slots, Animator Monitor first checks for `SlotItemID`. If that parameter is absent, the controller does not receive the state-index, change-trigger, or substate writes for that slot. The same values are also forwarded to active supported child and item animators.
---
# Default Animator Values
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/default-animator-values/)
Use these Version 3 values when an ability or Character Item should play states from the supplied Animator Controller; use different values only when the matching Animator transitions are changed at the same time.
## Match a value to the Animator
1. Select the character and find its **Ultimate Character Locomotion** component.
2. Under **Abilities**, select an ability and check **Ability Index Parameter**. Under **Item Abilities**, check **Item State Index** or the ability's phase-specific fields, such as **Equip Item State Index** and **Unequip Item State Index**.
3. Select each equipped item prefab and find its **Character Item** component. Check **Animator Item ID**, **Animator Movement Set ID**, and **Dominant Item**.
4. Open **Window > Animation > Animator**, select the relevant transition, and match its `AbilityIndex`, `SlotItemID`, `SlotItemStateIndex`, or `MovementSetID` condition to the Inspector value.
5. Change both the Inspector value and every affected transition when using a project-specific number. Changing only one side selects the wrong state or no state.
The ability and item-ability values below are assigned when those built-in entries are added. They are editable starting values, not reserved constants. The item and movement-set tables describe the shipped Version 3 Demo content.
## Ability Index defaults
| Ability | Ability Index Parameter |
| --- | ---: |
| Jump | 1 |
| Fall | 2 |
| Height Change | 3 |
| Die | 4 |
| Revive | 5 |
| Quick Start | 6 |
| Quick Stop | 7 |
| Quick Turn | 8 |
| Interact | 9 |
| Damage Visualization | 10 |
| Pickup | 11 |
| Ride and Rideable | 12 |
| Impact Knock Back | 13 |
| Drive | 14 |
| Generic | 10000 |
Ride and Rideable deliberately share `12` so the rider and mount can synchronize through the same Animator flow. A custom ability without a supplied default starts with `-1`, which means it does not select an `AbilityIndex` value until you assign one.
## Item State Index defaults
| Item ability or phase | Item State Index |
| --- | ---: |
| Aim | 1 |
| Use, In Air Melee Use, and Melee Counter Attack | 2 |
| Reload | 3 |
| Equip phase of Equip Unequip | 4 |
| Unequip phase of Equip Unequip | 5 |
| Drop | 6 |
| Block | 8 |
| Parry | 9 |
Sharing `2` is intentional: the Animator Item ID and Item Substate Index provide the additional context needed to choose the correct use animation. An item ability that returns `-1` for a slot does not supply that slot's Item State Index.
## Demo Animator Item IDs
These IDs are configured on the shipped Demo Character Item prefabs. Reuse them when retaining the supplied Demo Animator states, or choose a project-specific mapping and update the transitions that read `SlotItemID`.
| Demo item | Animator Item ID |
| --- | ---: |
| Assault Rifle | 1 |
| Pistol | 2 |
| Shotgun | 3 |
| Bow | 4 |
| Sniper Rifle | 5 |
| Rocket Launcher | 6 |
| Body | 21 |
| Sword | 22 |
| Knife | 23 |
| Katana | 24 |
| Shield | 25 |
| Frag Grenade | 41 |
| Flashlight | 42 |
| Fireball | 61 |
| Particle Stream | 62 |
| Ricochet | 63 |
| Heal | 64 |
| Shield Bubble | 65 |
| Teleport | 66 |
Items that use the same animation family may share an Animator Item ID. Items that need different states within the same slot should use different IDs and matching Animator transitions.
## Demo movement-set IDs
The dominant equipped Character Item supplies `MovementSetID`. The Demo uses these broad stance families:
| Demo stance | Animator Movement Set ID |
| --- | ---: |
| Default, ranged, magic, and throwable | 0 |
| Melee | 1 |
| Bow | 2 |
`0` is both the Demo's default stance and the runtime fallback when no dominant equipped item supplies another movement set. Multiple items can share a movement-set value when they use the same locomotion stance.
## Choose values for a custom controller
- Give abilities different nonzero Ability Index values when they need different top-level Animator states. Deliberately synchronized abilities, such as Ride and Rideable, can share a value.
- Use Animator Item ID to identify an item animation family within each slot. The same item family can use the same ID in more than one slot.
- Reuse an Item State Index for the same kind of action, then use Item Substate Index for animation variations inside that action.
- Reuse a Movement Set ID across items that share locomotion. Set **Dominant Item** on the item that should choose the equipped stance.
- Keep `0` for neutral Ability Index, Item ID, and Item State Index behavior. Movement Set ID `0` remains a valid default stance.
## Verify in Play Mode
1. Select the active character and open **Window > Animation > Animator**.
2. On **Animator Monitor**, expand **Editor** and enable **Log Ability Parameter Changes** and **Log Item Parameter Changes** when a written trace is useful.
3. Start each changed ability. Confirm `AbilityIndex` shows its configured value, the expected state becomes active, and the value returns to `0` when no active ability supplies an index.
4. Equip and use each changed item. Confirm the slot's Item ID and Item State Index match the tables or your custom mapping, and that `MovementSetID` matches the dominant item.
5. Stop the item ability and unequip the item. The Item State Index and empty slot Item ID should return to `0`; the movement set should return to `0` when no dominant item supplies another value.
6. Disable parameter logging after testing.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| An ability runs but its animation does not start. | Compare **Ability Index Parameter** with the `AbilityIndex` transition condition. | Give both sides the same nonzero value, or intentionally use `-1` when the ability should not select an Animator state. |
| The wrong item animation plays. | Watch the slot's Item ID, Item State Index, and Item Substate Index together. | Correct the Character Item ID or the item ability's state value, then update the matching Animator conditions. |
| Equipping an item changes the action animation but not the locomotion stance. | Check **Animator Movement Set ID** and which equipped item has **Dominant Item** enabled. | Assign the intended movement set to the dominant item and add a matching `MovementSetID` transition. |
| A value remains active after the action ends. | Check whether another higher-priority ability or item ability is still active. | Stop or reprioritize the remaining ability; the monitor resets the parameter only when no active entry supplies it. |
| A custom number works on one character but not another. | The characters may use different Animator Controllers or item prefabs. | Apply the mapping to each relevant Inspector and controller rather than treating the Demo IDs as global constants. |
## Related tasks
- [Animator Parameters](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/animator-parameters/) explains what each parameter carries and how to inspect it in Play Mode.
- [Animator Controller](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/animator-controller/) explains how to match these values to states and transitions.
- [Abilities](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/) explains ability order and animation-related settings.
- [Character Item](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/) explains the item component that supplies Animator Item ID and Movement Set ID.
- [Item Slots](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-slots/) explains how slot numbers map to the item Animator parameters.
## Developer reference
`AbilityBuilder` reads the `DefaultAbilityIndex` and `DefaultItemStateIndex` attributes when it creates an ability or item ability. Equip Unequip and Block use their own phase-specific serialized values. Editing an existing entry does not rewrite the Animator Controller.
At runtime, `AnimationMonitorBase` takes the first value supplied by the active abilities in priority order. When no active ability supplies an Ability Index, it writes `0`; when no active item ability supplies a slot's Item State Index or Item Substate Index, it writes `0`. An empty slot receives Item ID `0`. Movement Set ID begins at `0` and is replaced by the configured value from the dominant equipped item.
---
# First Person Arms
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/first-person-arms/)
First-person arms give the close camera a dedicated visible rig and Animator Controller; use them when the full character body is hidden in first person or when weapon handling needs camera-specific animation.
## Before you begin
- Use a character whose **Perspective** is **First** or **Both**.
- Import the arm model and its clips with a compatible Unity rig. The supplied Demo arms use a **Generic** rig, so their clips must be authored for that skeleton and cannot be humanoid-retargeted.
- Prepare an Animator Controller for the arms when they should animate. It must contain every Ultimate Character Controller parameter that its transitions read.
- When the character carries items, decide which arm hand transforms should be the first-person **Item Slots**.
Unity's [generic animation import guide](https://docs.unity3d.com/Manual/GenericAnimations.html) explains the model import settings for a non-humanoid rig.
## Add the arms with Character Manager
1. Place the character and arm model in the scene. The character must be a scene object; the **First Person Arms** field can also accept an arm prefab that Character Manager instantiates.
2. Open **Tools > Opsive > Ultimate Character Controller > Character Manager** and assign the character in **Character**.
3. Set **Perspective** to **First** or **Both** and select the intended **First Person Movement**.
4. Assign the arm root in **First Person Arms**. In the controller field on the same row, assign the Animator Controller made for that arm rig. Adding another arm root creates another row and another controller choice.
5. If **Items** is enabled, select **Adjust Slots** beside **Item Slots**. In the **Character Item Slots** window, find the **First Person Arms** section and assign the appropriate hand transforms. Use **Right** for Slot ID `0`, **Left** for Slot ID `1`, or **Other** for a project-specific ID; each parent and ID in that arm model must be unique.
6. Select **Build Character** for a new character or **Update Character** for an existing one.
7. Inspect the result. Character Manager places the arm root below **FirstPersonObjects** and adds **First Person Base Object**. When a controller was assigned, the root also has **Animator** and **Child Animator Monitor**.
8. For every Character Item that should use these arms, configure its [First Person Perspective Item](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/first-person-perspective/) to reference the correct arm object or **First Person Base Object ID**.
Do not add a second **Animator Monitor** to the arms. The character model keeps **Animator Monitor**; the arms use **Child Animator Monitor** to receive the same movement, ability, and item parameters.
## Choose an arm and controller setup
| Setup | Use it when | Important tradeoff |
| --- | --- | --- |
| Generic arm rig | Final first-person animation needs close-up posing tailored to one skeleton. This is the approach used by the supplied Demo arms. | Clips cannot be humanoid-retargeted, and the humanoid-only Character IK workflow does not drive the generic arms. |
| Humanoid arm rig | A prototype should reuse a humanoid animation library or the full character rig. | Retargeting is convenient, but third-person clips commonly need camera-specific cleanup for hands, weapon framing, and off-screen bones. |
| Multiple arm roots | Different item families or character models need different skeletons or controllers. | Each item must select the correct First Person Base Object, and each arm set needs matching Item Slots and controller parameters. |
| No arm controller | The arm object is intentionally static, absent, or all visible motion is handled elsewhere. | Character Manager does not add Animator or Child Animator Monitor, so ability and item parameters cannot animate that arm root. |
For a quick humanoid prototype, a mesh-isolation tool such as [FPS Mesh Tool](https://assetstore.unity.com/packages/tools/modeling/fps-mesh-tool-28006) can create an arms-only mesh while retaining the humanoid rig. The existing [FPS Mesh Tool integration video](https://www.youtube.com/watch?v=6Ro6mszmeHw) demonstrates that optional third-party workflow. Treat the result as a starting point and review every pose from the gameplay camera.
## How the arms run
**FirstPersonObjects** keeps the first-person hierarchy aligned with the camera and manages which arm base objects are active. By default, a base object is activated when an equipped dominant item references it and is deactivated when no equipped item needs it. Enable **Always Active** on **First Person Base Object** only when that arm set should remain visible without an item.
**Child Animator Monitor** copies the live values from the active character model's **Animator Monitor**, including movement, aiming, ability, Movement Set, and supported item-slot parameters. The arm controller can therefore use the same parameter names and values while playing different first-person clips.
The arm Animator does not apply root motion. Locomotion remains controlled by the character, while the arm clips provide visible first-person motion. Animation events raised by a child Animator Monitor are accepted only when its perspective matches the active perspective.
## Verify in Play Mode
1. Start in first person and equip an item mapped to the arm set. Confirm that the intended arms and visible item appear, with no duplicate third-person arms in front of the camera.
2. Move, look, aim, use, reload, equip, and unequip. Watch the arm Animator and confirm its parameters follow the character and each action enters the expected state.
3. On the character's **Animator Monitor**, expand **Editor** and enable **Log Ability Parameter Changes**, **Log Item Parameter Changes**, or **Log Events** only while diagnosing a mismatch.
4. Unequip the item. Confirm the arm base object hides unless **Always Active** is enabled or another equipped item still references it.
5. For a **Both** character, switch to third person and back. First-person arms should be hidden in third person, return in first person, and resume the correct current Animator state.
6. If multiple character models or arm roots are configured, repeat the equip and perspective checks for every supported combination.
7. Disable the Animator Monitor logging options after testing.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| The arms never appear. | Check **Perspective**, the **FirstPersonObjects** hierarchy, the item's arm reference or **First Person Base Object ID**, and whether the item is equipped. | Select **First** or **Both**, run **Update Character**, then map the First Person Perspective Item to the intended base object. Use **Always Active** only for arms that should not depend on an item. |
| The arms are visible for the wrong item or remain visible after unequipping. | Inspect the item's **Object**, **First Person Base Object ID**, additional control objects, and the arm's **Always Active** value. | Point each item at the correct base object and remove unintended additional control objects; disable **Always Active** for item-specific arms. |
| The arm mesh appears but does not animate. | Check the controller field beside **First Person Arms**, then inspect the root for **Animator** and **Child Animator Monitor**. | Assign the intended controller and select **Update Character**. Character Manager adds or removes both components to match that controller field. |
| The arm Animator logs missing parameters or enters the wrong state. | Compare its parameter names, types, Ability Indexes, Item IDs, and Item State Indexes with the character controller. | Add the required parameters and matching transition conditions; use [Animator Parameters](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/animator-parameters/) and [Default Animator Values](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/default-animator-values/) as the baseline. |
| Generic arm clips deform or do not retarget. | Check the model and clip **Rig** import settings and confirm they use the same generic skeleton. | Use clips authored for that rig, or deliberately switch both model and clips to a valid humanoid workflow instead of mixing rig types. |
| An item appears in the wrong hand. | In **Character Item Slots**, compare the arm hand transform and Slot ID with the Character Item's **Slot ID**. | Assign the correct hand parent and keep the same Slot ID throughout the first- and third-person item setup. |
| An animation event works in one perspective but not the other. | Confirm the active perspective's clip contains the event or uses the intended duration fallback. | Add the event to the first-person clip or configure the matching [Animation Event Trigger](https://opsive.com/support/documentation/ultimate-character-controller/animation/animation-event-trigger/). |
## Related tasks
- [Character Creation](https://opsive.com/support/documentation/ultimate-character-controller/character/character-creation/) explains the complete Character Manager setup.
- [First Person Perspective Item](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/first-person-perspective/) controls which arm base object and visible item an equipped item uses.
- [Animator Parameters](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/animator-parameters/) lists the parameters copied to an animated arm root.
- [Replacing Animations](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/replacing-animations/) covers clips, layers, and required animation events.
- [First Person View Types](https://opsive.com/support/documentation/ultimate-character-controller/camera/view-types/included-view-types/first-person/) explains the camera-side first-person setup.
- [Inverse Kinematics](https://opsive.com/support/documentation/ultimate-character-controller/inverse-kinematics/) explains the humanoid-only Character IK workflow and why it does not drive the supplied generic arms.
## Developer reference
`CharacterManager` calls `ItemBuilder.AddFirstPersonArms` when building or adding an arm root. The builder assigns a unique `FirstPersonBaseObject` ID and moves that hierarchy to the Overlay layer. When the row has a controller, it adds or reuses an `Animator`, disables root motion, sets culling to **Always Animate**, assigns the controller, and adds `ChildAnimatorMonitor`. Updating the row with no controller removes the arm Animator and Child Animator Monitor.
`ChildAnimatorMonitor` reads from the active character model's `AnimatorMonitor`, mirrors the standard character and supported slot parameters, follows the character time scale, and snaps to the current state when enabled or after an immediate transform change. It treats a slot as supported when the arm controller contains that slot's `SlotItemID` parameter, so keep the full slot parameter group consistent with the controller's transitions.
---
# Replacing Animations
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/replacing-animations/)
Replace clips when the supplied state logic is correct but the character, first-person arms, or visible item needs project-specific motion. The Version 3 Animation Replacer can update every matching clip reference in one Animator Controller while preserving the controller's states, transitions, blend trees, and layers.
## Before you replace clips
- Duplicate the supplied Animator Controller into a project-owned folder under `Assets`. **Replace** edits the selected controller asset directly and does not provide its own rollback workflow.
- Commit or back up both the controller and replacement animation assets. Copying events can modify the replacement model's import settings, which also affects other controllers that use that clip.
- Test the unchanged controller in Play Mode and record the expected idle, locomotion, ability, equip, use, reload, and unequip behavior.
- Confirm that every replacement clip is compatible with the model's rig and Avatar. The Animation Replacer changes clip references; it does not retarget an incompatible rig.
- Identify every controller that needs the motion. Character bodies, first-person arms, and animated visible items can use separate controllers and must be processed separately.
If Unity's Animator workflow is unfamiliar, review the [Unity Animator Controller guide](https://docs.unity3d.com/Manual/class-AnimatorController.html) before changing the supplied controller.
## Replace clips with Animation Replacer
1. Open **Tools > Opsive > Ultimate Character Controller > Animation Replacer**.
2. Assign the project-owned controller to **Animator Controller**. The list shows each original clip found in that controller's layers, nested state machines, and blend trees.
3. For a one-time change, assign a replacement beside each original clip name. Leave entries empty when they should remain unchanged.
4. For a reusable mapping, assign a **Replacement Template**. Create one with **Assets > Create > Opsive > Ultimate Character Controller > Utility > Animation Replacements**, then keep its **Originals** and **Replacements** arrays paired and the same length.
5. Choose **Replace Events** deliberately. Leave it enabled only when the replacement imported clips should receive the original clips' event lists. Disable it when the replacements already contain approved events or the related gameplay triggers use durations.
6. Review every populated mapping. One listed source clip can be referenced by several states or blend trees; selecting **Replace** changes every occurrence of that exact clip in the selected controller.
7. Select **Replace**. Confirm the Console reports the number of clip references replaced, then inspect the controller diff before continuing.
8. Repeat the process for each separate body, arm, or visible-item controller that should use the new motions.
For a state-specific exception, replace that state's **Motion** manually in the Animator window instead. Animation Replacer is intended for replacing every occurrence of a source clip within the selected controller.
## Decide how to handle animation events
Animation events coordinate visible frames with gameplay actions such as applying jump force, firing, reloading, equipping, or completing an interaction.
Use **Replace Events** when the new clip should inherit the original event names and parameters. Version 3 copies each event to the same relative point in the replacement clip. For example, an event halfway through the original clip is placed halfway through the replacement, even when the two clips have different lengths.
Review the result before Play Mode:
- When the original contains events, copying replaces the imported replacement clip's current event list. Disable **Replace Events** when the replacement already has deliberate events that must be retained.
- Automatic event copying works for clips stored in an imported model whose event list can be changed through its Model Importer. Add events manually to standalone `.anim` clips or any replacement that did not receive them.
- Relative timing does not guarantee correct action timing. Move the copied event to the actual contact, release, or completion frame when the new performance is paced differently.
- Do not map original clips with different event requirements to one shared replacement while copying events. A clip asset has one event list wherever it is used.
- For an event-driven [Animation Event Trigger](https://opsive.com/support/documentation/ultimate-character-controller/animation/animation-event-trigger/), keep **Wait For Animation Event** enabled and verify the replacement sends `ExecuteEvent` with the expected String value.
- For duration timing, disable **Wait For Animation Event** and retune **Duration** for the new clip. Duration mode does not use copied animation events.
- First-person and third-person states may use different clips. Each active perspective needs the event or duration configuration that drives its action.
Unity's [animation events on imported clips guide](https://docs.unity3d.com/Manual/AnimationEventsOnImportedClips.html) shows where imported clip events are edited.
## Check the surrounding Animator setup
The tool replaces motions but does not redesign the states around them. Review these choices after each group:
- **Layers and masks:** confirm the replacement exists in every intended full-body, upper-body, arms, and item layer. A different source clip in another controller is not changed automatically.
- **Transitions:** compare exit time, transition duration, interruption settings, and conditions with the new clip's anticipation and recovery.
- **State settings:** review Speed, Cycle Offset, Mirror, Foot IK, and Write Defaults where they affect the new performance.
- **Blend trees:** preview every direction and speed. Clips with different stride lengths or poses can require new thresholds or motion-speed adjustments.
- **Looping and root motion:** set the replacement clip's import options for the intended loop and root-transform behavior. Animation Replacer does not copy these settings from the original.
- **Rig-specific controllers:** generic first-person arms require clips authored for their exact rig; a humanoid body controller can use compatible retargeted clips.
## Verify in Play Mode
1. Open **Window > Animation > Animator**, select the active character model, and watch the changed state while performing its action.
2. Test idle, start, stop, turns, every locomotion direction, jump, fall, and landing when any locomotion clip changed. The character should enter and leave each state cleanly without a bind pose, foot slide, or layer mismatch.
3. Run each changed ability and item action. Confirm the correct body, arm, and visible-item clips play in every relevant layer.
4. On **Animator Monitor**, expand **Editor** and enable **Log Events**. Confirm each expected event occurs once at the intended visible frame and the action does not remain waiting.
5. Test rapid input, interrupted actions, altered playback speed, and any supported character time scale. Events and transitions should remain synchronized.
6. For a **Both** character, repeat the actions in first person and third person. Verify both controller sets and their events.
7. Unequip items and return to idle. No layer should remain in the replacement action state.
8. Disable **Log Events** after verification.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| **Replacement Template** leaves expected fields empty. | Compare each **Originals** reference with the exact clips used by the selected controller, and confirm both arrays have the same length. | Correct the source references and pair every valid original with one replacement; null entries are skipped. |
| **Replace** reports `0` or the controller appears unchanged. | Check **Animator Controller** and confirm at least one displayed source clip has a replacement assigned. | Select the project-owned controller actually used by the runtime Animator, populate the intended mappings, and run **Replace** again. |
| A different source clip with the same name is missing from the list. | Animation Replacer sorts and identifies its displayed entries by clip name, so same-named source assets share one mapping. | Do not select **Replace** until the source clips have distinct names, or replace those states manually. |
| Only part of the body changed. | The other layer, perspective, arm, or item controller may use another clip asset. | Inspect every relevant controller and replace its source clip separately. |
| The replacement event never fires. | Check whether the replacement is a standalone `.anim` clip or whether the active trigger is waiting for a named event. | Add the event manually with `ExecuteEvent` and the exact String value, or deliberately switch the trigger to Duration mode. |
| Approved events disappeared from the replacement clip. | **Replace Events** may have overwritten the imported target event list with the source events. | Restore the asset from version control, disable **Replace Events**, and add or retain the approved events manually. |
| The action occurs too early or too late. | A copied event keeps relative clip time, not the new performance's semantic frame. | Move the event to the visible action frame or retune the trigger's **Duration**. |
| Another character changed unexpectedly. | It may share the edited controller or the replacement clip whose imported events changed. | Restore the shared asset, create project-specific controller or clip assets, and repeat the replacement on those copies. |
| The model deforms or enters a bind pose. | Check the replacement clip's rig type and Avatar against the animated model. | Use a compatible clip or correct the import and Avatar setup before editing the controller again. |
## Related tasks
- [Animator Controller](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/animator-controller/) explains the supplied layers, states, transitions, and customization route.
- [Animator Parameters](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/animator-parameters/) lists the values that select the changed states at runtime.
- [Default Animator Values](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/default-animator-values/) lists the supplied ability and item mappings used by transition conditions.
- [Animation Event Trigger](https://opsive.com/support/documentation/ultimate-character-controller/animation/animation-event-trigger/) explains event-driven and duration-driven gameplay timing.
- [Animation Slot Event Trigger](https://opsive.com/support/documentation/ultimate-character-controller/animation/animation-event-trigger/animation-slot-event-trigger/) covers slot-aware item events.
- [First Person Arms](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/first-person-arms/) explains the separate generic arm rig and controller workflow.
## Developer reference
`AnimationReplacer` traverses every layer, nested state machine, state, and nested blend tree in the selected `AnimatorController`. It lists one entry for each source clip name and replaces every traversed reference whose mapping is non-null. Controllers used by first-person arms or visible items are not discovered automatically.
With **Replace Events** enabled, the replacer reads the original clip's events, converts each time to a normalized position based on the original length, and writes that event list through the replacement clip's `ModelImporter`. This path does not update a standalone `.anim` asset. The controller is marked dirty and the Console reports the replacement count, but state settings, transitions, masks, import settings, and gameplay trigger configuration remain unchanged.
---
# Animation Event Trigger
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/animation/animation-event-trigger/)
An Animation Event Trigger lets an ability or item action occur at a specific point in an animation, or after a fixed duration when clip-driven timing is not needed.
## Choose the trigger mode
Animation Event Trigger fields appear throughout Ultimate Character Controller, including **Jump Event**, landing, interaction, pickup, and item-action timing fields. Expand the field and choose one of two modes:
- Enable **Wait For Animation Event** when the gameplay action must match a meaningful frame in a clip, such as applying jump force at takeoff or releasing an item during a throw.
- Disable **Wait For Animation Event** when a consistent timed delay is sufficient. The **Duration** field then appears and sets the delay in seconds. A Duration of `0` triggers the action immediately.
These modes do not act as fallbacks for each other. When **Wait For Animation Event** is enabled, a missing event leaves the trigger waiting rather than using Duration.
## Set up an animation event
The Jump ability provides a clear example:
1. Select the character and expand **Ultimate Character Locomotion > Abilities > Jump > Jump Event**.
2. Leave **Wait For Animation Event** enabled.
3. Hover over **Jump Event** and read its tooltip to find the expected event name. Jump expects `OnAnimatorJump`; other fields name their own event.
4. Open **Window > Animation > Animation**, select the clip used by the active Animator state, and add an Animation Event at the frame where the gameplay action should occur.
5. Set the event **Function** to `ExecuteEvent` and its **String** value to the exact event name from the trigger tooltip. Event names are case-sensitive.
6. Confirm that the Animator Controller actually reaches this clip for the relevant ability or item action.
7. If different first-person and third-person clips can perform the action, add the equivalent event to every clip that can be active in its perspective.
For Jump, `OnAnimatorJump` applies the initial jump force. Other triggers can begin an interaction, release a projectile, complete a reload, or end an ability, depending on the field that owns the trigger.
## Set up duration timing
1. Expand the Animation Event Trigger field on the ability or item action.
2. Disable **Wait For Animation Event**. The **Duration** field becomes visible.
3. Enter the number of seconds to wait from the point when that trigger begins waiting.
4. Test the action after any clip, transition, or playback-speed change and retune Duration if its visible timing has shifted.
Duration timing is useful for an action without a meaningful animation frame, a quick prototype, or a fixed delay that should not depend on a particular clip. Prefer an animation event when different clips or playback speeds still need the action to occur at the correct visual moment.
## Verify in Play Mode
1. On the character's **Animator Monitor** component, expand **Editor** and enable **Log Events**.
2. Enter Play Mode and perform the configured action.
3. In animation-event mode, the Console should log the expected event at the intended frame. For Jump, the message includes `Execute OnAnimatorJump`, and the character should receive its jump force at that moment.
4. Repeat the action several times and from every supported perspective. The result should occur once per action and should not remain waiting.
5. In duration mode, confirm that the result occurs after the configured delay. A duration-triggered callback does not produce an `Execute ...` message from Animator Monitor because it is not sent by the Animator.
Disable **Log Events** after testing when the extra Console output is no longer useful.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| The ability or item action remains waiting. | **Wait For Animation Event** is enabled, but the active clip may not send the expected event. | Add an event with **Function** set to `ExecuteEvent` and the exact **String** value from the trigger tooltip, or deliberately switch the trigger to Duration mode. |
| The event is visible in the clip but nothing happens. | The event name may have different capitalization, the trigger may be in Duration mode, or the Animator Controller may be playing a different clip. | Match the event string exactly, enable **Wait For Animation Event**, and inspect the active Animator state in Play Mode. |
| The action occurs too early or too late. | Determine whether **Log Events** reports an Animator event. | For event mode, move the event marker in the clip. For duration mode, adjust **Duration**. |
| **Duration** is not visible. | **Wait For Animation Event** is still enabled. | Disable **Wait For Animation Event** to expose the Duration field. |
| The timing works in one perspective only. | The first-person and third-person states may use different clips. | Add the same named event at the appropriate frame in every clip that can drive the action. |
| Timing changed after replacing or speeding up a clip. | A fixed duration does not follow the clip's authored action frame. | Retune Duration or use an animation event so the gameplay action remains attached to the intended frame. |
## Related tasks
- [Jump](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/jump/) uses `OnAnimatorJump` to apply its initial force.
- [Animator Controller](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/animator-controller/) explains how ability and item states are organized.
- [Replacing Animations](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/replacing-animations/) covers preserving event timing when clips change.
- [Animation Slot Event Trigger](https://opsive.com/support/documentation/ultimate-character-controller/animation/animation-event-trigger/animation-slot-event-trigger/) adds slot-aware event names for item actions.
## Developer reference
In Ultimate Character Controller Version 3, `AnimationEventTrigger.WaitForEvent` begins one pending wait. With **Wait For Animation Event** enabled, `Animator Monitor.ExecuteEvent` forwards the clip's String value through the Opsive event system and the matching trigger completes. With the option disabled, the Scheduler invokes the trigger after **Duration** instead. `CancelWaitForEvent` ends the pending wait and cancels its scheduled callback.
The trigger owner registers the event name and decides what happens when it completes. For example, Jump registers `OnAnimatorJump` and applies its force in the completion callback. Item actions that must distinguish slots use `AnimationSlotEventTrigger`; see the related page rather than adding a slot number to a standard Animation Event Trigger by assumption.
---
# Animation Slot Event Trigger
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/animation/animation-event-trigger/animation-slot-event-trigger/)
An Animation Slot Event Trigger lets an item action respond to a specific equipment slot, which is useful when two equipped items must reach their use, reload, equip, or unequip timing independently.
## Choose shared or slot-specific timing
Animation Slot Event Trigger extends [Animation Event Trigger](https://opsive.com/support/documentation/ultimate-character-controller/animation/animation-event-trigger/) with **Wait For Slot Event**. Choose the mode based on how the equipped items should behave:
| Scenario | Trigger settings | Example event |
| --- | --- | --- |
| One item acts at a time, or every waiting item should advance together. | Enable **Wait For Animation Event** and leave **Wait For Slot Event** disabled. | `OnAnimatorItemUse` |
| Items in different slots must advance independently. | Enable both **Wait For Animation Event** and **Wait For Slot Event**. Use a slot-qualified event in each relevant clip. | `OnAnimatorItemUseSlot0` or `OnAnimatorItemUseSlot1` |
| The action needs only a fixed delay. | Disable **Wait For Animation Event** and set **Duration**. | No Animator event is required. |
In Version 3, enabling **Wait For Slot Event** permits the slot-qualified event in addition to the shared base event. It does not reject the base event. If separate items must complete independently, do not leave an unsuffixed base event in a clip that can run while both triggers are waiting.
## Configure a slot-specific item event
The **Use Event** on a Usable Action is a common example:
1. Select the item's GameObject and find its **Character Item** component. Note its **Slot ID**; the supplied humanoid setup normally uses slot `0` for the right hand and slot `1` for the left hand.
2. Expand the item action's **Use Event**.
3. Enable **Wait For Animation Event**. The **Wait For Slot Event** option becomes visible; enable it for independent per-slot timing.
4. Read the trigger field's tooltip for its base event name. **Use Event** registers `OnAnimatorItemUse`, while **Use Complete Event** registers `OnAnimatorItemUseComplete`.
5. Append `Slot` and the Character Item's numeric Slot ID without spaces. For a Use Event in slot `0`, the result is `OnAnimatorItemUseSlot0`.
6. Open **Window > Animation > Animation** and select the clip that performs this item's action.
7. Add an Animation Event at the intended action frame. Set **Function** to `ExecuteEvent` and **String** to the exact slot-qualified name.
8. Repeat the setup for each slot that acts independently. For slot `1`, use `OnAnimatorItemUseSlot1` rather than copying the slot `0` string.
9. If first-person and third-person states use different clips, add the corresponding event to every clip that can be active in its perspective.
The event name is registered by the item or item-action code; it is not generated from the visible field label at runtime. The tooltip is the reliable source for the base name.
## Common event names
Ultimate Character Controller commonly follows a base-name-plus-slot convention:
| Trigger | Shared base event | Slot `0` event |
| --- | --- | --- |
| **Use Event** | `OnAnimatorItemUse` | `OnAnimatorItemUseSlot0` |
| **Use Complete Event** | `OnAnimatorItemUseComplete` | `OnAnimatorItemUseCompleteSlot0` |
| **Reload Event** | `OnAnimatorItemReload` | `OnAnimatorItemReloadSlot0` |
| **Reload Complete Event** | `OnAnimatorItemReloadComplete` | `OnAnimatorItemReloadCompleteSlot0` |
| **Equip Event** | `OnAnimatorItemEquip` | `OnAnimatorItemEquipSlot0` |
| **Unequip Event** | `OnAnimatorItemUnequip` | `OnAnimatorItemUnequipSlot0` |
Use the field tooltip rather than assuming that every custom trigger follows this naming convention.
## Verify in Play Mode
1. On the character's **Animator Monitor**, expand **Editor** and enable **Log Events**.
2. Enter Play Mode with items assigned to the slots being tested.
3. Perform the slot `0` action. The Console should show the slot-qualified event, such as `Execute OnAnimatorItemUseSlot0`, and only the intended slot should advance.
4. Perform the equivalent slot `1` action. The Console should show the `Slot1` event and the other item should remain unaffected.
5. Repeat the test in every supported perspective and with both items ready at the same time.
6. If the trigger uses Duration instead, verify the delayed result without expecting an Animator Monitor event log.
Disable **Log Events** after the timing has been confirmed.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| Both equipped items respond to one animation event. | The active clip may still send the shared base event, such as `OnAnimatorItemUse`. | Use slot-qualified events, enable **Wait For Slot Event** on each trigger, and remove the shared event from clips that must act independently. |
| A slot-specific event is logged but the item does not advance. | **Wait For Slot Event** may be disabled, or the suffix may not match the Character Item's **Slot ID**. | Enable the option and make the event end in the exact `Slot` value used by that Character Item. |
| **Wait For Slot Event** is not visible. | **Wait For Animation Event** is disabled. | Enable **Wait For Animation Event**; otherwise the trigger uses Duration and does not listen for slot events. |
| Slot `0` works but slot `1` does not. | The second clip may still contain `Slot0`, or both Character Items may use the same Slot ID. | Correct the event String and confirm each **Character Item > Slot ID**. |
| The action remains waiting in one perspective. | That perspective may use a different animation clip without the slot-qualified event. | Add the correct event to every first-person or third-person clip that can drive the action. |
| A duration-based trigger produces no event log. | Animator Monitor logs Animator events, not Scheduler callbacks. | Verify the visible action after **Duration** instead; no `Execute ...` log is expected. |
## Related tasks
- [Animation Event Trigger](https://opsive.com/support/documentation/ultimate-character-controller/animation/animation-event-trigger/) explains the shared event and Duration modes inherited by this trigger.
- [Item Slots](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-slots/) explains Slot IDs and matching first-person and third-person slot layouts.
- [Usable Item Actions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/) explains the Use and Use Complete stages.
- [Dual Wielding](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-creation/dual-wielding/) covers an item setup where independent slot timing is especially useful.
## Developer reference
`AnimationSlotEventTrigger.RegisterUnregisterEvent` receives the base event name and Slot ID from its owner. Version 3 registers both the base name and a cached slot name formed as `eventName + "Slot" + slotID`. `InvokeSlotEvent` completes the wait only when **Wait For Slot Event** is enabled, while the inherited base-event handler remains available whenever **Wait For Animation Event** is enabled.
The current Usable Action registers its Use Event as follows:
```csharp
m_UseEvent.RegisterUnregisterEvent(
register,
m_Character,
"OnAnimatorItemUse",
m_CharacterItem.SlotID,
HandleItemUseAnimationSlotEvent);
```
Start or reset the pending event-or-duration wait with:
```csharp
m_UseEvent.WaitForEvent(true);
```
The callback overload can also receive the registered Slot ID. After one valid event or scheduled callback completes the wait, later events do not invoke the completion callback again until another wait begins.
---
# Input
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/input/)
Use the input layer to connect a player’s keyboard, mouse, controller, or on-screen controls to one Ultimate Character Controller character. Choose the input implementation before building the character so the Character Manager can create the correct components and references.
## Choose an input route
| Route | Use it when | UCC setup |
| --- | --- | --- |
| **Unity Input System** | A new project needs action assets, control schemes, or device pairing. | Enable **Input System** in the Character Manager. UCC creates an Opsive **Unity Input System** component alongside Unity’s **Player Input** component. |
| **Input Manager** | An existing project already uses Unity’s legacy axis and button mappings, or you want the supplied default mappings for a quick prototype. | Leave **Input System** disabled and add the mappings from **Setup Manager > Project**. UCC creates a **Unity Input** component. |
| **Rewired** | The project already manages actions and player identities with Rewired. | Install the UCC integration, add **Rewired Input**, and assign it through **Player Input Proxy**. |
The rest of UCC reads the common `IPlayerInput` interface, so abilities, camera input, and item input do not need to know which route supplies the values. An AI-controlled character is different: enable **AI Agent** in the Character Manager and do not add a player-input implementation.
## Set up the Unity Input System
1. Install and enable Unity’s Input System package. After Unity recompiles with the Input System active, the **Input System** option becomes available in the Character Manager.
2. Open **Tools > Opsive > Ultimate Character Controller > Setup Manager** and select **Project**.
3. Use **Update Layers** and the appropriate **Render Pipeline** setup. Do not select **Update Buttons** unless the project also needs the legacy Input Manager mappings.
4. Open **Tools > Opsive > Ultimate Character Controller > Character Manager**, select or create the playable character, leave **AI Agent** disabled, and enable **Input System**.
5. Build or update the character.
6. On the character, verify that **Player Input Proxy > Player Input** references the Opsive **Unity Input System** component on the `Input` GameObject.
7. On that input GameObject, verify that Unity’s **Player Input** component has the supplied `CharacterInput` actions and uses the `Gameplay` action map. The Character Manager assigns both when it creates the input object.
If you replace `CharacterInput` with a custom action asset, keep the action names used by the character’s abilities and camera settings. The Opsive component looks up each requested input name in Unity Player Input’s current action map.
## Set up the legacy Input Manager
1. Open **Tools > Opsive > Ultimate Character Controller > Setup Manager** and select **Project**.
2. Select **Update Buttons** under **Input Manager Button Mappings**. In a new project, the combined **Update Buttons and Layers** or **Update Buttons, Layers, and Render Pipeline** action can perform the same input update with the other required project setup.
3. Open **Tools > Opsive > Ultimate Character Controller > Character Manager**, select or create the playable character, leave **AI Agent** disabled, and disable **Input System** if the option is visible.
4. Build or update the character.
5. On the character, verify that **Player Input Proxy > Player Input** references the **Unity Input** component on the `Input` GameObject.
The default mappings include names such as `Horizontal`, `Vertical`, `Mouse X`, `Mouse Y`, and `Jump`. Custom mappings can use different names, but the corresponding ability, camera, and input-component fields must request those same names.
## Connect Rewired
1. Install Rewired and the current UCC Rewired integration.
2. Configure the Rewired Input Manager and the actions used by the character.
3. On the character’s input GameObject, replace the existing Opsive input implementation with **Rewired Input**.
4. On the character, assign **Player Input Proxy > Player Input** to that **Rewired Input** component.
5. Enable **Enable Touch Controls** on Rewired Input only when the project uses Rewired’s touch controls.
6. For local multiplayer, give each character its own Rewired Input component and a different Rewired player assignment.
The integration package supplies the Rewired implementation; the UCC character still consumes it through the same Player Input Proxy. See [Rewired](https://opsive.com/support/documentation/ultimate-character-controller/integrations/rewired/) for the integration-specific setup.
## Add on-screen controls
1. Open **Tools > Opsive > Ultimate Character Controller > Setup Manager** and select **Scene**.
2. Under **Virtual Controls Setup**, choose **Input Type**:
- **InputSystem** adds the on-screen controls for Unity’s Input System.
- **InputManager** adds the legacy Virtual Controls Manager and its controls.
3. Select **Add Virtual Controls**.
4. Assign the intended character where the generated controls do not obtain it from the attached camera.
5. Test the target input mode. The Opsive **Unity Input System > Force Input** choice is **On Screen**; the legacy **Unity Input > Force Input** choice is **Virtual**.
The legacy controls support virtual buttons, joysticks, and touchpads and must remain under their Virtual Controls Manager. See [Virtual Controls](https://opsive.com/support/documentation/ultimate-character-controller/input/virtual-controls/), the direct child of this section, for their names and layout.
## Understand input ownership
Each playable character needs its own **Player Input Proxy** and its own referenced input implementation. A Camera Controller reads the input of its assigned character; adding a second camera does not create a second player or separate devices.
For local multiplayer:
- With Unity’s Input System, give each character a separate Opsive **Unity Input System** component and Unity **Player Input** component. Pair gamepads or control schemes through Unity Player Input. The shipped Opsive component deliberately makes keyboard and mouse available to every enabled player-input instance, so test shared keyboard behavior explicitly.
- With Rewired, give each character a separate Rewired player assignment.
- The legacy Input Manager exposes global axis names, not player identities. Use player-specific mappings and an implementation that distinguishes them, or use the Input System or Rewired when devices must be paired dynamically.
See [Split Screen](https://opsive.com/support/documentation/ultimate-character-controller/camera/split-screen/) for the matching camera, viewport, and HUD setup. For a non-player character, use the [Artificial Intelligence](https://opsive.com/support/documentation/ultimate-character-controller/artificial-intelligence/) workflow instead of assigning local input.
## Key choices
- **Look input names:** **Horizontal Look Input Name** and **Vertical Look Input Name** must match the selected route’s mappings or actions. The supplied names are `Mouse X` and `Mouse Y`.
- **Look Vector Mode:** Use **Smoothed** for UCC’s buffered look smoothing, **Unity Smoothed** for the input implementation’s smoothed values, **Raw** for direct values, or **Manual** when another system assigns the look vector, such as a tracked headset.
- **Look tuning:** Adjust **Look Sensitivity** first. Change **Smooth Look Steps**, **Smooth Look Weight**, **Smooth Exponent**, or **Look Acceleration Threshold** only when **Smoothed** is selected and the default response does not suit the game.
- **Cursor behavior:** **Disable Cursor** locks and hides the cursor while playing. **Enable Cursor With Escape** releases it, and **Prevent Look Vector Changes** prevents the released cursor from rotating the camera.
- **Input-mode override:** Leave **Force Input** at **None** for normal platform detection. Use **On Screen** for the Unity Input System route or **Virtual** for the legacy route when testing touch controls in the Editor.
- **Repeated presses:** **Double Press Tap Timeout** controls the time window used by tap and double-press checks.
- **Death behavior:** **Disable On Death** stops the input implementation when the character dies and enables it again after respawn.
## Verify in Play Mode
1. Enter Play Mode and use the configured `Horizontal` and `Vertical` inputs. The intended character should move, and no other character should respond.
2. Move the mouse or right stick. The assigned camera should look around using the selected smoothing mode and sensitivity.
3. Press `Jump` or another input assigned to an enabled ability. That ability should start once, using the same action or mapping name shown in its Inspector.
4. If cursor release is enabled, press Escape. The cursor should become visible and camera look should stop until the cursor is captured again.
5. If the scene has on-screen controls, interact with each button and axis. The controls should affect the assigned character and should use the same names as the corresponding actions or mappings.
6. In a local multiplayer scene, test one device at a time. Only its assigned character and camera should respond.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| The character does not respond. | **Player Input Proxy > Player Input** may be empty, or it may reference an input component from another character. | Assign the character’s own **Unity Input**, **Unity Input System**, or **Rewired Input** component. |
| Unity Input System actions never fire. | Unity **Player Input > Actions** or its current action map may be missing, or the requested action name may not exist in that map. | Assign the intended action asset, activate `Gameplay` or the custom map, and make its action names match UCC’s input names. |
| Legacy movement works but an ability does not. | The ability’s input name may not match an Input Manager button mapping. | Add or correct the mapping, or change the ability to request the existing name. |
| The camera does not look around. | Check **Horizontal Look Input Name**, **Vertical Look Input Name**, **Look Vector Mode**, and whether the cursor is released. | Match the look names to the route, choose a non-Manual mode unless another system supplies look, and recapture the cursor. |
| Both local characters respond to one device. | The characters may share an input component, Rewired player, Unity device pairing, or global legacy mapping. | Give each character a separate implementation and player/device assignment; do not treat a second camera as input ownership. |
| On-screen controls are hidden or inactive. | **Virtual Controls Setup > Input Type** may not match the character’s input route, or **Force Input** may select the desktop mode while testing in the Editor. | Add the matching controls and temporarily choose **On Screen** or **Virtual** on the input component. |
| Input stays disabled after closing a menu. | The system that sent `OnEnableGameplayInput` with `false` may not have sent the matching `true` event. | Restore gameplay input when the menu closes or the interaction ends. |
## Related pages
- [Quick Setup](https://opsive.com/support/documentation/ultimate-character-controller/getting-started/quick-setup/)
- [Virtual Controls](https://opsive.com/support/documentation/ultimate-character-controller/input/virtual-controls/)
- [Rewired](https://opsive.com/support/documentation/ultimate-character-controller/integrations/rewired/)
- [Split Screen](https://opsive.com/support/documentation/ultimate-character-controller/camera/split-screen/)
- [Artificial Intelligence](https://opsive.com/support/documentation/ultimate-character-controller/artificial-intelligence/)
- [Events](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/)
## Developer reference
### Read input through `IPlayerInput`
`PlayerInputProxy` implements `IPlayerInput`, so gameplay code can read the character-level interface without locating the concrete implementation. The interface supplies `GetButton`, `GetButtonDown`, `GetButtonUp`, `GetAxis`, `GetAxisRaw`, `GetTap`, `GetDoublePress`, `GetLongPress`, and `GetLookVector`.
```csharp
using Opsive.Shared.Input;
using UnityEngine;
public class MyObject : MonoBehaviour
{
[SerializeField] private GameObject m_Character;
private IPlayerInput m_PlayerInput;
private void Awake()
{
m_PlayerInput = m_Character.GetComponent();
}
private void Update()
{
if (m_PlayerInput != null && m_PlayerInput.GetButtonDown("Jump")) {
// Respond to the Jump press.
}
}
}
```
### Enable or disable gameplay input
Send `OnEnableGameplayInput` on the character to disable or enable the input implementation, character locomotion handler, and attached camera input together. This is useful while a full-screen menu or another interaction owns the controls.
```csharp
using Opsive.Shared.Events;
using UnityEngine;
public class GameplayInputToggle : MonoBehaviour
{
[SerializeField] private GameObject m_Character;
public void SetGameplayInput(bool enable)
{
EventHandler.ExecuteEvent(m_Character, "OnEnableGameplayInput", enable);
}
}
```
---
# Virtual Controls
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/input/virtual-controls/)
Use virtual controls to give a mobile player on-screen movement, camera, and action controls without changing the character's abilities. UCC supplies one layout for Unity's Input System and another for the legacy Input Manager.
## Before you begin
- Set up and test the character with its normal input first. See [Input](https://opsive.com/support/documentation/ultimate-character-controller/input/) to choose the Unity Input System or legacy Input Manager route.
- Add the scene managers, camera, and Canvas before arranging a final mobile HUD. [Quick Setup](https://opsive.com/support/documentation/ultimate-character-controller/getting-started/quick-setup/) covers that scene workflow.
- Use the virtual-control type that matches the character's input component. The two supplied layouts are not interchangeable.
## Choose a control type
| Character input | Setup Manager **Input Type** | Generated root component | How controls send input |
| --- | --- | --- | --- |
| Opsive **Unity Input System** | **InputSystem** | **On Screen Controls** | Unity **On-Screen Button** and **On-Screen Stick** components feed the control paths used by the action asset. |
| Legacy **Unity Input** | **InputManager** | **Virtual Controls Manager** | Opsive **Virtual Button**, **Virtual Joystick**, and **Virtual Touchpad** components feed named Input Manager buttons and axes. |
Use the Unity Input System route for a new project that already uses actions and control schemes. Use the legacy route only when the character uses the Input Manager or when an existing project depends on its named mappings.
## Add the supplied controls
1. Open **Tools > Opsive > Ultimate Character Controller > Setup Manager** and select **Scene**.
2. Under **Virtual Controls Setup**, choose **Input Type**:
- **InputSystem** for a character with Opsive **Unity Input System**.
- **InputManager** for a character with legacy **Unity Input**.
3. Select **Add Virtual Controls**. The Setup Manager creates a Canvas if the scene does not already have one, then adds a **VirtualControls** UI root.
4. Select the new root and set **Character** when the controls should always operate one specific character. Leave it empty for a single-player scene where the controls should follow the character attached to the Camera Controller.
5. Select the character's input GameObject and set **Force Input** for the current test:
- On Opsive **Unity Input System**, choose **On Screen**.
- On legacy **Unity Input**, choose **Virtual**.
6. Enter Play Mode and confirm that the root becomes active. Return **Force Input** to **None** before the mobile build if platform detection should decide between desktop and on-screen input.
On supported mobile builds, both input implementations select their on-screen mode automatically unless **Force Input** is set to **Standalone**. Forcing the mode is mainly useful for testing the layout with a mouse in the Editor.
## Configure Unity Input System controls
The supplied InputSystem layout contains movement and camera sticks plus Attack, Next, Reload, Action, and Jump buttons. Its root **On Screen Controls** component owns the character reference; each child uses Unity's standard on-screen component.
1. For a button, set **Control Path** to a control that is bound to the intended action in the active input action map.
2. For a stick, set **Control Path** to the vector control used by the movement or look bindings.
3. Keep **Use Isolated Input Actions** enabled on a stick when control-scheme switching would otherwise cancel its pointer drag.
4. Adjust **Movement Range** to the visible stick radius. Use **Behaviour** to decide whether the origin stays fixed or follows the first touch.
The supplied prefab uses `/leftStick` for movement and `/rightStick` for camera look. Both sticks use **Movement Range** `75`, **Exact Position With Static Origin**, and **Use Isolated Input Actions**. The supplied buttons simulate keyboard controls already represented in `CharacterInput`, including Space for Jump and R for Reload.
Changing a button's label does not change its action. Update **Control Path** and the input action binding together, then verify the result in Play Mode.
## Configure legacy controls
All legacy Virtual Button, Virtual Joystick, and Virtual Touchpad objects must remain below the **Virtual Controls Manager** so they can register their input names with the correct character.
### Movement joystick
The supplied **Virtual Joystick** uses **Horizontal Input Name** `Horizontal`, **Vertical Input Name** `Vertical`, **Radius** `100`, and **Deadzone Radius** `5`. Keep **Joystick** assigned to the movable knob. Increase the deadzone if small unintended motion occurs near the center; increase the radius when the visual control should allow a longer drag.
### Camera touchpad
The supplied **Virtual Touchpad** uses `Mouse X` and `Mouse Y`, so dragging the open look area rotates the camera. **Delta Position Multiplier** controls the drag response. Enable **Require Active Drag** when the value should begin damping as soon as the pointer stops moving, and tune **Active Drag Damping** to control how quickly it falls. Leave **Use Axis Input** disabled for a touch-driven look area.
### Action buttons
Set each **Virtual Button > Button Name** to the exact Input Manager mapping requested by the ability or item action. The supplied layout includes `Fire1`, `Equip Next Item`, `Reload`, `Action`, and `Jump`.
The supplied Virtual Controls Manager leaves **Allow Axis Input** disabled and enables **Allow Button Input**. That keeps physical axes from being mixed into the touch joystick while still allowing a physical button to supplement an unpressed virtual button when the pointer is not over UI. Change those settings only when the game deliberately supports hybrid touch and physical input.
## Design for common mobile scenarios
- **Third-person movement and camera:** Keep the left movement stick, use the touchpad or right stick for look, and place action buttons where they do not cover the look area.
- **Twin-stick controls:** Use a second stick for the look axes. Match its legacy input names or Input System control path to the camera bindings.
- **Large drag-to-look area:** Stretch the touchpad or right-stick hit area behind the action buttons, but keep interactive buttons above it in the Canvas hierarchy so their pointer events are not stolen.
- **Controller plus touch:** Keep the virtual controls active and use the route's physical-input options or bindings. Test simultaneous input because the legacy fallback and Input System control-scheme behavior are different.
- **Multiple local players:** Give each UI root an explicit **Character**. This chooses which UCC input instance is enabled by that root, but it does not by itself pair Unity Input System devices, divide touch regions between players, or configure per-player UI navigation. Complete those responsibilities in the selected input system and follow [Split Screen](https://opsive.com/support/documentation/ultimate-character-controller/camera/split-screen/).
## Verify in Play Mode
1. Force the matching on-screen mode and enter Play Mode. The **VirtualControls** root should become visible only for a character with the matching input implementation.
2. Drag the movement control in all directions. The character should move smoothly, return to idle on release, and remain still inside the intended deadzone.
3. Drag the look control slowly and quickly. The camera should rotate on both axes without continuing after the interaction ends unless that response is intentional.
4. Press each action button once. Only the action whose mapping or binding matches that control should start.
5. Press two controls together, such as movement and Jump. Both should remain responsive under multitouch.
6. Open menus and press near UI boundaries. Gameplay controls should not activate through an interactive menu control.
7. Change or respawn the Camera Controller's character when **Character** is empty. The controls should attach to the new character; an explicitly assigned root should remain with its assigned character.
8. Build to a target device and repeat the test. Confirm safe-area placement, UI scale, orientation changes, and real multitouch instead of relying only on mouse simulation.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| The controls never appear. | **Input Type** may not match the character's input component, or **Force Input** may be **Standalone**. | Add the matching layout and use **On Screen**, **Virtual**, or **None** on a mobile build. |
| The Console reports that the character has no Unity input component. | The root's **Character** may use the other input route or reference the wrong character. | Assign a character with Opsive **Unity Input System** to On Screen Controls, or legacy **Unity Input** to Virtual Controls Manager. |
| A legacy control logs that it cannot find Virtual Controls Manager. | The Virtual Button, Joystick, or Touchpad is outside the manager's hierarchy. | Move the control below the correct Virtual Controls Manager root. |
| A button highlights but no action starts. | Its **Button Name** or **Control Path** may not match a configured mapping or binding. | Match the legacy mapping exactly, or bind the simulated Input System control path to the intended action. |
| The movement stick never returns to zero. | Its knob reference, pointer-up event, or UI raycast may be blocked. | Confirm **Joystick** is assigned, the control has a raycast target, and no full-screen UI element intercepts pointer release. |
| Camera look is too slow, too fast, or drifts. | Check the touchpad **Delta Position Multiplier**, **Require Active Drag**, and the character input's look sensitivity. | Tune one layer at a time and verify that release returns both look axes to zero. |
| Desktop input unexpectedly changes touch input. | Legacy **Allow Axis Input** or **Allow Button Input**, or Input System control-scheme switching, may combine sources. | Disable the unwanted legacy fallback or revise the Input System bindings and device pairing. |
| Two players respond to the same touch controls. | Both roots may follow the same camera character, or the virtual device may not be paired per player. | Assign **Character** explicitly on each root and configure ownership in the selected input system. |
## Related pages
- [Input](https://opsive.com/support/documentation/ultimate-character-controller/input/)
- [Quick Setup](https://opsive.com/support/documentation/ultimate-character-controller/getting-started/quick-setup/)
- [Split Screen](https://opsive.com/support/documentation/ultimate-character-controller/camera/split-screen/)
- [Control Freak](https://opsive.com/support/documentation/ultimate-character-controller/integrations/control-freak/)
## Developer reference
Both root components expose a `Character` property for a character spawned or selected at runtime. The legacy manager also exposes `AllowAxisInput` and `AllowButtonInput`. Assigning `Character` performs the same unregister/register work as changing ownership in the Inspector.
```csharp
using Opsive.Shared.Input.InputManager.VirtualControls;
using UnityEngine;
#if ENABLE_INPUT_SYSTEM
using Opsive.Shared.Input.InputSystem;
#endif
public class VirtualControlOwner : MonoBehaviour
{
[SerializeField] private VirtualControlsManager m_LegacyControls;
#if ENABLE_INPUT_SYSTEM
[SerializeField] private OnScreenControls m_InputSystemControls;
#endif
public void SetCharacter(GameObject character)
{
if (m_LegacyControls != null) {
m_LegacyControls.Character = character;
}
#if ENABLE_INPUT_SYSTEM
if (m_InputSystemControls != null) {
m_InputSystemControls.Character = character;
}
#endif
}
}
```
Changing `UnityInput.ForceInput` raises `OnUnityInputTypeChanged` with the legacy input instance and a Boolean virtual-input state. Changing `UnityInputSystem.ForceInput` raises `OnUnityInputSystemTypeChanged` with a Boolean on-screen state. The supplied root components listen to those events and activate or hide themselves automatically.
---
# State System
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/state-system/)
Use the State System to change selected public properties when gameplay conditions such as aiming, running, equipping an item, or entering water become active. It keeps these variations in Inspector-configured presets instead of spreading one-off value changes through gameplay scripts.
## When to use a state
A state is a good fit when the desired result is a temporary value change on a state-enabled component or serialized UCC object. Examples include a narrower camera field of view while aiming, different movement values while sprinting, or an item setting that changes while a named character state is active.
Use an ability, action module, or another gameplay system when the feature needs to perform an action rather than apply property values. A state does not replace the logic that decides when aiming, running, or another condition begins; it defines the values that should apply while that condition is active.
The only direct child in this section is [Presets](https://opsive.com/support/documentation/ultimate-character-controller/state-system/presets/). Read it when you need to choose which public properties a state stores, reuse a preset asset, or remove a property from a preset.
## Create a state
1. Open **Tools > Opsive > Ultimate Character Controller > Setup Manager**.
2. Select the **Scene** tab and choose **Add Managers** under **Manager Setup**. Confirm that the scene's **Game** GameObject has **State Manager**. The runtime can create a fallback manager, but keeping the service visible in the scene makes setup and event configuration easier to verify.
3. Select the state-enabled component, ability, movement type, view type, or item module that owns the value. Configure its normal Inspector values first; these become the runtime **Default** values.
4. Expand **States** and select the plus button.
5. Choose **Create New Preset**, save the asset under a project-owned folder such as `Assets//Presets`, and give it a descriptive name. Choose **Add Existing Preset** only when the asset was created for the same owner type.
6. Select the new preset asset. In its Inspector, use **Add Property...** to add only the public properties that this state should change, then enter their state-specific values. A property needs a usable public getter and setter to appear and apply at runtime.
7. Return to the owner and give the new row a unique, case-sensitive **State** name. The same logical condition must use the same spelling everywhere it should apply.
8. Drag the row to its priority position. The top active row wins when multiple presets set the same property. Leave **Default** at the bottom; it cannot be edited, removed, or moved.
9. Use **Blocked By** only when another active state should suppress this row completely. For example, on a camera's `Zoom` row choose `Run` under **Blocked By** when running should prevent the zoom preset from applying.
10. Save the component's scene or prefab and the preset asset, then test the actual gameplay trigger in Play Mode.
The **Persist** button copies the owner's current values into properties already stored by that row's preset. It changes the preset asset, so use it deliberately after confirming the selected owner and preset. The **Activate** button is available in Play Mode for a quick property check; it toggles that one row directly and is not a substitute for testing the real ability, item, or script that owns the state.
## Manage shared State names
A mapped State Name field opens a searchable popup. Select an existing entry, enter a valid name and choose **Add**, or choose **Open Editor** for the complete map. Open that editor directly from **Tools > Opsive > Ultimate Character Controller > Utility > State Names**.
For project-owned names, create **Assets > Create > Opsive > Ultimate Character Controller > Utility > NameMap**, assign it to **Name Map**, and keep the asset in version control. The first Add to a new map asks where to save its editable CSV file; store the map and CSV together. **Order By > Name Ascending** or **Name Descending** changes the editor presentation. Entries supplied through **Read Only Files** can be selected but cannot be edited or removed from this window.
The utility window remembers its selected map in editor preferences for that workstation. Verify the project map on every developer machine; choosing it in the utility window does not rewrite every existing scene or prefab. State names remain case-sensitive at runtime.
## How states combine
At runtime, the bottom **Default** state captures the owner's normal public property values and remains active. When another state activates, its preset changes only the properties stored in that preset. Unlisted properties continue to come from Default or another active state.
If several active states change the same property, the State System reapplies them from lower priority to higher priority, so the row nearest the top supplies the final value. When a state deactivates, the affected properties return to their Default values and the remaining active, unblocked states are applied again.
A row named in **Blocked By** is a blocker of the current row. If that blocker is active, the current state remains recorded as active but its preset is skipped. The Inspector only shows bold text and `(Active)` when the state is active and not blocked.
When a GameObject-based state change uses a shared name, State Manager updates the registered state owners for that GameObject. UCC also maps relevant character-owned child objects and the attached camera back to the character, allowing their matching states to follow the character condition. An item initialized after a character state is already active receives that active state during initialization.
## Key choices by scenario
| Scenario | Recommended configuration |
| --- | --- |
| Aim uses a different camera zoom for each weapon | Give the relevant camera view type and item owners the same state name, such as `Zoom`, but use a separate type-compatible preset for each owner. Store only the properties each owner needs to change. |
| Running should suppress aim zoom | On the camera's `Zoom` row, add `Run` to **Blocked By**. Do not put `Zoom` in the `Run` row unless zoom should block running instead. |
| A higher-priority condition should override one value but preserve others | Put the higher-priority row nearer the top and include only the property it owns. Values not present in that preset continue to come from lower active states. |
| Several characters share the same tuning | Reuse the same preset only for the same concrete owner type. Duplicate the preset before one character needs independent values. |
| A short damage or interaction effect needs temporary values | Activate a named state, then schedule its deactivation with `StateManager.DeactivateStateTimer`. The timer only schedules deactivation, so the state must already be active. |
| A linked object outside the normal character hierarchy should follow states | Link it deliberately with `StateManager.LinkGameObjects`, and give its state-enabled owners matching state names. Unlink it when the relationship ends. |
## Verify in Play Mode
1. Expand **States** on the owner and record the relevant Default property values.
2. Trigger the real ability, item condition, or script that activates the state. Confirm the expected row becomes bold and displays `(Active)`.
3. Inspect the affected component or StateObject. Only properties included in the preset should change.
4. Activate a second state that overlaps one property. Confirm the row nearer the top supplies the final value while nonoverlapping properties remain combined.
5. Test **Blocked By**. The suppressed row should lose its visible active marker and its values should no longer apply while its blocker is active.
6. End each condition. The remaining active states should recombine, and the last deactivation should restore the recorded Default values.
7. If the state should affect a camera or equipped item, test that object too. Equip or initialize an item while the character state is already active and confirm it starts with the matching values.
8. Stop Play Mode and reopen the scene or prefab. Confirm the state rows and preset references remain assigned and no runtime-only Inspector value was mistaken for an asset change.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| A state never becomes active. | The activating code or built-in feature uses a different spelling or case, or the owner was not initialized with State Manager. | Match the state name exactly, confirm the owner exposes **States**, and verify the scene's **Game** object has State Manager. |
| The row becomes active but no value changes. | The preset contains no property, uses the wrong owner type, or the property lacks a usable public getter and setter. | Open the preset, add the intended property with **Add Property...**, and use a preset created for that owner type. |
| The wrong value wins while several states are active. | Two presets change the same property and their list order is reversed. | Move the state that should win nearer the top, then repeat the overlap test in Play Mode. |
| A state is requested but does not show `(Active)`. | One of the names in that row's **Blocked By** field is active. | Remove the unintended blocker or deactivate it. Keep the blocker on the row that should be suppressed. |
| The camera or item does not follow a character state. | Its owner has no matching state name, has not initialized yet, or is outside the normal character/camera relationship. | Add a type-compatible preset under the exact shared name, verify initialization, or link the GameObjects deliberately. |
| Editing one preset changes several characters or items. | They reference the same preset asset. | Keep sharing when the values should remain common; otherwise duplicate the asset and assign the copy before editing. |
| **Persist** saved unexpected values. | The wrong row, owner, or shared preset was selected. | Undo or restore the preset from version control, select the intended project-owned asset, set the owner values, and persist again. |
| `OnStateChange` is never received. | **Send State Change Event** is disabled, or the state was toggled through the row's **Activate** button or an owner-specific overload instead of the GameObject-based path. | Enable the manager setting and use `StateManager.SetState(GameObject, string, bool)` for changes that need the global event. |
## Related tasks
- [Presets](https://opsive.com/support/documentation/ultimate-character-controller/state-system/presets/)
- [Events](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/)
- [Programming Concepts](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/)
- [Abilities](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/)
- [Movement Types](https://opsive.com/support/documentation/ultimate-character-controller/character/movement-types/)
- [View Types](https://opsive.com/support/documentation/ultimate-character-controller/camera/view-types/)
- [Action Modules and Groups](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/)
## Developer reference
The released Version 3 State System types are in `Opsive.Shared.StateSystem`. `StateBehavior` is the `MonoBehaviour` owner used by state-enabled components, while `StateObject` is the serializable owner used by abilities, movement types, view types, and other nested objects. Both expose `States`, `SetState(string, bool)`, `StateWillChange()`, and `StateChange()`.
Use the GameObject overload when a named condition should update all registered owners and participate in the optional global event:
```csharp
StateManager.SetState(character, "Zoom", true);
StateManager.SetState(character, "DamageFlash", true);
StateManager.DeactivateStateTimer(character, "DamageFlash", 0.25f);
```
`StateManager.SetState(object, State[], string, bool)` targets one registered owner and state array. `StateManager.ActivateState` toggles a specific `State` directly and is what the Inspector's **Activate** button uses. These narrower paths do not send the manager's global state-change event.
When **Send State Change Event** is enabled, the GameObject-based path sends the global `OnStateChange` event with `GameObject stateGameObject`, `string stateName`, and `bool active`. Register and unregister through the [event system](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/). The manager calls each affected owner's `StateWillChange()` before applying values and `StateChange()` afterward.
`StateManager.AddState(GameObject, IStateOwner, State[], State, int)` can add a non-default, uniquely named state with a preset after that owner has initialized in Play Mode. The index must be inside the existing array; use `0` for the highest-priority position. Prefer editor-authored states unless runtime composition is a real requirement, because the runtime API must also preserve the owner's state array and preset lifetime.
---
# Presets
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/state-system/presets/)
A State Preset stores selected public property values for one state-enabled owner type. Use one when a named gameplay condition should temporarily change Inspector values, such as Jump force, movement speed, camera field of view, or an item setting, then restore the normal values when that condition ends.
## When a preset is appropriate
Use a State Preset for value changes that already have a gameplay owner and a clear on/off condition. The system applies the preset while its State is active; it does not detect the condition, start an ability, play an animation, or save gameplay progress.
Keep the normal value directly on the component, ability, movement type, view type, or other state-enabled object. Put only the properties that should differ into the preset. An unlisted property continues to use its normal value or a value supplied by another active State.
Use separate gameplay logic when the change needs a sequence, spawned object, collision query, or another action rather than a property override.
## Create and assign a preset
1. Select the component or nested UCC object that owns the value and configure its normal Inspector values first. These become its runtime **Default** values.
2. Expand **States** at the bottom of the owner Inspector. The table contains **State**, **Preset**, **Blocked By**, **Persist**, and **Activate** columns, with the fixed **Default** row at the bottom.
3. Select the plus button and choose **Create New Preset**.
4. In **Save Preset**, save a unique `.asset` under a project-owned folder such as `Assets//Presets`. A new asset is typed for this owner and begins with no stored properties; it is not a snapshot of every current value.
5. Confirm the new row references that asset in **Preset**, then give the row a unique, case-sensitive **State** name that matches the condition that will activate it.
6. Select the preset asset. In its Inspector, choose a property from **Add Property...**, then enter the value that should apply while this State is active.
7. Return to the owner and drag the row to its priority position. Keep **Default** last; it cannot be edited, removed, or moved.
8. Save the owner scene or prefab and the preset asset.
**Add Existing Preset** opens a preset asset picker and adds a State that references the selected asset. Use an asset created for the same concrete owner type. The State Inspector rejects an incompatible recorded type rather than applying similarly named properties to the wrong object.
## Add, update, and remove properties
The preset Inspector lists public properties available on its recorded owner type. A property needs a usable public getter and setter to be a safe runtime override. The released Inspector can list a getter-only property, but the runtime delegate has no setter to apply it; do not add read-only properties.
When a property is first added, the preset uses the type's default value from a temporary default instance. It does not read the selected scene or prefab owner. Choose one of these workflows:
- Enter the state-specific value directly in the preset asset.
- Configure the desired value on the owner, then select the row's **Persist** control to copy the owner's current value into properties already stored by that preset.
**Persist** updates only properties already present in the preset. It changes the shared asset, not just that row or instance. It does not copy a top-level `UnityEngine.Object` property in released Version 3; assign an allowed project asset reference directly in the preset Inspector instead.
Select the **X** beside a property to remove that complete property and its stored value. The State will stop overriding it the next time values are initialized and applied.
## Choose what owns each value
| Goal | Recommended setup |
| --- | --- |
| One temporary difference | Leave the normal value directly on the owner and store only that property in one preset. |
| Several independent changes | Use separate presets and State names when the conditions start and stop independently. Each preset should contain only the values that condition owns. |
| One condition changes several related values | Put those properties in one preset so they activate and restore together. |
| Several objects use identical tuning | Share one preset asset only among the same owner type. Runtime initialization creates per-owner delegate instances, while the serialized values remain shared. |
| One character or item needs different tuning | Duplicate the preset asset and assign the copy before editing it. Editing a shared asset changes every row that references it. |
| A higher-priority State changes the same property | Move the State nearer the top of **States**. Active States are recombined so the top row supplies the final overlapping value. |
| One State should suppress another completely | On the row that should be suppressed, add the stronger State to **Blocked By**. A blocked State remains recorded as active but its preset is skipped. |
| A quick Play Mode value check | Use the row's **Activate** control in Play Mode. It toggles that row directly; still test the real ability, item, trigger, or code path afterward. |
The generated **Default** preset is different from the `.asset` assigned to a named State. During initialization, it captures the owner's normal public values. When a named State deactivates, Default restores the properties that State changed, then the remaining active, unblocked States are reapplied from lower priority to higher priority.
Directly editing an affected runtime property while its State remains active is temporary. The next State activation, deactivation, block change, or recombination can apply the preset again. Change the preset or the condition's ownership instead of fighting an active override.
## Work with nested values, lists, and references
A top-level public property can contain a serializable class, struct, array, or list. The preset Inspector expands its nested data, and the State treats that top-level property as one override. Removing it removes the complete nested value.
- Use a nested property when the complete setting should change and restore together.
- Expose separate top-level public properties when different States need independent priority over individual parts.
- Keep lists and arrays initialized. The runtime copies their elements into the owner's existing collection and resizes an array through its setter when necessary; a null destination cannot be updated safely.
- Store project asset references only when Unity can serialize them in the preset asset. A project-level preset cannot hold a durable reference to a scene object.
- Do not use a preset as mutable per-instance inventory, target, checkpoint, or save data. Those values belong to their runtime and persistence owners.
## How activation and ordering work
1. A state-enabled owner initializes its State array with State Manager in Play Mode.
2. The last **Default** row receives a generated runtime preset that captures the owner's normal public values and remains active.
3. Each named preset initializes delegates against that specific owner. When the same asset is already initialized for another owner, the State creates a runtime copy so delegates do not point to the earlier object.
4. A built-in feature or project call activates a State by its exact name. The preset changes only its stored properties.
5. When several unblocked States are active, the list is applied from lower priority to higher priority. The row nearest the top is applied last and wins overlapping properties.
6. **Blocked By** prevents a row's values from applying while a named blocker is active. Its active flag remains set so it can resume automatically when the blocker ends.
7. On deactivation, Default restores only the properties affected by that State, then the remaining active States are applied again.
The State Inspector's **Activate** control calls the narrow row activation path. It does not represent the owner callbacks or optional global state-change event used by the normal GameObject-based path, so treat it as a visual preset test rather than full gameplay verification.
## Editor checkpoint
Before Play Mode, confirm that:
- the owner exposes **States**, its normal direct values are correct, and **Default** remains last;
- every named row has a unique, case-sensitive name and a preset for the same concrete owner type;
- each preset contains only public getter-and-setter properties that the State should own;
- newly added values were entered directly or deliberately captured with **Persist**;
- shared assets are meant to remain shared, and instance-specific variants use duplicated assets;
- nested values and lists are initialized and contain no scene-object reference that an asset cannot serialize;
- overlapping presets are ordered with the intended winner nearer the top;
- **Blocked By** is configured on the row that should be suppressed; and
- the ability, item, trigger, or project code that owns activation uses the exact same State name.
## Verify in Play Mode
1. Create a small test preset on a visible property, such as Jump **Jump Force**, camera field of view, or a movement speed value. Record the owner's normal value.
2. Enter Play Mode and trigger the real gameplay condition. Confirm the row becomes bold and displays `(Active)` and the stored property changes to the preset value.
3. End the condition. Confirm the property returns to the normal value captured by Default.
4. Add a second State that changes the same property, place it above the first, and activate both. Confirm the top row supplies the final value.
5. Move that row below the first and repeat. Confirm the winner changes with the list order.
6. Add the stronger State to the weaker row's **Blocked By** field. Activate both and confirm the weaker row is suppressed; deactivate the blocker and confirm the still-active weaker State resumes.
7. Add a nonoverlapping property to one preset. Confirm both States can remain active and combine their independent values.
8. If the preset is shared, test two owners of the same type. Confirm both use the asset values without one owner's runtime delegate targeting the other.
9. Stop Play Mode, reopen the preset asset and owner, and confirm only editor-authored asset and row changes persisted. Runtime active flags and temporary Inspector values should be gone.
## Troubleshooting and released-Version-3 limitations
| Symptom | Check | Fix |
| --- | --- | --- |
| A new preset contains no component snapshot | This is the released workflow: **Create New Preset** creates an empty typed asset. | Add the intended properties, enter their values, or use **Persist** after the properties exist. |
| The row becomes active but no value changes | The preset has no property, the wrong property was added, or the State is blocked. | Open the asset, add the intended property, inspect **Blocked By**, and repeat the Play Mode test. |
| A property appears in **Add Property...** but fails when activated | It has a public getter but no usable public setter. The Inspector's availability check is less strict than runtime application. | Expose a public setter or choose another supported property. Do not add a read-only value. |
| The preset cannot be assigned | Its recorded object type does not match the State owner type. | Create or select a preset from the same concrete component, ability, movement type, view type, or nested owner. |
| **Persist** saved surprising values | The wrong owner or shared asset was selected, or the component was already under another active override. | Restore or undo the asset, configure the intended owner in Edit Mode, verify the row, and persist again. |
| **Persist** does not update an asset reference | Released Version 3 skips a top-level `UnityEngine.Object` property in the Persist path. | Assign a project asset directly in the preset Inspector. Do not use a scene-object reference. |
| Editing one preset changes several characters or items | Their rows reference the same asset. | Keep the shared asset for common tuning or duplicate it and assign the copy before editing. |
| The wrong value wins | Two active presets include the same property and their list order is reversed. | Move the intended winner nearer the top and retest both States together. |
| The value returns to an unexpected default | The normal owner value was changed after State initialization or loaded after Default captured its runtime snapshot. | Establish and load normal values before State initialization, or deliberately reinitialize/restore them through the system that owns load order. |
| A nested list fails or keeps old elements | The owner's collection is null, its getter/setter is unsuitable, or the preset was not refreshed after the desired list changed. | Keep the collection initialized, expose a usable public getter/setter, then edit the preset or use **Persist** for the stored property. |
| The row is active but does not show `(Active)` | Another active row in **Blocked By** suppresses it. | Remove the unintended blocker or end that condition. |
| `OnStateChange` is not received during the Inspector test | **Activate** calls the direct row path, and the manager event is only sent by the GameObject-based path when enabled. | Test through `StateManager.SetState(GameObject, string, bool)` and enable State Manager **Send State Change Event** when an integration needs it. |
## Saving and networking
The preset `.asset`, the owner's State rows, their names, list order, block lists, and preset references are authored configuration. The active flag, generated Default snapshot, runtime delegate copies, linked-object maps, and timed deactivations are transient.
A save system should store the authoritative gameplay condition or active State names that must survive loading. Restore normal owner data first, wait until its States initialize, then reactivate the required names. Saving only the active flag is insufficient when the system that owns the ability, item, camera, or other condition disagrees after load.
State Presets do not replicate themselves or their active status. State Manager **Send State Change Event** starts disabled and only exposes the GameObject-based change to a listening integration; it does not perform networking. Let authority choose the change, keep matching preset assets on every peer, and let the installed integration or project code synchronize the State name and active value.
## Related tasks
- [State System](https://opsive.com/support/documentation/ultimate-character-controller/state-system/) explains State creation, priority, blocking, and cross-owner activation.
- [Events](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/) explains registration for the optional global State change event.
- [Abilities](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/) covers common owners and gameplay triggers for named States.
- [Movement Types](https://opsive.com/support/documentation/ultimate-character-controller/character/movement-types/) covers movement settings that can be varied with a State.
- [Character Time](https://opsive.com/support/documentation/ultimate-character-controller/character/time/) shows a practical `TimeScale` State property.
- [Object Fader](https://opsive.com/support/documentation/ultimate-character-controller/camera/object-fader/) is an example of a component whose behavior can be tuned by State values.
## Developer reference
The released types are in `Opsive.Shared.StateSystem`. `PersistablePreset` stores serialized property data and initializes per-owner delegates. `StateBehavior` is the component owner and `StateObject` is the nested serializable owner; both expose `States`, `SetState(string, bool)`, `StateWillChange()`, and `StateChange()`.
Use the GameObject path when the same State name should update all registered owners on that object and participate in the optional global event:
```csharp
using Opsive.Shared.StateSystem;
StateManager.SetState(character, "Zoom", true);
StateManager.SetState(character, "DamageFlash", true);
StateManager.DeactivateStateTimer(character, "DamageFlash", 0.25f);
```
`DeactivateStateTimer` schedules only deactivation, so activate the State first. `StateManager.SetState(object, State[], string, bool)` targets one registered owner. `StateManager.ActivateState(State, bool, State[])` toggles a specific row and is the path used by the Inspector's **Activate** control. Only the GameObject overload sends the optional global `OnStateChange(GameObject, string, bool)` event when State Manager **Send State Change Event** is enabled.
`Preset.Initialize`, `UpdateValue`, and `ApplyValues` operate on runtime delegates; they do not save an edited asset automatically. `PersistablePreset.CreatePreset(object)` creates an in-memory typed preset with empty property data under the editor workflow's default visibility. Asset creation and durable changes remain editor/project responsibilities.
---
# Attributes
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/attributes/)
Attributes store bounded values such as health, shield, stamina, hunger, battery charge, or durability. Add them to an Attribute Manager when gameplay needs a named value that other UCC components can read, spend, restore, or update over time.
## Choose the setup path
| Goal | Start here |
| --- | --- |
| Give a UCC character health, shield, death, and respawn support | In Character Manager, enable **Health**. This adds **Character Attribute Manager**, **Character Health**, and **Character Respawner**. Continue with [Health](https://opsive.com/support/documentation/ultimate-character-controller/attributes/health/). |
| Add stamina or another value to a character that already has health | Add the new entry to its existing **Character Attribute Manager**. |
| Add attributes to a character without the health system | Add **Character Attribute Manager** to the character so initialization follows the UCC character lifecycle. |
| Add charge, durability, or another value to an item or ordinary GameObject | Add the standard **Attribute Manager** component to that object. |
The manager stores values; it does not decide what consumes them. Connect each attribute to a Health component, ability Attribute Modifier, item action, UI monitor, or custom system by using the exact same attribute name.
## Add and configure an attribute
1. For a character that needs health, open **Tools > Opsive > Ultimate Character Controller > Character Manager**, assign **Character**, enable **Health**, and select **Build Character** or **Update Character**.
2. Select the GameObject and locate **Character Attribute Manager** or **Attribute Manager** in the Inspector.
3. Select the plus button below the **Attribute** list. Select the new row to show its settings.
4. Set **Name** to a unique, nonempty value such as `Stamina`. Names are case-sensitive at runtime, so copy the same spelling into every component that references it.
5. Set **Min Value**, **Max Value**, and the starting **Value**. The Inspector keeps the range valid and clamps the starting value inside it.
6. Choose **Auto Update Value Type**. Use **None** for a value changed only by gameplay, **Increase** to move toward **Max Value**, or **Decrease** to move toward **Min Value**.
7. When automatic updates are enabled, configure **Update When Inactive**, **Auto Update Start Delay**, **Auto Update Interval**, and **Auto Update Amount**.
8. Configure the component that consumes the value. For example, select `Health` in **Character Health > Health Attribute**, or select `Stamina` in an ability's **Attribute Modifier**.
9. Enter Play Mode and change the value through the real gameplay action before duplicating the setup.
Disabling **Health** in Character Manager removes the character's attribute manager together with Character Health and Character Respawner. Preserve or recreate any custom attributes before deliberately removing that managed component set.
## Choose the value and update settings
| Setting | Decision |
| --- | --- |
| **Name** | Use a stable, unique identifier. `GetAttribute` and UCC consumers match this exact string. |
| **Min Value** and **Max Value** | Define the legal range. Runtime assignments and automatic updates are clamped to these bounds. |
| **Value** | Set the starting value captured when the attribute initializes. `ResetValue()` returns to this starting value. |
| **Auto Update Value Type** | Choose **Increase** for regeneration, **Decrease** for continuous depletion, or **None** when another system owns every change. |
| **Update When Inactive** | Enable it only when automatic updates must continue while the owning GameObject is inactive. |
| **Auto Update Start Delay** | Set how long an automatic update waits after initialization or a direct value change. Every `Value` assignment restarts this delay. |
| **Auto Update Interval** | Set the time between automatic update steps. Short intervals look smoother but execute more often. |
| **Auto Update Amount** | Enter the positive amount applied on each step. **Increase** adds it; **Decrease** subtracts it. |
Use the **States** foldout only when a named UCC state should override attribute settings. Keep the default values correct first, then test every state transition that changes the range or automatic update behavior. See the [State System](https://opsive.com/support/documentation/ultimate-character-controller/state-system/).
## Configure common scenarios
### Health and a regenerating shield
Keep the `Health` attribute at its full starting value with **Auto Update Value Type** set to **None** unless the game deliberately regenerates health. Add a separate `Shield` attribute, choose **Increase**, and use **Auto Update Start Delay** to create the pause after taking damage. In Character Health, set **Health Attribute** and **Shield Attribute** to those exact names.
The Health component applies shield damage before health and provides damage, healing, death, hitbox, and fall-damage behavior. Follow the direct child guide: [Health](https://opsive.com/support/documentation/ultimate-character-controller/attributes/health/).
### Stamina used by an ability
Add `Stamina` to **Character Attribute Manager** and let it regenerate with **Increase**. On the ability, select `Stamina` in **Attribute Modifier**, set a negative **Amount**, and enable the modifier's **Auto Update** when the cost should repeat while the ability remains active. The ability checks the modifier before starting and can stop when the repeated cost reaches the minimum.
The ability modifier temporarily owns the attribute's auto-update settings while active, then restores the previous settings and schedules the normal attribute update again. Test the transition from drain to regeneration rather than configuring both in isolation.
### Hunger or another continuous countdown
Choose **Decrease**, set the starting **Value** near **Max Value**, and use a longer **Auto Update Interval** with a suitable **Auto Update Amount**. Another gameplay system must decide what happens at the minimum; the Attribute Manager only changes and reports the value.
### Item charge or durability
Put an **Attribute Manager** on the item when the value belongs to that item rather than the character. UCC item actions can reference values such as a usable action's use attribute or a shield's durability attribute. Ensure the action's attribute name matches the manager entry exactly.
## How attributes run
When an Attribute Manager initializes, it builds a name lookup and records each attribute's starting value. Assigning `Value` clamps it between **Min Value** and **Max Value**, sends `OnAttributeUpdateValue`, cancels the previous automatic-update schedule, and starts a new delay when the attribute is not already at its destination.
After the delay, **Increase** adds **Auto Update Amount** until **Max Value**, while **Decrease** subtracts it until **Min Value**. Each step sends another update event. Reaching the destination sends `OnAttributeReachedDestinationValue` on that Attribute instance. If **Update When Inactive** is disabled, the automatic update does not run while the owning GameObject is inactive.
Attribute names must remain unique. The manager builds its runtime lookup by name, and `GetAttribute` returns `null` when no exact match exists.
## Verify in Play Mode
1. Inspect the manager immediately after the scene starts. Every attribute should begin inside its configured range with the intended starting value.
2. Trigger the real action that spends or restores the value. Confirm it changes once by the expected amount and never passes its minimum or maximum.
3. For an auto-updating attribute, change the value and time the **Auto Update Start Delay**. Confirm each later step follows **Auto Update Interval** and reaches the correct bound.
4. Change the value again during the delay. Confirm the delay restarts rather than allowing an older scheduled update to run.
5. Start and stop any ability that uses **Attribute Modifier**. Confirm the ability cost, minimum-value stop, and return to the attribute's normal regeneration behavior.
6. If **Update When Inactive** matters, disable and re-enable the GameObject during the delay and during repeated updates. Confirm the result matches the chosen setting.
7. Verify every UI element and consuming component follows the correct attribute, especially when Health, Shield, and Stamina exist together.
8. Test any required reset path. Character Health resets its configured Health and Shield attributes on respawn; custom attributes need their own deliberate reset behavior.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| A component cannot find the attribute. | Its name may be blank, duplicated, misspelled, or use different capitalization. | Give every entry a unique name and copy that exact value into the consuming component. |
| The value immediately snaps to an unexpected number. | **Value** may be outside **Min Value** and **Max Value**, or a state may override the range. | Correct the default range, inspect active States, and retest from a fresh initialization. |
| Regeneration never starts. | **Auto Update Value Type** may be **None**, the value may already be at its destination, or the GameObject may be inactive without **Update When Inactive**. | Choose **Increase** or **Decrease**, move the value away from its destination, and select the inactive behavior deliberately. |
| Regeneration begins too soon after repeated damage or use. | **Auto Update Start Delay** may be too short, or an active State or Attribute Modifier may temporarily replace the update settings. | Inspect the active overrides, then increase the normal start delay and retest the complete transition. |
| A drain increases the value instead. | **Auto Update Amount** on the Attribute should be positive, or an Attribute Modifier may have the wrong sign. | Use a positive Attribute amount with **Decrease**, and a negative modifier **Amount** for a cost. |
| An ability starts without enough stamina or stops immediately. | Its **Attribute Modifier** may reference the wrong name, use an unsuitable amount, or begin at the minimum. | Select the correct attribute, verify the cost against the starting value, and retest the ability from full stamina. |
| Health changes but the shield does not absorb damage. | **Character Health > Shield Attribute** may be empty or may not match the Shield entry. | Assign the exact shield name and verify the shield starts above its minimum. |
| Custom attributes disappeared after a Character Manager update. | The **Health** option may have been disabled, which removes Character Attribute Manager with the managed health set. | Restore the managed components and attributes from version control or a backup, then keep **Health** enabled when using that set. |
| The UI does not update. | It may observe a different GameObject or attribute name, or it may not listen for `OnAttributeUpdateValue`. | Point the monitor at the manager's GameObject and exact name, then verify the update event is registered and unregistered correctly. |
## Related pages
- [Health](https://opsive.com/support/documentation/ultimate-character-controller/attributes/health/) covers health, shield, damage, healing, death, and fall damage.
- [Character Creation](https://opsive.com/support/documentation/ultimate-character-controller/character/character-creation/) explains the Character Manager workflow that adds the managed health component set.
- [Abilities](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/) explains ability configuration and the Attribute Modifier shared by abilities.
- [Usable Item Actions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/) describes item and character use attributes.
- [Shield](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/shield/) uses an item Attribute Manager for durability.
- [Die](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/die/) connects depleted health to character death and respawn.
- [Events](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/) explains registering and unregistering UCC events.
- [Event Names](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/event-names/) lists the attribute update, destination, and modifier events.
## Developer reference
Retrieve an attribute by its exact name, guard against a missing entry, and change it through `Value` so clamping, events, and the automatic-update delay all run.
```csharp
using UnityEngine;
using Opsive.Shared.Events;
using Opsive.UltimateCharacterController.Traits;
using Attribute = Opsive.UltimateCharacterController.Traits.Attribute;
[RequireComponent(typeof(AttributeManager))]
public class StaminaConsumer : MonoBehaviour
{
private AttributeManager m_AttributeManager;
private Attribute m_Stamina;
private void Awake()
{
m_AttributeManager = GetComponent();
m_Stamina = m_AttributeManager.GetAttribute("Stamina");
EventHandler.RegisterEvent(gameObject, "OnAttributeUpdateValue", OnAttributeUpdateValue);
}
public bool TrySpend(float amount)
{
if (m_Stamina == null || amount < 0 || !m_Stamina.IsValid(-amount)) {
return false;
}
m_Stamina.Value -= amount;
return true;
}
private void OnAttributeUpdateValue(Attribute attribute)
{
if (attribute == m_Stamina) {
Debug.Log($"Stamina: {attribute.Value}");
}
}
private void OnDestroy()
{
EventHandler.UnregisterEvent(gameObject, "OnAttributeUpdateValue", OnAttributeUpdateValue);
}
}
```
The current Version 3 runtime surface includes:
- `AttributeManager.Attributes` to replace or inspect the managed array and `GetAttribute(string)` to retrieve an entry.
- `Attribute.Value`, `MinValue`, and `MaxValue`, with clamping performed through the `Value` setter.
- `ScheduleAutoUpdate(float)`, `CancelAutoUpdate()`, `IsAtDestinationValue()`, `IsValid(float)`, and `ResetValue()` for lifecycle control.
- `AttributeModifier.Initialize`, `IsValid`, and `EnableModifier` for one-time or repeated changes owned by abilities and other systems.
- `OnAttributeUpdateValue` on the manager's GameObject, `OnAttributeReachedDestinationValue` on the Attribute instance, and `OnAttributeModifierAutoUpdateEnabled` on the AttributeModifier instance.
---
# Health
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/attributes/health/)
Health turns Attribute Manager values into damage, healing, shield, death, and respawn behavior. Use **Character Health** for a UCC character, or the generic **Health** component for a crate, target, or other GameObject.
## Choose the setup
| Goal | Components to use |
| --- | --- |
| A UCC character can take damage and respawn | **Character Attribute Manager**, **Character Health**, and **Character Respawner**. Character Manager adds this set when **Health** is enabled. |
| A character should also play a death ability | Add **Die** to **Ultimate Character Locomotion > Abilities** after creating the health set. Character Manager does not add Die with the **Health** option. |
| A character should ragdoll or revive | Add and configure the **Ragdoll** or **Revive** ability in addition to the health set. |
| An ordinary object can take damage | Add **Attribute Manager** and **Health** to the same GameObject. Add **Respawner** only when that object should return. |
Health requires an Attribute Manager on the same GameObject. Its **Health Attribute** and optional **Shield Attribute** select entries from that manager by name.
## Set up character health
1. Place the character in the scene and open **Tools > Opsive > Ultimate Character Controller > Character Manager**.
2. Assign **Character**, enable **Health**, and select **Build Character** or **Update Character**.
3. Select the character and confirm it now has **Character Attribute Manager**, **Character Health**, and **Character Respawner**.
4. In **Character Attribute Manager**, select the default `Health` entry and set its **Min Value**, **Max Value**, and starting **Value**. The default entry starts at `100` with a minimum of `0` and maximum of `100`.
5. In **Character Health**, select `Health` for **Health Attribute**.
6. Add and configure a `Shield` attribute only when damage should consume a separate shield first. Select it in **Shield Attribute**.
7. If the character needs a visible death animation, add [Die](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/die/) to the ability list and verify its Animator transitions.
8. Configure **Character Respawner** for the intended return location and delay, then test the complete damage-to-respawn sequence in Play Mode.
For a non-character object, add **Attribute Manager** and **Health** manually, create the same named attributes, and choose them from the Health Inspector. The generic Health component supports damage, healing, hitboxes, death objects, audio, Unity events, and optional deactivation, but it does not add character fall damage.
## Configure health and shield
Damage is applied to Shield first and Health second. Death occurs when neither configured attribute remains above its **Min Value**.
Healing uses the opposite priority: `Heal` fills Health first, then puts any remaining amount into Shield. Use the Attribute Manager's automatic update when Shield should regenerate independently after a delay.
| Field | Version 3 default | Use it for |
| --- | --- | --- |
| **Invincible** | Disabled | Ignore normal damage while a state, cutscene, or gameplay rule protects the object. |
| **Time Invincible After Spawn** | `0` seconds | Ignore normal damage for this duration after `OnRespawn`. Before the first respawn, Version 3 compares the value with time since application start. |
| **Health Attribute** | `Health` | Select the primary Attribute Manager value. |
| **Shield Attribute** | **(None)** | Select an optional value that absorbs damage before Health. |
Keep normal Health automatic updating set to **None** unless the game deliberately regenerates it. For a regenerating Shield, choose **Increase** on the Shield attribute and configure its delay, interval, and amount. Every shield value change restarts that delay.
See [Attributes](https://opsive.com/support/documentation/ultimate-character-controller/attributes/) for the complete automatic-update workflow.
## Configure hit locations
Use **Hitboxes** when specific colliders should change non-radius damage, such as reduced limb damage or increased head damage:
1. Expand **Hitboxes** in Health.
2. Add an entry and assign its **Collider**.
3. Set **Damage Multiplier** to `1` for unchanged damage, below `1` for reduced damage, or above `1` for increased damage.
4. Keep **Max Hitbox Collision Count** at its default `10` unless the fallback raycast can encounter more overlapping colliders.
5. Test each collider with the actual weapon or impact that supplies the hit collider and damage direction.
Hitbox multipliers apply only to non-radius damage that includes a nonzero direction and a hit collider. Radius damage does not use the multiplier because one explosion can overlap multiple colliders.
## Configure feedback and death
Use the foldouts in the Health Inspector for focused feedback:
- **Audio > Take Damage**, **Heal**, and **Death** select the Audio Clip Sets played for those outcomes. Lethal damage plays Death audio instead of Take Damage audio.
- **UI > Damage Popup Manager ID** connects the Health component to a registered Damage Popup Monitor. Leave the default `-1` when no popup manager is used.
- **Events** exposes Unity events for damage, healing, and death. Use these for local Inspector wiring; use UCC events when several systems or code listeners need the notification.
- On Character Health, **Damaged Effect** and **Damaged Effect Index** select an existing character Effect to start after accepted damage.
Expand **Death** to configure the result:
| Field | Version 3 default | Behavior |
| --- | --- | --- |
| **Spawned Objects On Death** | Empty | Instantiates each prefab through the object pool at the object's position and rotation. |
| **Destroyed Objects On Death** | Empty | Returns pooled objects to their pool or destroys ordinary objects. |
| **Deactivate On Death** | Disabled | Deactivates the object after **Deactivate On Death Delay**. |
| **Deactivate On Death Delay** | `0` seconds | Delays deactivation when that option is enabled. Keep it shorter than the minimum respawn time. |
| **Death Layer** | None | Moves the object to a single layer while dead; Character Health also updates the locomotion collision layer. |
Health cancels Health and Shield regeneration on death. On `OnRespawn`, it restores those two attributes to their recorded starting values and restores the alive layer. Spawned or destroyed death objects are not automatically reversed; another system must restore any persistent scene state.
The Character Respawner added by Character Manager defaults to **Start Location**, a random delay between **Min Respawn Time** `2` and **Max Respawn Time** `3`, and scheduling on death. Follow [Respawner](https://opsive.com/support/documentation/ultimate-character-controller/spawn-system/respawner/) when the character should use a Spawn Point, stay dead, or be revived by another system.
## Configure fall damage
Character Health adds a **Fall Damage** foldout. The generic Health component does not receive character landing events.
| Field | Version 3 default | Behavior |
| --- | --- | --- |
| **Apply Fall Damage** | Disabled | Enables damage when the reported fall height reaches the minimum. |
| **Min Fall Damage Height** | `3` | Falls below this height do no damage. |
| **Min Fall Damage** | `1` | Damage at the minimum height. |
| **Max Fall Damage** | `50` | Damage just below **Death Height**. |
| **Death Height** | `20` | A fall at or above this height sends infinite damage through the normal damage path. |
| **Damage Curve** | Linear | Maps the normalized distance between minimum height and death height to the range between minimum and maximum damage. |
Test the curve with several known ledge heights. **Invincible** and **Time Invincible After Spawn** also guard fall damage because Character Health sends the calculated amount through the normal `Damage` method.
## How health runs
An accepted damage request follows this order:
1. Reject zero damage, an already-dead object, **Invincible**, or the active spawn grace period.
2. Apply a qualifying hitbox multiplier.
3. Subtract from Shield down to its minimum, then apply any remainder to Health down to its minimum.
4. Apply force through the character force interface or a non-kinematic Rigidbody.
5. Send damage events and update the optional damage popup.
6. If both configured attributes are at their minimum, run death behavior and send `OnDeath`; otherwise play Take Damage audio.
Death spawns and destroys configured objects, changes the death layer, plays Death audio, optionally schedules deactivation, cancels attribute regeneration, and notifies UCC systems. Ultimate Character Locomotion, Die, Ragdoll, inventory, camera, UI, and Respawner can respond to the same `OnDeath` event.
`Heal` clamps the applied amount to the available Health and Shield capacity and returns `false` when nothing changed. Healing attribute values after death does not run the respawn lifecycle by itself; use Respawner or a configured Revive workflow to restore the full character state.
## Verify in Play Mode
1. Confirm the Inspector shows the intended starting Health and Shield values after initialization.
2. Apply damage smaller than the current Shield. Shield should decrease, Health should remain unchanged, and shield regeneration should restart only after its delay.
3. Apply enough damage to exhaust Shield. Confirm only the remainder reduces Health.
4. Heal a partially damaged object. Health should fill before any remaining amount restores Shield.
5. Strike every configured hitbox with the real damage source. Confirm its multiplier changes non-radius damage and radius damage remains unmultiplied.
6. Toggle **Invincible**, then respawn and test during **Time Invincible After Spawn**. No damage, force, damage event, or popup should occur while the request is rejected.
7. Apply lethal damage. Confirm death audio, Unity/UCC events, layer changes, death objects, ability behavior, and deactivation occur once.
8. Let Respawner complete. Health and Shield should return to their starting values, the alive layer should be restored, and the character should move and receive damage again after the grace period.
9. For Character Health, test falls below the minimum, near the minimum, between the limits, and at **Death Height**.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| Health shows an Attribute Manager warning or fails during initialization. | The same GameObject may not have **Attribute Manager** or **Character Attribute Manager**. | Add the correct manager before Health and create the referenced attributes. |
| Damage has no effect. | The object may already be considered dead, be **Invincible**, still be inside the spawn grace period, or receive zero damage. | Confirm at least one configured attribute is above its minimum, then disable immunity or wait for the grace period. |
| Damage skips Shield. | **Shield Attribute** may be **(None)**, miss the exact attribute, or already be at its minimum. | Select the Shield entry in Character Health and verify its starting value and range. |
| Healing restores Shield before Health. | Another system may be changing the attributes directly rather than calling `Health.Heal`. | Use `Heal` when the intended rule is Health first, then Shield. |
| A headshot multiplier does not apply. | The damage may be radius-based, omit its direction or hit collider, or reference a different collider. | Send non-radius damage with the actual collider and direction, then verify the **Hitboxes** entry. |
| The character reaches zero Health but never plays a death animation. | Character Manager adds the health component set, not the **Die** ability or its Animator transitions. | Add and configure [Die](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/die/). |
| The object deactivates after it already respawned. | **Deactivate On Death Delay** may be longer than the Respawner's minimum delay. | Shorten the deactivation delay, lengthen the respawn delay, or disable death deactivation. |
| Shield or Health regenerates after death. | A separate system may be changing the attributes or scheduling its own updates. | Confirm Health owns the same attributes, remove the competing update, and verify death reaches `OnDeath`. |
| `Heal` raises the values but the dead character remains unusable. | Healing does not send `OnRespawn` or restore locomotion and ability state. | Use Character Respawner or the [Revive](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/revive/) workflow. |
| Fall damage never occurs. | The component may be generic Health, **Apply Fall Damage** may be disabled, or the landing height may be below the minimum. | Use Character Health, enable the option, and test from a measured height above the threshold. |
| Damage feedback appears twice. | The same response may be wired to both the Inspector Unity event and a UCC event listener. | Keep one owner for each audio, UI, or gameplay response. |
## Related pages
- [Attributes](https://opsive.com/support/documentation/ultimate-character-controller/attributes/) configures bounds, regeneration, names, and attribute events.
- [Character Creation](https://opsive.com/support/documentation/ultimate-character-controller/character/character-creation/) adds the character health component set through Character Manager.
- [Die](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/die/), [Ragdoll](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/ragdoll/), and [Revive](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/revive/) define visible character death and recovery behavior.
- [Respawner](https://opsive.com/support/documentation/ultimate-character-controller/spawn-system/respawner/) configures timing and return location.
- [Damage Processor](https://opsive.com/support/documentation/ultimate-character-controller/objects/damage-processor/) describes reusable damage-data processing.
- [Health Pickup](https://opsive.com/support/documentation/ultimate-character-controller/objects/object-pickup/health-pickup/) restores health through a pickup.
- [Damage Visualization](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/damage-visualization/) reacts to health damage with character feedback.
- [Events](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/) explains UCC event registration and cleanup.
- [Event Names](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/event-names/) lists the standard health, death, and respawn signatures.
## Developer reference
### Damage, heal, and death APIs
Use positive amounts and the simplest overload that preserves the information the gameplay needs. `Damage(float)` applies value damage without a direction, force, attacker, or hit collider; richer overloads and `Damage(DamageData)` support those details.
```csharp
using UnityEngine;
using Opsive.UltimateCharacterController.Traits;
public class HealthCommands : MonoBehaviour
{
[SerializeField] private Health m_Health;
public void ApplyDamage(float amount)
{
if (amount > 0) {
m_Health.Damage(amount);
}
}
public bool ApplyHealing(float amount)
{
return amount > 0 && m_Health.Heal(amount);
}
public void KillImmediately()
{
m_Health.ImmediateDeath();
}
}
```
`ImmediateDeath` temporarily bypasses **Invincible** and sends enough damage through the normal damage path. In the current Version 3 implementation, **Time Invincible After Spawn** still rejects that request while its grace period is active.
Useful runtime properties include `HealthValue`, `ShieldValue`, combined `Value`, `HealthAttribute`, `ShieldAttribute`, `Invincible`, and the configured attribute-name, hitbox, death, audio, popup, and Unity-event properties. `IsAlive()` returns true while either configured Health or Shield is above its minimum.
### Health events
Register UCC events on the GameObject that owns Health, and unregister the same callback when the listener is destroyed:
```csharp
using UnityEngine;
using Opsive.Shared.Events;
public class HealthListener : MonoBehaviour
{
private void Awake()
{
EventHandler.RegisterEvent(
gameObject, "OnHealthDamage", OnDamage);
EventHandler.RegisterEvent(gameObject, "OnHealthHeal", OnHeal);
EventHandler.RegisterEvent(gameObject, "OnDeath", OnDeath);
}
private void OnDamage(float amount, Vector3 position, Vector3 force, GameObject attacker, Collider hitCollider)
{
Debug.Log($"Damage remaining after Shield: {amount}");
}
private void OnHeal(float amount)
{
Debug.Log($"Health and Shield restored: {amount}");
}
private void OnDeath(Vector3 position, Vector3 force, GameObject attacker)
{
Debug.Log($"Killed by: {attacker}");
}
private void OnDestroy()
{
EventHandler.UnregisterEvent(
gameObject, "OnHealthDamage", OnDamage);
EventHandler.UnregisterEvent(gameObject, "OnHealthHeal", OnHeal);
EventHandler.UnregisterEvent(gameObject, "OnDeath", OnDeath);
}
}
```
The current Version 3 event surface is:
- `OnHealthDamage(float amount, Vector3 position, Vector3 force, GameObject attacker, Collider hitCollider)`. The float is the damage remaining after Shield absorption in the current processing order.
- `OnHealthDamageWithData(DamageData damageData)` for the structured damage context available during the callback. Scalar `Damage` overloads use pooled data, so listeners should not retain that instance after the callback.
- `OnHealthHeal(float amount)` with the amount actually applied, not the amount requested.
- `OnDeath(Vector3 position, Vector3 force, GameObject attacker)` after death processing runs.
- `OnRespawn()` from Respawner; Health uses it to reset Health, Shield, layer, and spawn-grace timing.
The **Events** foldout also exposes Unity callbacks for damage (`float`, position, force, attacker), healing (`float`), and death (position, force, attacker). The Unity damage callback does not include the hit collider or full `DamageData`.
---
# Inverse Kinematics (IK)
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/inverse-kinematics/)
Character IK adjusts a humanoid after its animation has evaluated so its feet can meet uneven ground, its upper body can follow the look direction, and its hands can remain aligned with equipped items. Use UCC's built-in **Character IK** for a Unity Humanoid rig; use animation or a separately supported IK integration for other rig types.
## Before you begin
- Import the character as **Humanoid** and confirm that Unity reports a valid Avatar with head, hips, hands, upper arms, feet, and lower-leg bones. UCC's built-in Character IK uses Unity's humanoid IK and does not solve a Generic rig.
- Start with a working **Animator**, **Animator Monitor**, **Ultimate Character Locomotion**, and camera or AI look source. Character IK remains disabled until an `ILookSource` attaches.
- Use an Animator Controller whose intended IK layers have **IK Pass** enabled. UCC's released Version 3 defaults expect **Base Layer Index** `0` and **Upper Body Layer Index** `4`.
- Decide which provider owns the animated model. Do not run **Character IK** and [Final IK Bridge](https://opsive.com/support/documentation/ultimate-character-controller/integrations/final-ik/) on the same model.
Separate first-person arms are normally Generic rigs. Character IK belongs on the humanoid character model, not on those arms; first-person arms and items use their authored animations and [first-person item springs](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/first-person-perspective/).
## Add Character IK
1. Open **Tools > Opsive > Ultimate Character Controller > Character Manager**.
2. Select the character. For a new model, enable **Animator**, set **Model Type** to **Humanoid**, and assign the intended Animator Controller.
3. Enable **Unity IK**. This option defaults to enabled for a valid Humanoid and is disabled for a Generic model.
4. Select **Build Character** for a new character or **Update Character** for an existing one.
5. Select the animated model GameObject that contains **Animator** and **Animator Monitor**. Confirm that **Character IK** was added there. A character with switchable models needs one compatible IK provider on every humanoid model that can become active.
6. On a custom Animator Controller, enable **IK Pass** on the layers that should solve the lower and upper body, then set **Base Layer Index** and **Upper Body Layer Index** to those layer indices.
7. Enter Play Mode once and confirm the component enables after the camera or AI look source attaches. Resolve bone, Avatar, layer, and look-source problems before tuning weights.
### Editor checkpoint
Before tuning the pose, confirm that **Character IK** is on the Animator model rather than only the locomotion root, the model is Humanoid, the required bones resolve, the layer indices match IK-enabled Animator layers, and exactly one `CharacterIKBase` provider is active on the model.
## Configure feet and hips
Character IK casts from each foot and optional toe toward the character's gravity direction. When the character is grounded and using vertical collision detection, it raises and rotates a foot that would pass below the detected surface and lowers the hips when the two feet need different heights.
Use these controls for the ground solve:
| Setting | Released Version 3 default | Choose it by result |
| --- | --- | --- |
| **Layer Mask** | All layers except common ignored, character, overlay, water, UI, and visual-effect layers | Include the real ground colliders. Exclude invisible navigation ramps or helper colliders when the feet should meet visible stair treads instead. |
| **Hips Position Adjustment Speed** | `4` | Increase it when the pelvis lags behind changing ground height; reduce it when the pelvis correction looks abrupt. |
| **Hips Position Offset** | `0` | Apply a small model-specific vertical correction after the automatic hips adjustment. |
| **Foot Offset Adjustment** | `0.005` | Increase it slightly when the sole intersects the surface; avoid using a large value to hide an incorrect Avatar or collider setup. |
| **Foot Weight Active Adjustment Speed** | `10` | Controls the blend into ground or explicit foot IK. A value of `0` disables the resulting foot weight in the released implementation. |
| **Foot Weight Inactive Adjustment Speed** | `2` | Controls the blend back to the animated pose when a foot no longer needs correction. |
| **Override Foot IK Weight** | `-1` | Keep `-1` for automatic grounded behavior, use `0` to turn foot weighting off, or use a positive weight for an intentional override. |
An invisible slope collider can support the character capsule while visible step colliders support the feet. Exclude the slope helper from **Layer Mask** so the IK rays reach the steps.
## Configure look direction
The attached camera or AI `ILookSource` supplies the normal look direction. **Look At Offset** moves the body-and-arm target relative to that direction without rotating the camera, while the body, head, eyes, and clamp weights decide how much of the pose follows it.
Start from the released defaults and tune one decision at a time:
- **Look At Body Weight** defaults to `0.025`; keep it low for subtle torso participation.
- **Look At Head Weight** defaults to `0.2`; increase it when the head should lead the look pose.
- **Look At Clamp Weight** defaults to `0.35`; higher values restrict how far Unity's look-at solve can turn.
- **Look At Adjustment Speed** defaults to `0.5`, and **Look At Weight Adjustment Speed** defaults to `0.2`; use them to avoid a snap when the target changes.
- **Active Look At State Name** defaults to `LookAt`. An explicit target supplied by the [Look At ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/detect-object-ability-base/look-at/) activates that State while the target is active.
The released Version 3 **Look At Eyes Weight** field is not applied correctly: both the immediate and blended eye weight use **Look At Head Weight** in the current source. Treat the eyes as following the head weight, or use a corrected/custom IK implementation when independent eye weighting is required.
Enable **Debug Draw Look Ray** to draw the current target direction in green in the Scene view while testing. It is an editor-only diagnostic.
## Configure arms, hands, and items
**Upper Arm Weight** controls how strongly the dominant upper arm follows vertical aim. **Left Hand Weight**, **Right Hand Weight**, **Left Elbow Weight**, and **Right Elbow Weight** control each humanoid goal independently; all default to `1`. The corresponding adjustment speeds blend between the animated and IK poses.
For a two-handed item:
1. Open the item's [Third Person Perspective Item](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/third-person-perspective/) and expand **IK**.
2. Create a child Transform on the visible item at the non-dominant hand's intended grip.
3. Assign it to **Non Dominant Hand IK Target**.
4. Optionally create an elbow guide and assign **Non Dominant Hand IK Target Hint**.
5. Equip, aim, use, reload, and unequip the item. The active model's Character IK receives and clears these targets with the item.
6. If a reload animation must release the grip, use a [State preset](https://opsive.com/support/documentation/ultimate-character-controller/state-system/presets/) to reduce the relevant hand and elbow weights during that state, then restore them afterward.
Aim and Use also tell Character IK when the hands should rotate and position toward the look direction. An [Interact](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/detect-object-ability-base/interact/) target can supply a temporary hand, elbow, foot, or knee goal through **Ability IK Target**; ability targets take priority over item targets while active.
## How it runs
After the Animator evaluates a layer with **IK Pass**, Unity calls `OnAnimatorIK`. Character IK uses the base-layer callback for foot placement, hips preparation, and body look-at, then uses the upper-body callback for hand rotation, upper-arm rotation, hand position, and elbow hints. If an item or ability requires a second pass, the hands are positioned again on another IK-enabled layer. The hips correction is finalized in Late Update.
The component listens for the attached look source, item equip and unequip, Aim and Use, secondary item forces, Animator snaps, death, and respawn. It disables itself on death and restores its previous enabled state on respawn. Explicit look targets activate **Active Look At State Name**, and State presets can override the component's public properties.
Character IK runs locally on each animated model. In a multiplayer build, remote models are treated as third person for the first-person-specific hand condition; the component does not itself transmit custom look positions or ability IK targets. Synchronize the gameplay target or action that produces the pose. Inspector settings persist with the scene or prefab, but a temporary runtime target or interpolation is not a save record; restore the owning ability, item, or interaction after loading when that pose must continue.
## Verify in Play Mode
1. Confirm **Character IK** enables after the player camera or AI look source attaches and the Console reports no Humanoid, head, hand, or foot errors.
2. Stand on flat ground, a slope, and stairs. Both soles should meet the visible surface without a sudden pelvis drop, leg stretch, or foot intersection.
3. Toggle **Debug Draw Look Ray**, move the look source above, below, and across the character, and confirm the green ray agrees with the intended target.
4. Compare **Look At Offset**, body weight, head weight, and clamp weight one at a time. The body should follow without changing the camera direction or twisting past the desired limit.
5. Equip a two-handed item. The non-dominant hand should settle on its target and the elbow should bend toward its hint without a visible pop.
6. Start and stop Aim and Use at several pitch angles. The upper arm and hands should blend toward the look direction, then return to the authored pose.
7. Reload and unequip. Any State-based hand release should activate for the intended interval, and the target must clear when the item is no longer active.
8. Trigger a Look At or Interact target. Confirm the explicit target activates, the correct limb reaches it over the configured duration, and the pose returns cleanly afterward.
9. Switch every supported perspective and character model, then test death and respawn. Each active humanoid model should have one working IK provider; separate first-person arms should remain animation-driven.
10. In multiplayer, compare the local, spectator, and remote view. Replicated gameplay intent should produce an equivalent third-person pose without attempting to network final bone transforms.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| Character IK stays disabled. | The model may be Generic, missing required humanoid bones, or have no attached `ILookSource`. | Repair the Humanoid Avatar and bone mapping, then attach the player camera or an AI look source. Do not add built-in Character IK to Generic first-person arms. |
| No IK changes are visible. | The Animator layer may not have **IK Pass** enabled, or the layer indices may not match. | Enable IK Pass and set **Base Layer Index** and **Upper Body Layer Index** to the actual Animator layer indices. |
| Feet intersect or float above the ground. | Check grounded state, vertical collision detection, **Layer Mask**, **Foot Offset Adjustment**, and **Override Foot IK Weight**. | Restore automatic weight `-1`, include the visible ground, exclude helper colliders, and tune only a small foot offset. |
| Feet follow an invisible stair ramp. | The helper ramp is included in **Layer Mask**. | Move it to an excluded layer or remove that layer from the Character IK mask while retaining the visible step colliders. |
| The non-dominant hand misses the item. | The active Third Person Perspective Item may have no target, the target may not be a child of the visible item, or the active model may lack Character IK. | Assign **Non Dominant Hand IK Target** and its optional hint on the active item, then verify the active model's IK provider. |
| The hand remains locked during reload. | The item target is still active and the relevant hand weight remains `1`. | Use the Reload State to reduce the specific hand and elbow weights, then restore them after the animation. |
| First-person arms do not respond to Character IK. | Separate arms are normally Generic and are outside Unity humanoid IK. | Position them through their animation, First Person Perspective Item, and springs; keep Character IK on the humanoid full-body model. |
| The body or hands jitter or solve twice. | Character IK, Final IK Bridge, or another custom IK owner may be active together. | Keep one `CharacterIKBase` provider on each active model and remove the competing solver route. |
| **Look At Eyes Weight** has no independent effect. | Released Version 3 reads **Look At Head Weight** for the eye weight. | Tune the head value as the shared result or use a corrected/custom IK implementation. |
| A remote character looks or reaches toward the wrong target. | The explicit target or owning gameplay action may not be synchronized. | Replicate the target/action and let each client solve the pose locally; do not rely on Character IK to send it. |
| A loaded game loses a temporary reach or look pose. | Runtime IK targets and interpolation are not standalone save data. | Restore the item, ability, interaction, and target state after loading. |
## Built-in IK or Final IK
Use **Character IK** when the model is a valid Unity Humanoid and its feet, look direction, item grip, and ability targets fit the built-in workflow. It ships with UCC and is added by the Character Manager's **Unity IK** option.
Use the [Final IK integration](https://opsive.com/support/documentation/ultimate-character-controller/integrations/final-ik/) when a supported RootMotion solver must own the final pose. Replace Character IK with **Final IK Bridge** on the animated model and configure the required RootMotion components; the bridge does not automatically make every Generic rig compatible and should not run beside Character IK.
## Related tasks
- [Character Creation](https://opsive.com/support/documentation/ultimate-character-controller/character/character-creation/)
- [Generic Character](https://opsive.com/support/documentation/ultimate-character-controller/character/generic-character/)
- [Animator Controller](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/animator-controller/)
- [First Person Arms](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/first-person-arms/)
- [Third Person Perspective Item](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/third-person-perspective/)
- [Aim](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/aim/)
- [Look At](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/detect-object-ability-base/look-at/)
- [Interact](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/detect-object-ability-base/interact/)
- [Model Switch](https://opsive.com/support/documentation/ultimate-character-controller/character/model-switch/)
- [State System](https://opsive.com/support/documentation/ultimate-character-controller/state-system/)
- [Final IK](https://opsive.com/support/documentation/ultimate-character-controller/integrations/final-ik/)
## Developer reference
`CharacterIK` derives from `CharacterIKBase`, reports `UseOnAnimatorIK` as `true`, and exposes `SetLookAtPosition`, `GetDefaultLookAtPosition`, `SetItemIKTargets`, `SetAbilityIKTarget`, and `UpdateSolvers`. `OnUpdateIKPosition` and `OnUpdateIKRotation` delegates can adjust a final limb result before it is sent to Unity's Animator IK API.
`CharacterIKBase.IKGoal` includes both hands, elbows, feet, and knees. Ability targets override item hand targets while their interpolation is active. The built-in Interact ability uses **Ability IK Target** values for the goal, delay, interpolation duration, and active duration; the component defaults are `0`, `0.2`, and `1` seconds respectively.
Two released Version 3 API limitations are important:
- **Look At Eyes Weight** is serialized and exposed, but `LookAtTarget` uses **Look At Head Weight** when setting the eye weight.
- The public `RightHandRotationSpring` getter and setter route to the right-hand position spring. The serialized **Right Hand Rotation Spring** Inspector field is correct; configure it in the Inspector and avoid that public property in released Version 3 code or State presets.
---
# Objects
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/objects/)
The object systems provide reusable prefabs and components for pickups, projectiles, explosions, magic effects, damage rules, and detected scene targets. Start here when gameplay needs an object outside the character, then follow the route for the behavior that object must perform.
## Choose the object behavior
| Goal | Start with | What it covers |
| --- | --- | --- |
| Build a supported gameplay prefab | [Object Manager](https://opsive.com/support/documentation/ultimate-character-controller/objects/objects/) | Creates a configured starting prefab for pickups, projectiles, shells, grenades, explosions, magic projectiles, particles, and several weapon effects. |
| Give the character health or inventory objects | [Object Pickup](https://opsive.com/support/documentation/ultimate-character-controller/objects/object-pickup/) | Explains the shared pickup behavior and routes to Health Pickup and Item Pickup. |
| Launch, throw, bounce, or preview an object's path | [Trajectory Object](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/) | Provides the shared trajectory simulation and routes to Projectile, Grenade, Magic Projectile, and Shell. |
| Apply area damage and force | [Explosions](https://opsive.com/support/documentation/ultimate-character-controller/objects/explosions/) | Configures a radius-based effect that can damage targets and push supported physics objects. |
| Turn particle collisions into magic impacts | [Magic Particle](https://opsive.com/support/documentation/ultimate-character-controller/objects/magic-particle/) | Connects Particle System collision messages to the Magic Action that cast the effect. |
| Let an ability recognize a particular scene target | [Object Identifier](https://opsive.com/support/documentation/ultimate-character-controller/objects/object-identifier/) | Assigns a numeric ID that Detect Object Ability Base abilities can use as a filter. |
| Change how damage is calculated | [Damage Processor](https://opsive.com/support/documentation/ultimate-character-controller/objects/damage-processor/) | Defines the rule between a damage source and target, including integration with an external stats or modifier system. |
These pages describe different responsibilities. For example, a grenade can use a Trajectory Object for flight, spawn an Explosion at the end, and let a Damage Processor modify the resulting damage.
## Build a supported prefab
Use the Object Manager when its **Object Type** list contains the result you need:
1. Open **Tools > Opsive > Ultimate Character Controller > Object Manager**.
2. Enter a **Name** and choose an **Object Type**.
3. Assign a **GameObject** when the selected type requests one. Use the model or visual object that should become the prefab, not an already configured Character Item for an Item Pickup.
4. For **Magic Projectile** or **Particle**, enable **Magic Particle Collisions** only when particle collisions should perform Magic Action impacts.
5. Select **Build Object** and save the prefab under the project's `Assets` folder.
6. Open the new prefab and complete the feature-specific configuration using the route in the table above.
7. Assign the prefab to the item action, spawner, scene object, or other system that will create or enable it.
The Object Manager adds the common components, colliders, layers, and starting values for the selected type. It does not choose project-specific item definitions, effects, damage rules, layer masks, or references for you.
## Common scenarios
### A health or item pickup
Choose **Health Pickup** or **Item Pickup** in Object Manager, then follow [Object Pickup](https://opsive.com/support/documentation/ultimate-character-controller/objects/object-pickup/). Decide whether pickup happens on trigger entry, what the character receives, whether the object respawns, and which message or audio confirms collection.
### A projectile or throwable object
Choose **Projectile**, **Grenade**, or **Shell**, then follow [Trajectory Object](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/) and its concrete child page. Match the collider and impact layers to the physical object, and connect the resulting prefab to the appropriate item action. A visible trajectory preview is optional and uses the same motion settings as the launched object.
### A projectile that explodes
Treat flight and detonation as separate responsibilities. Configure the projectile or grenade through [Trajectory Object](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/), create the area effect through [Explosions](https://opsive.com/support/documentation/ultimate-character-controller/objects/explosions/), and assign the Explosion prefab where the launched object handles destruction or impact.
### A magic particle that reacts on contact
Use [Magic Particle](https://opsive.com/support/documentation/ultimate-character-controller/objects/magic-particle/) when individual Particle System collisions should invoke the casting Magic Action's impact. The Particle System must have its Collision module and **Send Collision Messages** enabled, and the particle must be initialized by the Magic Action that spawned it.
### A target that only certain abilities detect
Add [Object Identifier](https://opsive.com/support/documentation/ultimate-character-controller/objects/object-identifier/) to the scene target and give it an **ID**. Configure the Detect Object Ability Base ability with the same **Object ID** when it should ignore otherwise detectable objects with different IDs.
### Project-specific damage rules
Use [Damage Processor](https://opsive.com/support/documentation/ultimate-character-controller/objects/damage-processor/) when the normal damage amount must pass through armor, attributes, difficulty, teams, or another modifier system. Keep movement, collision, and visual effects on their normal components; the processor owns only the damage calculation and delivery rule.
## Verify in Play Mode
1. Trigger the system that creates or enables the prefab rather than dragging an unconnected prefab into an unrelated scene test.
2. Confirm that the expected trigger or collision occurs on the intended layers.
3. Watch for one concrete result: the pickup changes the character, the trajectory follows its configured path, the explosion affects an in-range target, the magic particle performs its impact, or the ability accepts only the matching object ID.
4. Reuse or respawn the object when that is part of the scenario and confirm that it initializes correctly again.
5. Check the Console. Missing component references, invalid particle collision setup, or an unassigned feature prefab should be corrected before tuning values.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| **Build Object** is disabled. | **Name** is blank, or the selected type requires a **GameObject** that has not been assigned. For **Item Pickup**, the source object may already contain a Character Item. | Enter a name, assign the required visual GameObject, and use an item model rather than an already built Character Item. |
| The prefab was created but never appears in gameplay. | The Object Manager builds the asset but does not assign it to an item action, spawner, or scene reference. | Assign the generated prefab to the system that should create it, then test that complete workflow. |
| A collision produces no pickup, impact, or explosion. | The required trigger, Rigidbody, layer mask, or Particle System collision message is missing or excludes the target. | Follow the concrete feature page and verify its collider and layer requirements before changing effect values. |
| The object moves correctly but applies the wrong result. | Flight, impact, and damage are configured by separate systems. | Keep Trajectory Object responsible for motion, the impact or Explosion responsible for the hit effect, and Damage Processor responsible for modifying damage. |
| An ability detects the wrong scene object. | Its layer mask is broad and its **Object ID** remains `-1`, which disables ID filtering, or the value does not match the target's Object Identifier. | Set a deliberate Object Identifier **ID** and use the same **Object ID** on the detecting ability. |
## Related pages
- [Items & Inventory](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/)
- [Health](https://opsive.com/support/documentation/ultimate-character-controller/attributes/health/)
- [Moving Platforms](https://opsive.com/support/documentation/ultimate-character-controller/moving-platforms/)
## Developer orientation
The Object Manager is editor-only prefab scaffolding. Runtime behavior comes from the generated components and the system that initializes, spawns, or enables the prefab.
The main runtime types are divided by responsibility:
- `TrajectoryObject` implements `IForceObject`, `IDamageSource`, and `ISmoothedObject` for simulated flight, forces, impacts, and trajectory previews.
- `Explosion` implements `IDamageSource` and sends its configured impact data and actions to objects inside its radius.
- `ObjectPickup` is the abstract `IObjectPickup` base used by concrete health and item pickups.
- `MagicParticle` receives Particle System collision callbacks after a `MagicAction` initializes it.
- `ObjectIdentifier` exposes a `uint ID` for ability and object-reference matching.
- `DamageProcessor` is a ScriptableObject that processes `DamageData` for an `IDamageTarget`; `DamageProcessorModule` provides a character-level assignment point.
---
# Explosions
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/objects/explosions/)
Use the **Explosion** component to damage and push nearby objects from one point, such as when a grenade detonates or a destructible barrel reaches zero Health.
## Create an explosion prefab
1. Open **Tools > Opsive > Ultimate Character Controller > Object Manager**.
2. Enter a **Name**, select **Explosion** for **Object Type**, and select **Build Object**. An Explosion does not require a source GameObject in the manager.
3. Save the generated prefab. The Object Manager adds **Particle System** and **Explosion** components.
4. Configure the Particle System's material, duration, and playback so the visual starts when the prefab is activated. The Explosion component does not control particles directly.
5. In **Explosion**, set **Radius** to the gameplay reach and configure **Impact Damage Data** for the targets, damage, and force.
6. Review **Impact Actions**. The generated component starts with **Simple Damage**, **Spawn Surface Effect**, and **Impact Event**.
7. Enable **Line Of Sight** when solid cover should protect targets, then make sure the cover layers are also included in **Impact Damage Data > Layer Mask**.
8. Add clips to **Explosion Audio Clip Set** when the detonation needs sound. UCC's shared audio system obtains the audio source at runtime.
9. Choose one owner for detonation: **Explode On Enable**, a grenade or projectile, a Health death object, or your own call to `Explode`. Do not enable two of these paths for the same spawn.
Before testing, the saved prefab should contain one Explosion component, its visual effect, an intentional detonation path, and a **Lifespan** long enough for the particles and audio to finish.
## Choose how the explosion starts
### Grenade or projectile
Assign the explosion prefab to the grenade or projectile's **Spawned Objects On Destruction** list. Keep **Explode On Enable** disabled: the Version 3 projectile code spawns the prefab and then calls `Explode` with the projectile's impact data and damage-source ownership. Enabling the option would detonate the same spawned object twice.
Use this path when the collision, timer, or trajectory object should decide when and where the explosion occurs. Follow [Grenade](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/grenade/) for the trajectory setup.
### Destructible barrel
Add **Attribute Manager** and **Health** to the barrel, then place the explosion prefab in **Health > Death > Spawned Objects On Death**. Keep **Explode On Enable** disabled here as well. Health explicitly calls `Explode` after it spawns a death object.
This path attributes the explosion to the barrel GameObject. If a chain reaction or score system must retain the original attacker as an `IDamageSource`, invoke the owner/source overload from the system that owns that attribution.
### Direct or pooled effect
Enable **Explode On Enable** only when activating the explosion prefab is the complete trigger. Each enable performs the overlap query, runs the actions, plays audio, and schedules the object for pooled destruction after **Lifespan**. A script can instead leave the option disabled and call one of the public `Explode` overloads.
## Tune reach, damage, and force
The outer **Radius** controls target detection and distance strength. **Impact Damage Data > Impact Radius** is separate data passed to damage and force processing; it does not expand the detection sphere.
| Setting | Version 3 default | Use it for |
| --- | --- | --- |
| **Explode On Enable** | Disabled | Detonate whenever this pooled object becomes active. Leave it disabled for projectile and Health death-object workflows. |
| **Radius** | `5` | Detect colliders and calculate a strength from the explosion center to each collider's closest point. |
| **Impact Damage Data > Damage Amount** | `10` | Supply the base damage used by the default **Simple Damage** action. |
| **Impact Damage Data > Impact Force** | `2` | Supply the base force. Force is multiplied by distance strength. |
| **Impact Damage Data > Impact Force Frames** | `1` | Spread force handled by an `IForceObject`, such as a character, over this many frames. |
| **Impact Damage Data > Impact Radius** | `0` | Mark radius damage and select downstream radial-force behavior. This is not the Explosion detection radius. |
| **Impact Damage Data > Layer Mask** | All except Ignore Raycast, Water, SubCharacter, Overlay, and Visual Effect | Choose affected colliders and, when **Line Of Sight** is enabled, which colliders can block the test. Trigger colliders are always ignored. |
| **Impact Damage Data > Damage Processor** | None | Supply custom damage filtering or modification before a damage target receives it. |
| **Line Of Sight** | Disabled | Skip a target when an included-layer collider blocks the route from the explosion. |
| **Lifespan** | `3` seconds | Return or destroy the explosion object after detonation. |
| **Max Collision Count** | `100` | Size the non-allocating collider buffer created in `Awake`. Multiple colliders can fill this buffer even though duplicate objects are filtered later. |
| **Explosion Audio Clip Set** | Empty | Play one configured explosion clip once per detonation. |
Explosion always calculates a distance strength, which approaches one percent at the radius edge, and **Simple Damage** multiplies **Impact Force** by that strength before applying its direction. Damage does **not** fall off by default. To scale damage too, expand **Impact Actions > Simple Damage** and enable **Scale Damage By Impact Strength**.
Explosion Version 3.2.0 has no **Upward Modifier** field. The direction runs outward from the explosion center. Add a custom impact action or apply a separate force when an upward lift is part of the design.
The **Impact State Name**, **Impact State Disable Timer**, and **Surface Impact** values in Impact Damage Data are only consumed by actions that use them. The default group does not contain **State Impact**, so add that action if an explosion should activate a state. Configure and test **Spawn Surface Effect** when a per-target surface response is required; use the prefab's Particle System for the main blast visual.
## How it runs
When `Explode` runs, the component:
1. Searches **Radius** with a non-allocating overlap sphere using the Impact Damage Data layer mask and ignoring triggers.
2. Filters duplicate GameObjects and duplicate parent force objects so a multi-collider target is not processed repeatedly.
3. Applies the optional line-of-sight test.
4. Finds the collider's closest point and calculates outward direction and distance strength.
5. Runs every enabled **Impact Action** for that target. By default, **Simple Damage** damages an `IDamageTarget` or pushes an `IForceObject` or non-kinematic Rigidbody, **Spawn Surface Effect** requests a Surface System response, and **Impact Event** notifies the source and target.
6. Plays **Explosion Audio Clip Set** once, then returns or destroys the explosion object through the object pool after **Lifespan**.
For objects with [Health](https://opsive.com/support/documentation/ultimate-character-controller/attributes/health/), damage consumes the configured Shield attribute before Health. That attribute shield is separate from an equipped item's **Shield Action**: **Absorb Explosions** is disabled by default on Shield Action, so enable it when that item should intercept explosion damage.
## Verify in Play Mode
1. Place one target close to the explosion, one near the radius edge, one outside it, and one behind included-layer cover.
2. Give damage targets Attribute Manager and Health, and give physics-only targets a non-kinematic Rigidbody.
3. Detonate once. Confirm the visual and audio play once and the explosion object leaves the scene after **Lifespan**.
4. Confirm the two in-range targets receive outward force and the outside target is unchanged.
5. With **Scale Damage By Impact Strength** disabled, confirm both damage targets receive the base damage. Enable it and confirm the edge target then receives less damage.
6. Enable **Line Of Sight** and confirm the covered target is protected. Check that both the target and cover layers are in **Layer Mask**.
7. Test a target with several colliders and a crowded scene. Each logical object should react once, and the Console should not report that **Max Collision Count** was reached.
8. Test the actual trigger path: grenade collision or timer, barrel death, direct activation, or script call. Confirm only one detonation occurs.
9. If the project uses multiplayer or saving, test through that integration's authority and restoration flow rather than assuming the Explosion component synchronizes itself.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| Nothing is damaged or pushed. | The target may be outside **Radius**, excluded by **Layer Mask**, represented only by a trigger, blocked by **Line Of Sight**, or missing Health/Rigidbody/`IForceObject`. | Include a non-trigger collider on an affected layer and add the receiver required for damage or force. |
| Edge targets take the same damage as close targets. | **Simple Damage > Scale Damage By Impact Strength** is disabled by default. | Enable it when damage, rather than only force, should fall off with distance. |
| A barrel or grenade detonates twice. | **Explode On Enable** may be enabled while Health or ProjectileBase also calls `Explode`. | Disable **Explode On Enable** and let the owning gameplay system make the call. |
| Cover does not block the explosion. | **Line Of Sight** may be disabled, or the cover layer may be absent from the same Impact Damage Data layer mask used by the test. | Enable the option and include both blockers and targets in **Layer Mask**. |
| Only some crowded targets react. | The overlap query may have filled **Max Collision Count**; the value counts colliders before duplicate targets are removed. | Increase it on the prefab before runtime and test again. Changing it after `Awake` does not resize the current buffer. |
| A Rigidbody receives no useful force. | It may be kinematic, use an excluded layer, or have zero **Impact Force**. **Impact Radius** may also be confused with the outer Radius. | Use a non-kinematic Rigidbody or `IForceObject`, set Impact Force, and use the outer **Radius** for detection. |
| An equipped shield does not block the blast. | **Shield Action > Absorb Explosions** defaults to disabled. | Enable it and verify the shield collider is the collider found by the explosion. |
| Particles or audio are cut off. | **Lifespan** may be shorter than the configured effect. | Increase Lifespan or shorten the Particle System and Audio Clip Set playback. |
| A surface effect appears at the wrong place or cannot identify the surface. | Version 3.2.0 builds explosion targets from an overlap collider, not a full raycast hit. | Keep the main blast on the prefab and use a tested custom impact action when exact per-surface placement is required. |
| Multiplayer clients produce duplicate or different explosions. | Explosion has no built-in network spawn, authority, or replication logic. | Let the multiplayer integration's authority spawn and detonate the effect, then replicate the resulting gameplay state as required. |
## Related pages
- [Object Manager](https://opsive.com/support/documentation/ultimate-character-controller/objects/objects/) creates the starting explosion prefab.
- [Grenade](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/grenade/) configures a throwable object that spawns an explosion on destruction.
- [Trajectory Object](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/) explains collision, timing, and spawned destruction objects shared by projectiles.
- [Health](https://opsive.com/support/documentation/ultimate-character-controller/attributes/health/) configures damage, Shield attributes, death objects, and barrel-style destruction.
- [Damage Processor](https://opsive.com/support/documentation/ultimate-character-controller/objects/damage-processor/) customizes how structured damage reaches a target.
- [Surface System](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/) maps impacts to effects.
- [Audio](https://opsive.com/support/documentation/ultimate-character-controller/audio/) explains Audio Clip Sets and shared audio playback.
- [Events](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/) explains how to register and unregister UCC event listeners.
## Developer reference
### Detonation API and ownership
`Explosion` implements `IDamageSource`. Use an owner when damage attribution matters, and forward an existing `IDamageSource` when the explosion belongs to another attack:
```csharp
using UnityEngine;
using Opsive.UltimateCharacterController.Objects;
using Opsive.UltimateCharacterController.Traits.Damage;
public class ExplosionTrigger : MonoBehaviour
{
[SerializeField] private Explosion m_Explosion;
public void Detonate(GameObject owner, IDamageSource ownerSource)
{
m_Explosion.Explode(m_Explosion.ImpactDamageData, owner, ownerSource);
}
}
```
The public overloads are `Explode()`, `Explode(GameObject owner)`, `Explode(float damageAmount, float impactForce, int impactForceFrames, GameObject owner, IDamageSource ownerSource = null)`, and the virtual `Explode(IImpactDamageData impactDamageData, GameObject owner, IDamageSource ownerSource = null)`. Useful public properties include `ExplodeOnEnable`, `Radius`, `ImpactDamageData`, `ImpactActionGroup`, `LineOfSight`, `Lifespan`, and `ExplosionAudioClipSet`. **Max Collision Count** is serialized but has no public property in the inspected Version 3.2.0 source.
The default **Impact Event** action sends `OnObjectImpact` with an `ImpactCallbackContext` to the explosion source and the impacted target. Damage applied through Health then produces the normal Health damage and death events.
### Version 3.2.0 source boundaries
The inspected Version 3.2.0 implementation uses the `LayerMask` from an `impactDamageData` argument for target detection, but assigns the component's serialized **Impact Damage Data** to the default action context. A projectile-supplied or temporary data object therefore does not necessarily replace the damage and force read by context-driven default actions. Keep the explosion prefab's data aligned with the caller and recheck this behavior after upgrading.
The default **Spawn Surface Effect** receives overlap-derived collision data without a populated `RaycastHit`. Surface selection and placement that require raycast details need a custom action or an explicitly tested fallback.
Explosion contains no save serialization or multiplayer replication. Its scheduled pooled destruction is local runtime state. Persist the source object's durable state, such as barrel Health, and let the chosen multiplayer integration own network spawning, authority, damage, and despawning.
---
# Damage Processor
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/objects/damage-processor/)
A Damage Processor changes or rejects damage between a source and an `IDamageTarget`. Use one when a firearm, melee weapon, projectile, or explosion must account for armor, resistance, difficulty, teams, or an external stat system before the target's Health applies the result.
The built-in `DamageProcessor.Default` does not change the data: it calls `target.Damage(damageData)`. Ultimate Character Controller Version 3 does not include separate armor, resistance, or team processor types. Those rules belong in a project-specific `DamageProcessor` subclass.
## Choose where the processor applies
| Scope | Configure | Best for |
| --- | --- | --- |
| Every compatible hit from one character | Add **Damage Processor Module** to the attacking character and assign **Default Damage Processor**. | One team, difficulty, or stat rule shared by that character's weapons and nested damage sources. |
| One Impact Action | Assign **Damage Processor** on **Simple Damage**. | A weapon or attack that needs a different rule from the character default. |
| Projectile or Explosion context | Assign **Damage Processor** in the source's **Impact Damage Data**, then enable **Use Context Data** on **Simple Damage**. | A processor that should travel with the damage amount and force supplied by the source. |
| Normal UCC damage | Leave every processor field empty. | The runtime-created default processor passes the data directly to the target. |
The module belongs on the source character, not on the object receiving damage.
Assign an attack-specific asset directly on its **Simple Damage** Impact Action when that attack must override the character rule.
There is no registration list or processor stack. Exactly one processor is selected for a **Simple Damage** invocation, in this order:
1. Start with the **Damage Processor** on **Simple Damage**.
2. If **Use Context Data** is enabled and `ImpactDamageData` exists, use its processor instead. A blank context value also replaces the local value, so selection continues to the fallbacks.
3. If the selected value is empty and the source character has **Damage Processor Module**, use **Default Damage Processor** from that component.
4. If it is still empty, use `DamageProcessor.Default`.
An explicitly selected processor still passes through `DamageProcessorModule.ProcessDamage`, but it is not replaced by the module default.
## Configure the damage source
After the project contains a custom processor class:
1. Create its ScriptableObject asset from the **Assets > Create** menu path declared by that class.
2. Decide whether the rule belongs to an attacking character, one **Simple Damage** action, or the source's **Impact Damage Data**.
3. Assign the asset in only the intended location. When using context data, verify **Use Context Data** on **Simple Damage**.
4. Confirm the target has **Health**, **Character Health**, or another component that implements `IDamageTarget`.
5. Test the same known damage amount with the processor assigned and unassigned before adding more rules.
These released-Version-3 defaults are useful when checking the Inspector:
| Location | Field | Default |
| --- | --- | --- |
| Damage Processor Module | **Default Damage Processor** | None |
| Simple Damage | **Use Context Data** | Off |
| Simple Damage | **Damage Processor** | None |
| Simple Damage | **Damage Amount** | `10` |
| Simple Damage | **Impact Force** | `2` |
| Simple Damage | **Impact Force Frames** | `15` |
| Simple Damage | **Impact Radius** | `0` |
| Simple Damage | **Scale Damage By Impact Strength** | Off |
| Impact Damage Data | **Damage Processor** | None |
## How damage runs
A standard weapon or object impact follows this path:
1. The source creates an `ImpactCallbackContext`. Its `ImpactCollisionData` identifies the hit, source, target, direction, strength, and colliders; optional `ImpactDamageData` carries configured damage, force, radius, and processor values.
2. The ordered Impact Action Group reaches **Simple Damage**. That action reads either its local values or the context values and optionally scales damage by **Impact Strength**.
3. A struck item shield can absorb damage through `ShieldCollider` before a processor runs.
4. **Simple Damage** resolves an `IDamageTarget`, builds a temporary `DamageData`, and selects one processor using the fallback order above.
5. The processor changes the request, rejects it, or calls `target.Damage(damageData)`. The default processor calls the target once without changing the data.
6. The built-in Health target rejects invalid requests, applies a qualifying hitbox multiplier, consumes its Shield attribute, consumes Health, applies force, sends damage events, and invokes death behavior when neither value remains above its minimum.
This order matters. A held shield acts before the processor; Health hitbox multipliers and the Health **Shield Attribute** act after it. A custom processor that returns without calling `target.Damage` suppresses Health changes, force, Health events, and death. A processor should normally call the target no more than once.
## Choose the rule by outcome
### Armor or resistance
Read the target's external armor or resistance value, modify `DamageData.Amount`, clamp the result to the range your game supports, then pass it to the target. Do not duplicate Health's hitbox or Shield Attribute logic unless the custom design deliberately replaces those systems.
For a firearm, compare one unarmored and one armored target with the same shot. For an Iron Sword, also strike every configured Health hitbox so the processor rule and hitbox multiplier can be verified separately.
### Teams and friendly fire
Use `DamageData.DamageSource` to identify the source and the processor's `target` argument to identify the receiver. `IDamageSource` can form an owner chain such as character -> item action -> projectile -> explosion; `DamageSourceUtility.GetRootOwner()` returns the outer owner for a normal, non-null chain.
Ask the project's team or faction system whether the root source owner may damage `target.Owner`. Return without calling the target when friendly fire is disabled. UCC's core Version 3 package does not provide a team database or a built-in team comparison.
### Projectiles and explosions
A projectile can carry its **Impact Damage Data** into the hit context. Keep **Use Context Data** enabled on the receiving **Simple Damage** action when its amount, force, radius, and processor should come from the projectile.
For an Explosion, assign the processor on the Explosion component's serialized **Impact Damage Data**. Enable **Scale Damage By Impact Strength** on **Simple Damage** when damage, rather than only force, should use the Explosion's distance-based impact strength.
In released Version 3, `Explosion.Explode(IImpactDamageData, ...)` uses the supplied data for its overlap layer mask but sends the component's serialized Impact Damage Data to the Impact Action callback. A processor or amount supplied only through that runtime argument therefore does not reach **Simple Damage**. Configure the component data, or use project code that constructs and invokes the intended impact context.
## Editor checkpoint
Before entering Play Mode, confirm that:
- the custom ScriptableObject asset is assigned at the intended scope;
- **Use Context Data** agrees with the location that owns the processor and damage values;
- the attacking character, rather than the receiver, owns **Damage Processor Module** when a character-wide fallback is required;
- the receiver resolves to one `IDamageTarget` and has valid Health/Shield attributes when using Health;
- the processor is stateless or stores per-character state in another component or system, because one ScriptableObject asset can serve many attackers at once;
- a custom impact source component implements `IDamageSource` and supplies the intended owner chain; and
- an Explosion that needs a custom processor has it in the component's serialized **Impact Damage Data**.
## Verify in Play Mode
Use one target with known Health, one with a Shield attribute, one armored target, and two characters on the same team.
| Test | Expected result |
| --- | --- |
| Fire the weapon with no processor assigned | The default processor passes the configured amount to Health. |
| Assign a character-level multiplier processor | Compatible firearm and melee hits from that character use the changed amount. |
| Assign a different processor on one Simple Damage action | That action uses its explicit processor; the character default still applies to other unassigned actions. |
| Enable context data and assign a projectile processor | The projectile's context processor wins over the local Simple Damage field. |
| Hit an armored and unarmored target | Only the armored target applies the external resistance rule, followed by its normal Health hitbox and Shield processing. |
| Hit an ally with friendly fire disabled | Health, force, Health damage events, and death do not run for the rejected request. |
| Hit a target with a held shield and a Health Shield attribute | The held shield adjusts the amount before the processor; the Health Shield attribute consumes the processed remainder. |
| Detonate an Explosion at two distances | Force follows impact strength; damage follows it only when **Scale Damage By Impact Strength** is enabled. Both hits use the serialized Explosion processor. |
| Apply lethal processed damage | Health sends its damage events, then death behavior and `OnDeath` run once. |
Temporarily log the source root, target owner, incoming amount, outgoing amount, and chosen processor while validating an external stat or team integration. Remove per-hit logging after the rule is proven.
## Troubleshooting and released-Version-3 limitations
| Symptom | Check | Fix |
| --- | --- | --- |
| A processor assigned on Simple Damage never runs | **Use Context Data** may be enabled while a context exists with a different or blank processor. | Assign the processor in **Impact Damage Data**, or disable context use so the local field is read. |
| The character default is ignored for one weapon | That Simple Damage action or its context may select an explicit processor. | Clear the explicit value when the character module should be the fallback. |
| The processor changes `Amount`, but Health does not change | The processor may not call the target, or Health may reject zero damage, invincibility, an already-dead target, or spawn grace. | Call `target.Damage(damageData)` exactly once for an accepted request and verify the Health state. |
| A custom team rule cannot find its target through `DamageData.DamageTarget` | Built-in `DamageData.SetDamage` overloads do not assign that property, and `DamageData.Copy` does not copy it. | Use the `IDamageTarget target` argument supplied to `DamageProcessor.Process`. Explicitly populate the property only in a fully owned custom pipeline. |
| `DamageData.UserData` contains an unexpected object | Built-in `SetDamage` overloads do not initialize or clear **User Data**, and standard Simple Damage uses pooled `DamageData`. | Set or clear `UserData` for every custom request that uses it. Never treat an unset pooled value as meaningful. |
| A custom impact has a null `DamageSource` | Simple Damage replaces the initially resolved source with `ImpactCollisionData.SourceComponent as IDamageSource`. | Make the custom source component implement `IDamageSource` and configure its owner/source chain. Standard Usable Action, Trajectory Object, Projectile, and Explosion sources already do this. |
| A runtime Explosion argument uses the wrong processor or amount | The released overload forwards serialized component data to the Impact Action callback. | Configure the Explosion component's **Impact Damage Data**, or invoke a project-owned context with the intended data. |
| The processor applies its rule twice | More than one target call or more than one Impact Action may own damage. | Keep one damage owner and call `target.Damage` once. A Damage Processor is not a processor chain. |
| Remote players calculate a different result | The custom rule may be running on more than one peer or depend on data not carried by the network health interface. | Run the result on the authoritative combat path and synchronize the resulting Health state through the installed multiplayer integration. |
Do not retain `DamageData`, `ImpactCallbackContext`, or their pooled nested data after the synchronous call. Copy only the primitive or project-owned values that must outlive the hit.
## Save and multiplayer boundaries
A Damage Processor asset is configuration, not saved combat state. Persist armor, resistance, faction membership, difficulty, and other mutable values through the system that owns them. Health and inventory save support is separate from the processor and must be configured in the chosen save integration.
The UCC core package defines `INetworkHealthMonitor`, but a networking integration supplies the transport. On a networked Health component, only the authority forwards the accepted request through that monitor. Its damage method carries amount, position, direction, force magnitude, frames, radius, `IDamageSource`, and hit collider; it does not carry `DamageData.UserData`, `DamageTarget`, or `ImpactContext`. Make the processor's authoritative result reproducible from synchronized data, or explicitly replicate any additional project-owned result.
## Related tasks
- [Configure Health, Shield, hitboxes, and death](https://opsive.com/support/documentation/ultimate-character-controller/attributes/health/)
- [Configure ordered Impact Actions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/impact-actions/)
- [Configure a Shootable Action](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/shootable/)
- [Configure a Melee Action](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/melee/)
- [Configure a Throwable Action](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/throwable/)
- [Configure Explosions](https://opsive.com/support/documentation/ultimate-character-controller/objects/explosions/)
- [Use programming extension points](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/)
- [Listen for Health and death events](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/)
## Developer reference
### Create a custom processor
Derive a ScriptableObject from `DamageProcessor` and override `Process`. This example applies a nonnegative multiplier and then delegates to the target:
```csharp
using Opsive.UltimateCharacterController.Traits.Damage;
using UnityEngine;
[CreateAssetMenu(
fileName = "MultiplierDamageProcessor",
menuName = "Ultimate Character Controller/Damage Processors/Multiplier Damage Processor")]
public sealed class MultiplierDamageProcessor : DamageProcessor
{
[SerializeField, Min(0)] private float m_Multiplier = 1;
public override void Process(IDamageTarget target, DamageData damageData)
{
if (target == null || damageData == null) {
return;
}
damageData.Amount = Mathf.Max(0, damageData.Amount * m_Multiplier);
if (damageData.Amount > 0) {
target.Damage(damageData);
}
}
}
```
Returning before the target call is the normal way to reject a hit. Calling the target with an amount of `0` does not preserve force or events because the built-in Health target rejects zero-damage requests.
### Runtime data contracts
`DamageData` contains:
- `DamageSource`, an `IDamageSource` with **Owner Damage Source**, **Source Owner**, **Source GameObject**, and **Source Component** semantics;
- `DamageTarget`, which custom callers may set but the standard built-in population path does not;
- `Amount`, `Position`, `Direction`, `ForceMagnitude`, `Frames`, and `Radius`;
- `HitCollider`;
- `ImpactContext`, which exposes the originating `ImpactCallbackContext`; and
- `UserData`, an untyped project extension slot.
The current `IDamageTarget` contract exposes `Owner`, `HitGameObject`, `Invincible`, `Damage`, `IsAlive`, and `Heal`. Use the `target` argument as the authoritative target for the current call.
An `ImpactCallbackContext` contains the owning `CharacterItemAction` when one exists, required `ImpactCollisionData`, and optional `IImpactDamageData`. Collision data includes source ID, detection layers, raycast hit, impact position/object/Rigidbody/collider/direction/strength, damage source and target, source component/GameObject/character/item action, hit count/colliders, and surface impact. Use that detail only when the processor is intentionally coupled to an item impact; ordinary `Health.Damage` calls may have no impact context.
There is no processor-specific event. The processor decides whether to enter the target pipeline; the built-in Health component then sends `OnHealthDamage`, `OnHealthDamageWithData`, and, for a lethal result, `OnDeath`. See [Health](https://opsive.com/support/documentation/ultimate-character-controller/attributes/health/) for the exact event timing and signatures.
---
# Magic Particle
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/objects/magic-particle/)
Use **Magic Particle** when particles emitted by a Magic Action should turn Unity Particle System collisions into UCC impacts, such as a Fire Wand spray that damages what its embers touch.
## Choose a particle or a projectile
Magic Particle reports collisions; it does not move, aim, home, deal damage, or end the visual by itself.
| Intended result | Recommended setup |
| --- | --- |
| Several emitted particles can each touch a target | **Particle System**, **Magic Particle**, and **Particle Pooler**, spawned by the Magic Action's Cast Effects **Spawn Particle** module. The Particle System owns movement and collision. |
| One fireball follows a physical trajectory and produces one precise impact | **Projectile** with its required trajectory setup, spawned by Cast Effects **Spawn Projectile**. Let Projectile own collision and leave **Magic Particle Collisions** disabled unless a second particle-driven impact is deliberate. |
| A burst, glow, beam, or trail is visual only | Cast Effects **Spawn Particle** without **Magic Particle**, and keep the Collision module or **Send Collision Messages** disabled. |
For targeting, select **Forward**, **Target**, or **Indicate** on the Magic Action's Caster. That controls the cast data and the spawned root's orientation while the Cast Effect is active; Magic Particle does not steer individual particles toward a target. Use [Projectile](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/projectile/) or project-specific movement when the object itself needs trajectory or homing behavior.
## Create a collision particle prefab
1. Open **Tools > Opsive > Ultimate Character Controller > Object Manager**.
2. Enter a **Name**, select **Particle** for **Object Type**, enable **Magic Particle Collisions**, and select **Build Object**. The released Version 3 manager does not list a separate **Magic Particle** object type.
3. Save the prefab, then confirm its root has **Particle System**, **Particle Pooler**, and **Magic Particle**. In the inspected Version 3.2.0 builder, the **Particle** path adds Particle Pooler and optional Magic Particle but does not add Particle System; add that required component manually when it is absent.
4. Configure the Particle System's Main, Emission, Shape, movement, Renderer, and lifetime for the intended Fire Wand effect.
5. Enable the Particle System **Collision** module. Choose the appropriate world collision mode and **Collides With** layers, then enable **Send Collision Messages**. Magic Particle cannot receive `OnParticleCollision` without both the module and that option.
6. Configure the particle collision response. For a one-hit ember, make the particle stop or lose its remaining lifetime on contact. For an area stream, decide intentionally how often a continuing particle may report a collision.
7. Leave **Can Collide With Originator** disabled for a normal weapon. Also exclude the character's layers in **Collides With** when self-collision must be impossible.
8. Keep **Particle Pooler** on the prefab. Use a non-looping Particle System or make sure the Magic Action stops a looping one so it can return to the object pool.
The [Unity Particle System Collision module](https://docs.unity3d.com/Manual/PartSysCollisionModule.html) determines which scene colliders produce these messages. Magic Particle adds UCC impact handling after Unity reports a collision.
## Connect a Fire Wand
1. Create or select the Character Item's **Magic Action**. Add an enabled Trigger, a **Simple Caster**, and valid first- and third-person **Cast Origin** transforms as described in [Magic](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/magic/).
2. For a look-directed spray, set Simple Caster **Direction** to **Forward** and keep **Use Look Source** enabled.
3. In **Cast Effects Module Group**, add **Spawn Particle**. Assign the collision-particle prefab to **Particle Prefab**.
4. Tune **Position Offset** and **Rotation Offset** at the wand tip. Leave **Parent To Origin** disabled when emitted particles should remain in world space after the character moves. Choose Particle System **Simulation Space** to match that result.
5. Leave **Particle Layer** at its default Ignore Raycast unless the spawned visual itself must occupy another layer. This setting changes the spawned hierarchy's GameObject layer; the Particle System's **Collides With** mask still decides which targets particles can hit.
6. In **Impact Module Group**, add **Generic Magic Impact Module**. Configure its **Conditions** and successful **Impact Actions**. The default action group contains **Simple Damage**, **Spawn Surface Effect**, and **Impact Event**.
7. Set **Simple Damage > Damage Amount**, and select a **Surface Impact** on **Spawn Surface Effect** when the Surface System should create target-specific feedback. These values belong to the Magic Impact module, not Magic Particle. For a physics push, prefer Projectile or a custom Impact Action because the Magic Particle path leaves impact strength at zero in Version 3.2.0.
8. Save the Character Item and prefab, then verify that the Magic Action's **ID** matches the character's Use ability **Action ID**.
## Editor checkpoint
Before entering Play Mode, confirm that:
- the prefab has Particle System, Particle Pooler, and Magic Particle on the same root;
- **Collision** and **Send Collision Messages** are enabled, with deliberate **Collides With** layers;
- the Particle System's speed, lifetime, simulation space, looping, and collision lifetime behavior match the spell;
- the Cast Effects **Spawn Particle** row references this prefab and the cast origin is the wand tip;
- one or more enabled Magic Impact modules contain the intended damage, force, surface, event, or custom actions;
- self-collision is excluded unless it is a tested feature; and
- either Magic Particle or Projectile owns a collision result, rather than both responding to the same visible fireball.
## Choose the important settings
Magic Particle has one serialized option:
| Setting | Version 3 default | Behavior |
| --- | --- | --- |
| **Can Collide With Originator** | Disabled | Ignore a collision when Unity reports the casting character's Ultimate Character Locomotion GameObject as the target. Layer filtering is the safer additional guard for child-collider character setups. |
The Cast Effects **Spawn Particle** module controls how the prefab enters the scene:
| Setting | Version 3 default | Choose it based on |
| --- | --- | --- |
| **Particle Prefab** | None | The pooled prefab containing the particle setup. |
| **Position Offset** / **Rotation Offset** | Zero | Alignment relative to the current perspective's cast origin. |
| **Parent To Origin** | Disabled | Whether the particle root follows the cast origin. Emitted particle behavior also depends on Simulation Space. |
| **Project Direction On Plane** | Disabled | Whether to remove the character-up component from the cast direction. |
| **Clear Parent On Stop** | Disabled | Whether a parented particle root becomes independent before the cast stops emitting. |
| **Set Renderer Length Scale** | Disabled | Stretch a compatible Particle System renderer to the cast target distance; useful for a beam, not a normal ember spray. |
| **Particle Layer** | Ignore Raycast | The layer applied recursively to the spawned hierarchy. |
| **Fade In Duration** / **Fade Out Duration** | `0` | Optional material-alpha transitions. The material color property defaults to `_TintColor`. |
| **Delay** / **Initial Delay** | `0` / `-1` | Cast Effect timing. `-1` makes the first cast use Delay. Repeats require a Caster that keeps updating the cast. |
Particle velocity, gravity, lifetime, size, simulation space, and collision response remain Particle System settings. Magic Particle has no movement speed, targeting, collision mask, damage, impact limit, or lifespan fields.
A newly added **Generic Magic Impact Module** starts with one target-condition check, an empty failure group, and this successful action group:
| Impact Action | Important Version 3 defaults | Magic Particle result |
| --- | --- | --- |
| **Simple Damage** | **Damage Amount** `10`, **Impact Force** `2`, **Impact Force Frames** `15`, **Impact Radius** `0`, **Scale Damage By Impact Strength** disabled | Applies the base damage to a damage target. Magic Particle leaves **Impact Strength** at `0`, so its standard force is zero; enabling damage scaling would also reduce damage to zero. |
| **Spawn Surface Effect** | **Use Context Data** enabled; local **Surface Impact** None | Assign the local Surface Impact because this collision path does not supply Impact Damage Data. Placement uses Magic Particle's reconstructed raycast. |
| **Impact Event** | Source and target callbacks enabled | Sends `OnObjectImpact` to the particle source and impacted target. |
Keep **Scale Damage By Impact Strength** disabled for this component unless an earlier custom action explicitly assigns a nonzero strength.
## How it runs
1. Cast Effects **Spawn Particle** obtains the prefab from `ObjectPoolBase`, positions and rotates it from the Caster data, applies **Particle Layer**, clears the Particle System, and initializes Magic Particle with the active Magic Action and cast ID.
2. Unity simulates the particles. The Particle System Collision module decides which collisions generate `OnParticleCollision` messages.
3. Magic Particle rejects the reported originator when **Can Collide With Originator** is disabled, finds a non-trigger Collider on the reported GameObject, and reconstructs a `RaycastHit` from the particle-system root toward that object.
4. `MagicAction.PerformImpact` records the particle root as the source GameObject, the casting character in the impact context's fallback owner data, and the cast ID as the impact source ID. Every enabled Magic Impact module receives the context.
5. Generic Magic Impact evaluates its conditions, then invokes the successful or failed Impact Action group. Simple Damage can affect Health, Spawn Surface Effect uses the reconstructed hit, and Impact Event can notify listeners. The Magic Particle path does not assign Impact Strength, so the default Simple Damage force is zero.
6. When the particle GameObject is disabled, Magic Particle resets each enabled Magic Impact module for that cast ID.
7. Particle Pooler waits for the Particle System to stop being alive, then returns the GameObject through the local or active network object pool. A looping system remains alive until another owner stops it.
Magic Particle does not stop a particle after collision and does not suppress repeated callbacks. A particle that continues colliding can perform the Magic Impact group again. Use the Particle System collision response, an Impact Condition, or a Projectile workflow to enforce the intended hit count.
## Verify in Play Mode
1. Equip the Fire Wand, expand the Magic Action's **Debug** view, and cast at a Health target on an included collision layer.
2. Confirm particles begin at the correct first-person or third-person wand tip, travel in the expected simulation space, and do not collide with the caster.
3. Confirm one particle collision enters the enabled Magic Impact modules and produces the configured damage, surface response, and impact event. If the design requires push force, verify the custom action or Projectile path that supplies it.
4. Cast at scenery without Health. Confirm the surface response occurs and no damage error is produced.
5. Cast several particles into one target. Confirm the observed number of impacts matches the spell design; change collision lifetime or conditions if a continuing particle applies damage repeatedly.
6. Test a miss. Non-looping particles should finish and the prefab should become inactive through Particle Pooler.
7. Stop or interrupt the cast and switch perspectives. Confirm no looping particle remains attached to the old origin and the next cast initializes cleanly.
8. If using a physical fireball instead, repeat with **Spawn Projectile** and verify that Projectile alone owns the collision and lifespan.
9. In multiplayer, repeat as owner, server, and remote observer. Confirm only the authoritative path applies gameplay impacts and every role cleans up the visual.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| The Console says the Magic Projectile has no Particle System. | The Version 3.2.0 Object Manager **Particle** path may have created Particle Pooler without Particle System. | Add Particle System to the prefab root before Play Mode. |
| The Console says Collision or Send Collision Messages is disabled. | Particle System **Collision** and **Send Collision Messages** are required by Magic Particle. | Enable both and configure **Collides With**. |
| Particles are visible but impacts never run. | The prefab may be spawned as ordinary scenery, the Cast Effect may not have initialized Magic Particle, or no Magic Impact module is enabled. | Spawn it through Magic Cast Effects **Spawn Particle**, or call `Initialize` from custom code, then enable the intended Impact module. |
| Particles do not move or move with the wand unexpectedly. | Magic Particle has no movement. Check Particle System velocity, lifetime, **Simulation Space**, and **Parent To Origin**. | Configure motion in the Particle System or use a Projectile for trajectory-driven movement. |
| The spell hits its caster. | **Can Collide With Originator** only filters the GameObject Unity reports when it resolves directly to the caster's locomotion object. | Also exclude the character layers from Particle System **Collides With**, especially for child colliders. |
| One particle damages the same target repeatedly. | The particle remains alive and Unity continues sending collision messages; Magic Particle does not end it or deduplicate callbacks. Generic Magic Impact forces its Impact Actions, so **Allow Multi Hits** does not suppress these callbacks. | Stop or kill the particle on collision, add an Impact Condition/custom hit guard, or use one Projectile impact. |
| **Impact Force** is nonzero but the target is not pushed. | `MagicAction.PerformImpact` initializes this collision context with **Impact Strength** `0`, and Simple Damage multiplies force by that value. | Use Projectile or a custom Impact Action that assigns a deliberate strength before applying force. |
| Damage becomes zero after enabling strength scaling. | **Scale Damage By Impact Strength** also multiplies damage by the zero strength on this path. | Keep the option disabled or assign strength in project code before Simple Damage runs. |
| A physical fireball damages twice. | Both Projectile collision and Magic Particle collision may be reporting the same encounter. | Choose one collision owner. For a normal Spawn Projectile fireball, disable **Magic Particle Collisions**. |
| Surface feedback appears at an unexpected point. | Version 3.2.0 reconstructs a raycast from the Particle System root rather than reading the individual particle's collision event position. | Keep particles tightly aligned with the root or use Projectile/custom collision-event processing when exact hit position and normal matter. |
| The prefab never returns to the pool. | The Particle System may be looping or remain alive in a child. | Stop every looping system and allow all child particles to die; Particle Pooler waits while `IsAlive(true)` remains true. |
| A collision with a child or unusual collider does nothing. | Magic Particle searches the reported GameObject's Colliders and skips triggers before reconstructing a raycast on that GameObject's layer. | Put a non-trigger Collider on the reported target object or use Projectile/custom collision handling for complex hierarchies. |
| Remote players produce duplicate damage or stale particles. | Magic Particle itself does not decide authority. | Let the multiplayer integration own Magic Cast Effect and Impact replication, and do not independently execute gameplay impacts on observers. |
| Damage, scoring, or kill credit has no attacker. | In Version 3.2.0, Magic Particle is not an `IDamageSource`, and default **Simple Damage** replaces its prepared fallback source with `SourceComponent as IDamageSource`, which is null for this component. | Use Projectile for source-preserving impacts, add a project `IDamageSource` component to the particle root, or use a custom Impact Action that keeps the context's `DamageSource`. |
| A combined spell uses damage or surface data from a different effect. | The Magic Particle `PerformImpact` overload does not assign or clear the reused context's `ImpactDamageData`; a previous projectile-style effect can leave data there. | Use separate Magic Actions for unlike impact data or clear and populate the context in a custom collision path before running Impact modules. |
## Related pages
- [Magic](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/magic/) configures the Caster, Cast Effects, Impact modules, timing, and networking flow.
- [Object Manager](https://opsive.com/support/documentation/ultimate-character-controller/objects/objects/) creates the starting particle or projectile prefab.
- [Projectile](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/projectile/) is the better collision owner for a single moving fireball.
- [Impact Actions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/impact-actions/) configure damage, force, surface effects, and callbacks.
- [Impact Action Conditions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/impact-action-conditions/) filter which targets receive an impact.
- [Health](https://opsive.com/support/documentation/ultimate-character-controller/attributes/health/) configures damage and Shield reception.
- [Surface Impacts](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-impacts/) map an impact to surface-specific effects.
- [Events](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/) explains UCC event registration and cleanup.
## Developer reference
`MagicParticle.Initialize(MagicAction magicAction, uint castID)` is the required runtime handoff. Cast Effects **Spawn Particle** and **Spawn Projectile** call it automatically when the spawned root contains Magic Particle. A custom spawner must call it before collision messages arrive. `OnParticleCollision(GameObject other)` is the Unity callback that reconstructs a hit and calls `MagicAction.PerformImpact`.
Magic Particle exposes no public property for **Can Collide With Originator** in the inspected Version 3.2.0 source. Subclass the component or configure the serialized field on the prefab rather than expecting a runtime property.
The source does not call `ParticleSystem.GetCollisionEvents`; it reconstructs one raycast using the Particle System root and the reported target. That is adequate for a simple, aligned effect but is not an exact per-particle collision position or normal. It also does not destroy the particle, impose a hit limit, or provide targeting.
`MagicAction.PerformImpact(uint, GameObject, GameObject, RaycastHit)` resets the reused `ImpactCollisionData` but does not assign `ImpactStrength`, leaving it at `0`. The standard Simple Damage action multiplies force by that value. It also multiplies damage by the same value when **Scale Damage By Impact Strength** is enabled. A project action must assign strength before those calculations when either scaled result is required.
That overload also neither assigns nor clears `MagicImpactCallbackContext.ImpactDamageData`. It is normally null for a particle-only spell, so Simple Damage and Spawn Surface Effect use their local values. If another Cast Effect previously supplied Impact Damage Data through the same Magic Action, the reused context can retain it; custom code should explicitly clear or replace that data.
Version 3.2.0 prepares fallback owner data for a Magic Particle impact, but the default **Simple Damage** action subsequently assigns `DamageData.DamageSource` from `ImpactCollisionData.SourceComponent`. Magic Particle does not implement `IDamageSource`, so that assignment is null unless another source component is supplied. Projects that require reliable attacker or kill attribution should use the Projectile path, add a source component, or customize damage processing.
Prefab and Magic Action settings serialize normally, but an active cast ID, initialized Magic Action reference, live particles, scheduled pool check, and Impact module runtime state are transient. Finish or cancel the spell around a save/load boundary rather than expecting an in-flight particle stream to resume.
With the multiplayer integration enabled, Magic Action exposes Cast Effect and Impact replication calls, and Particle Pooler uses `NetworkObjectPool.Destroy` while network pooling is active. Authority, spawning, impact replication, and object registration remain integration responsibilities; custom spawning is not synchronized automatically.
---
# Object Identifier
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/objects/object-identifier/)
Use **Object Identifier** to give a GameObject a stable numeric role when UCC must find it within a runtime hierarchy, or when a Detect Object ability should accept only a particular kind of target.
An Object Identifier is a passive marker. It does not register the GameObject globally, make an ID unique, or save and synchronize the object. A consumer such as an ID/Object field or Detect Object ability decides where and when to look for the marker.
## Choose when to use an identifier
| Goal | Recommended reference |
| --- | --- |
| A component always uses one object in the same scene or prefab | Assign the object reference directly when that field supports it. |
| A reusable item prefab must find a spawn point, holster, muzzle, or another role on the character's active model | Give the role an Object Identifier and select the same ID in the item's ID/Object field. |
| Several interchangeable character models expose the same role | Put the same semantic ID on the equivalent GameObject in each model. Keep only one match within each searched model hierarchy. |
| Interact, Look At, Pickup, Drive, Ride, or another Detect Object ability should accept a narrower set of targets | Put the identifier on the detected GameObject or one of its parents and set the ability's **Object ID** to match. |
| A system needs a scene-wide lookup, persistent save identity, or network identity | Use a project-level registry or persistence/network identifier. Object Identifier does not provide those behaviors. |
Some UCC fields intentionally force an ID search so they can follow the active model. For example, a Third Person Perspective Item resolves **Spawn Parent** and **Holster Target** by ID. Follow the owning feature's page instead of assuming that its adjacent object-reference field overrides the ID.
## Create a project ID
1. Create a project-owned map with **Assets > Create > Opsive > Ultimate Character Controller > Utility > NameIDMap**. Keep this asset in version control so every team member uses the same names and numbers.
2. Open **Tools > Opsive > Ultimate Character Controller > Utility > Object Identifiers**.
3. Assign the project asset to **Name Map**. The packaged map remains available for the demo, but project roles should live in the project's map.
4. Select the target GameObject and add the **Object Identifier** component.
5. Select the dropdown beside **ID**, enter a descriptive role such as `Rifle Spawn Parent`, and select **Add**. The editor assigns the next unused ID beginning at `10000`; values below `10000` are reserved for Opsive demo content.
The first Add to a new NameIDMap asks where to save its editable CSV file. Save that CSV beside the map and version both files; the map reads its editable entries from the CSV.
6. Select the new name in the dropdown. The name is an editor aid; the component serializes and compares the numeric **ID** at runtime.
7. In the consuming ability or ID/Object field, select or enter the same ID. For an ID/Object lookup, clear an old direct object reference unless the owning feature explicitly documents that it uses both.
8. Save the scene or prefab. If this is a model-specific role, repeat the same name and ID on the equivalent GameObject in every model prefab.
An ID/Object field uses the same searchable popup. Select an existing entry, enter a valid name and choose **Add**, or choose **Open Editor** for the complete NameIDMap. In the utility window, **Order By** offers **ID Ascending**, **ID Descending**, **Name Ascending**, and **Name Descending**. Names and IDs must each be unique; sorting changes only their editor presentation.
The registered legacy image uses ID `106`. For new project roles, use the project map's generated IDs rather than copying an ID from this image or the demo.
## Choose IDs and marker locations
### Use positive project IDs
The Object Identifier component starts at ID `0`. An `IDObject` field, such as **Spawn Parent** or **Holster Target**, starts at `-1`, which means no ID lookup. Detect Object abilities also use `-1` to disable their ID filter.
For new shared roles, use the map-generated range from `10000` through `2147483647`. Object Identifier stores an unsigned value, but UCC's ID/Object fields and Detect Object abilities store signed integers, so larger values cannot be represented consistently by every consumer. Avoid negative manual entries: the Object Identifier Inspector converts its integer input to an unsigned value.
The NameIDMap editor rejects a duplicate name or ID when adding or editing a project entry, but the runtime component does not enforce uniqueness. If two markers with the same ID exist in one searched parent or child hierarchy, an `IDObject` resolves the first one returned by Unity. Reusing one ID on equivalent, mutually exclusive model prefabs is intentional; duplicating it within one active model is ambiguous.
### Put the marker on the resolved component
An `IDObject` finds a matching Object Identifier and then requests component `T` from that same GameObject. Put both components together. For example, a `Transform` target needs only the marker because every GameObject has a Transform; a custom component target needs that custom component beside the marker.
The search is limited to the parent or child hierarchy supplied by the consuming feature, including inactive GameObjects. It is not a scene-wide search. Place model-specific markers below the model or Item Slot that the field searches.
### Reuse a role across character models
A runtime Character Item prefab can use one **Spawn Parent** ID to find the corresponding attachment below each model's matching Item Slot. A Third Person Perspective Item can likewise use one **Holster Target** ID for an equivalent hip or back target on every model. When the active model changes, these item paths perform a fresh lookup in the new model.
Use the same positive role ID on each alternative model, but verify that each individual model contains exactly one matching marker. This lets the item prefab remain model-independent without storing a reference to one scene instance.
### Filter a detected target
On an ability derived from Detect Object Ability Base, leave **Object ID** at `-1` when the ID should not filter candidates. Set it to a project ID when the detected GameObject or one of its parents must contain a matching Object Identifier.
**Detect Layers** remains the first physics filter. A matching ID does not make a collider detectable when its layer, distance, trigger, angle, or ability-specific requirements reject it. See [Detect Object Ability Base](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/detect-object-ability-base/) for the complete detection workflow.
## How resolution runs
Object Identifier itself only exposes its numeric `ID`. For an ID/Object field, `IDObject` performs the lookup:
1. Unless the caller forces a search, it first returns a previously assigned or cached object.
2. ID `-1` returns no object.
3. The caller chooses a parent or child search and provides the root GameObject.
4. UCC includes inactive GameObjects, compares marker IDs, and uses the first matching marker.
5. It reads component `T` from the marker's GameObject and caches the result. A failed search is cached too.
The cache avoids repeating hierarchy scans, but it also means a non-forced lookup does not notice a later-spawned marker, a changed ID, a replaced model, or a destroyed cached component. Built-in features that expect model changes can force a new search or call `ResetValue()`. Custom code must do the same when its hierarchy changes.
Detect Object abilities use a separate path: after physics finds a candidate, they check Object Identifier components on that GameObject and its parents. They do not use the generic `IDObject` cache.
## Editor checkpoint
Before entering Play Mode, confirm that:
- the project **Name Map** contains a descriptive, non-demo ID;
- the target has Object Identifier with the intended numeric **ID**;
- an ID/Object lookup has the required component on the same GameObject as the marker;
- the marker is inside the parent or child hierarchy searched by the owning feature;
- each active searched hierarchy has only one marker for that role;
- alternate models repeat the same semantic role and ID; and
- a Detect Object target also has a collider on a layer included by **Detect Layers**.
## Verify in Play Mode
1. Select the consuming component and enter Play Mode.
2. Trigger the workflow that uses the reference. For an item prefab, equip and unequip it and confirm that its visible object uses the intended spawn or holster Transform.
3. If the character supports model switching, change to every model and repeat the workflow. The item should resolve the equivalent target rather than remain on the previous model.
4. For a Detect Object ability, approach one target with the matching ID and one without it. Confirm that **Detected Object** selects only the valid target while all other detection requirements are met.
5. Disable or temporarily change the intended marker and repeat the test. The workflow should fail or use its documented fallback rather than silently resolve an unrelated duplicate.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| The wrong object is resolved. | Search the relevant parent or child hierarchy for duplicate IDs. UCC uses the first matching marker returned by Unity. | Give each role one match per active hierarchy. Reuse the ID only on alternative model prefabs. |
| The marker is found but the result is null. | The requested component may not be on the same GameObject as Object Identifier. | Move the marker to the component's GameObject or add the required component there. |
| A runtime-spawned target is never found after an earlier miss. | `IDObject` caches a failed lookup. | Call `ResetValue()` or force the next search after changing the hierarchy. |
| Changing the ID during Play Mode has no effect. | Changing `IDObject.ID` does not clear its cached value. | Set the new ID, then call `ResetValue()` or perform a forced search. |
| An item remains attached to the previous model. | The next model may be missing the matching positive ID, or custom code may be reusing a cached result. | Add the equivalent marker to every model and reset or force the lookup on the model-change event. |
| A Detect Object ability rejects a correctly identified target. | Check **Detect Layers**, collider/trigger setup, distance, angle, and the concrete ability's required target component. | Correct the detection setup; Object ID is an additional filter, not a replacement for it. |
| The Inspector shows a large unexpected number. | A negative value may have been entered into the Object Identifier's integer control and converted to an unsigned ID. | Select a valid entry from the NameIDMap and use a positive value no larger than `2147483647`. |
| The ID dropdown is empty or shows the wrong project names. | The **Object Identifiers** window may still reference the packaged or a deleted **Name Map**. | Open the utility window and assign the project's NameIDMap. A deleted selection falls back to the packaged map. |
## Related tasks
- [Detect Object Ability Base](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/detect-object-ability-base/) configures layer, cast, trigger, angle, and Object ID filtering.
- [Third Person Perspective](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/third-person-perspective/) uses identified spawn and holster targets for runtime Character Item prefabs.
- [First Person Perspective](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/first-person-perspective/) explains first-person item objects and their model-specific references.
- [Model Switch](https://opsive.com/support/documentation/ultimate-character-controller/character/model-switch/) prepares equivalent slots and attachment roles across interchangeable models.
- [Item Creation](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-creation/) builds scene items and reusable Character Item prefabs.
## Developer reference
`ObjectIdentifier.ID` is a `uint` and defaults to `0`. `IDObjectBase.ID` is an `int` and defaults to `-1`. `IDObject` exposes `Obj`, `BaseObject`, `GetObjectInChildren`, `TryGetObjectInChildren`, `GetObjectInParent`, `TryGetObjectInParent`, `GetObject`, `TryGetObject`, and `ResetValue`.
```csharp
using Opsive.UltimateCharacterController.Objects;
using UnityEngine;
public class ModelAttachmentResolver : MonoBehaviour
{
[SerializeField] private IDObject m_Attachment = new IDObject();
public Transform Resolve(GameObject modelRoot, bool hierarchyChanged)
{
return m_Attachment.GetObjectInChildren(modelRoot, hierarchyChanged);
}
public void Invalidate()
{
m_Attachment.ResetValue();
}
}
```
With `forceSearch` set to `false`, an assigned object or any previous lookup result is returned from the cache. `ResetValue()` clears both the cached flag and cached object. Setting `BaseObject` during Play Mode changes the ID to `-1` and marks the direct reference as cached; setting `Obj` directly does not perform that reset.
In released Version 3.2.0, `TryGetObject` returns `true` as soon as an ID matches, even when component `T` is missing from that marker's GameObject and the output is null. Check both the Boolean result and the returned object, or use the `GetObject...` result and test it for null.
Object Identifier has no registration, lifecycle, event, save, or network code. Its serialized ID survives with its scene or prefab, and an ID/Object field can serialize an object assigned in Edit Mode. A reference found by a runtime hierarchy search and its cache are not persistent. Do not use the component as a persistent object key or assume that adding it synchronizes a spawned object.
---
# Object Pickup
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/objects/object-pickup/)
Object Pickup is the shared world-object lifecycle for collectable health and inventory items. Use an Object Manager prefab when a trigger should grant a result, show collection feedback, then deactivate, return to a pool, or respawn.
## Choose a pickup type
Released Ultimate Character Controller Version 3 includes two concrete Object Pickup types:
| Goal | Pickup type | Character requirement | Detailed page |
| --- | --- | --- | --- |
| Restore a living target | **Health Pickup** | A parent component that implements `IDamageTarget`; the built-in choice is Health or Character Health. | [Health Pickup](https://opsive.com/support/documentation/ultimate-character-controller/objects/object-pickup/health-pickup/) |
| Add Item Definitions to Inventory | **Item Pickup** | An enabled Inventory and the character's main collision layer. | [Item Pickup](https://opsive.com/support/documentation/ultimate-character-controller/objects/object-pickup/item-pickup/) |
`ObjectPickup` and `ItemPickupBase` are abstract. Create a custom implementation only when the result is neither built-in healing nor inventory collection. A custom object used by the character's Pickup ability implements `IObjectPickup` and owns its `DoPickup` result.
## Build the starting prefab
1. Open **Tools > Opsive > Ultimate Character Controller > Object Manager**.
2. In **Object Builder**, enter a **Name**.
3. Set **Object Type** to **Health Pickup** or **Item Pickup**.
4. Assign the visible model to **GameObject**. For an Item Pickup, use the model rather than an already built Character Item.
5. Select **Build Object**, choose a location under the project's `Assets` folder, and open the generated prefab.
6. Confirm the root has the expected pickup component and a Collider with **Is Trigger** enabled. Size the trigger around the intended collection area.
7. Configure the result, feedback, and lifetime before placing the prefab in a scene.
The **Item Pickup** builder adds a solid Box Collider, a trigger Sphere Collider, Item Pickup, and Respawner, and puts the object on the Visual Effect layer. **Dropped Item** creates the same pickup and colliders with Trajectory Object instead of Respawner. Follow the full [Item Pickup workflow](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-pickup/) when building scene loot or a Character Item's **Drop Prefab**.
In released Version 3, the **Health Pickup** builder adds a Sphere Collider but does not enable **Is Trigger**. Enable it manually on the generated prefab. Without a trigger on the same GameObject, Object Pickup logs an error and its initialization can fail.
## Configure the shared pickup behavior
Every concrete Object Pickup exposes these shared fields:
| Field | Version 3 default | Behavior |
| --- | --- | --- |
| **Trigger Enable Delay** | `4` seconds | Delays collection when a depleted pickup is reused. A Rigidbody pickup waits until its velocity settles, then starts this delay. |
| **Pickup On Trigger Enter** | Enabled | Selects immediate contact collection for Item Pickup. The built-in Health Pickup does not read this field. |
| **Rotation Speed** | `(0, 0, 0)` | Rotates the display by the configured Euler amount during each physics update. |
| **On Select** | No listeners | Invoked when a Detect Object ability selects the pickup. |
| **On Deselect** | No listeners | Invoked when that ability releases the pickup. |
| **Destroy Delay** | `0` seconds | Removes the depleted pickup immediately. A positive value delays removal; `-1` leaves it visible but depleted. |
| **Pickup Audio Clip Set** | Empty | Plays collection audio when UCC finds a camera associated with the collecting object. |
| **Pickup Message Text** | Empty | Supplies the Message Monitor's post-collection text and can populate a Pickup ability message placeholder. |
| **Pickup Message Icon** | None | Supplies the Message Monitor's post-collection icon. |
The first scene activation enables the trigger immediately even when **Trigger Enable Delay** is positive. The delay applies after the pickup has been depleted and initialized again. For a reused pickup without a Rigidbody, the countdown starts at initialization; with a Rigidbody, it starts after the body settles.
Keep the trigger on the same GameObject as the pickup component. Item Pickup also requires the entering collider to belong to the character's main layer according to Character Layer Manager, preventing item and ragdoll colliders from collecting it.
## Configure a Health Pickup
Use this for a health pack that is collected on contact:
1. Set **Health Amount**. The Version 3 default is `40`.
2. Leave **Always Pickup** disabled when a full target should leave the pack available.
3. Enable **Always Pickup** when a living target should consume the pack even if `Heal` applies no value.
4. Confirm the pickup's trigger can collide with the character's main colliders.
5. Confirm the character's Health component references valid Health and optional Shield attributes.
Health Pickup searches the entering object and its parents for `IDamageTarget`, requires that target to be alive, and calls `Heal(Health Amount)`. Built-in Health restores Health first, then puts any remaining amount into Shield. A dead target cannot consume the pickup even when **Always Pickup** is enabled.
The inherited **Pickup On Trigger Enter** field does not gate Health Pickup: its `TriggerEnter` always calls `DoPickup`. For an animation- or input-gated health object, use a custom externally controlled `IObjectPickup` rather than relying on that checkbox.
## Configure an Item Pickup
Use this for an Iron Sword, firearm, ammunition bundle, or another inventory result:
1. Add each Item Definition and quantity to **Item Definition Amounts**.
2. Leave **Always Pickup** disabled when a full Inventory should keep the world object available. Test the released-version capacity limitation below before relying on that behavior.
3. Leave **Equip** enabled when a valid collected Character Item should become active. Disable it for ammunition or inventory-only loot.
4. Leave **Item Set Group** at `-1` to search all groups, or enter the intended group index.
5. Leave **Item Set Name** empty to use a valid set containing the item, or enter the exact Item Set State name that should be selected.
6. Keep **Pickup On Trigger Enter** enabled for automatic contact collection.
7. Disable it only when the character's [Pickup ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/detect-object-ability-base/pickup/) should detect the object, wait for input or animation, and perform the transfer.
The character does not need the Pickup ability for automatic Item Pickup. The animated route needs an enabled Inventory, Item Set Manager for equipping, compatible Equip Unequip abilities, correct detection layers, and its pickup animation events or durations.
Use [Item Pickup](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-pickup/) for capacities, equipping, dropped-item population, and the complete animated workflow.
## How collection runs
When an eligible object enters the trigger:
1. Object Pickup rejects the request if it is already depleted.
2. Health Pickup tries to heal a living `IDamageTarget`; Item Pickup validates the enabled Inventory and main character layer.
3. The concrete pickup decides whether any value was accepted, unless **Always Pickup** forces depletion.
4. A completed pickup marks itself depleted and sends `OnObjectPickedUp` on the collecting object.
5. Collection audio plays when UCC finds the collector's camera. A Message Monitor can display the configured text and icon.
6. **Destroy Delay** removes the object immediately, schedules removal, or leaves it visible but depleted.
7. A pooled pickup returns through the Opsive object pool. A non-pooled pickup deactivates so Respawner can reactivate it when configured.
For Item Pickup with **Pickup On Trigger Enter** disabled, the Pickup ability reserves the object, coordinates Equip Unequip, and adds the definitions at its pickup event. The world object can become depleted before the delayed Inventory transfer, so test capacity-limited inventories explicitly.
## Editor checkpoint
Before entering Play Mode, confirm that:
- the pickup component and one trigger Collider are on the same GameObject;
- the trigger's layer collides with the character and is included by Pickup's **Detect Layers** when using the ability;
- a Health Pickup generated by Object Manager has **Is Trigger** enabled manually;
- a Health Pickup target has a live `IDamageTarget` with valid attributes;
- an Item Pickup has non-null Item Definitions, positive useful amounts, and an enabled Inventory on the character;
- equippable loot has its Character Item, slots, Item Set rules, and Item Set Manager configured;
- **Pickup On Trigger Enter** matches the intended automatic or animated Item Pickup route;
- **Destroy Delay** and Respawner create one deliberate lifetime; and
- message, audio, and selection feedback have the UI, camera, or detection listener they require.
## Verify in Play Mode
1. Enter a Health Pickup trigger with partially depleted Health and Shield. Confirm Health fills first, then Shield receives any remainder, and the pickup depletes once.
2. Repeat at full values with **Always Pickup** off and on. The pickup should remain for the first test and be consumed for the second.
3. Enter an automatic Iron Sword or firearm pickup. Confirm the configured amount enters Inventory once and the intended Item Set equips when allowed.
4. Repeat with an ammunition pickup near capacity. Confirm the accepted amount and whether the world object remains match the project's capacity policy.
5. Disable **Pickup On Trigger Enter** on an Item Pickup. Confirm contact only selects it, then input and the configured animation event add the item.
6. Observe **On Select**, **On Deselect**, pickup audio, message text/icon, and `OnObjectPickedUp` in their intended order.
7. For a scene pickup with Respawner, wait through depletion and the respawn interval. Confirm it returns at the intended position and can be collected again.
8. For a pooled or dropped pickup, confirm **Trigger Enable Delay** prevents immediate recollection after reuse.
## Troubleshooting and released-Version-3 limitations
| Symptom | Check | Fix |
| --- | --- | --- |
| Object Pickup logs that a trigger must exist, or initialization throws | The Health Pickup builder may have left its Sphere Collider non-trigger. | Enable **Is Trigger** on a Collider on the same GameObject as the pickup and size it appropriately. |
| **Trigger Enable Delay** does not delay a pickup placed in the scene | First initialization intentionally enables the trigger immediately. | Treat the field as a reuse delay; use a separate startup gate when the initial scene object must wait. |
| A Health Pickup is collected before an animation | Its implementation ignores **Pickup On Trigger Enter** and handles contact directly. | Use a custom externally controlled `IObjectPickup` for animation-gated health collection. |
| A full target consumes the Health Pickup | **Always Pickup** is enabled. | Disable it when `Heal` must change a value before depletion. |
| Item Pickup does nothing on contact | Check the trigger, collision matrix, enabled Inventory, Character Layer Manager, and **Pickup On Trigger Enter**. | Restore the main-character collider path, or finish the Pickup ability setup for an input-driven object. |
| The item disappears even though Inventory capacity accepted zero | Released Version 3 treats an Inventory return value of `0` as a successful Item Pickup because it checks for `>= 0`. | Precheck capacity or use a corrected custom Item Pickup when the world object must remain. **Always Pickup** does not fix this boundary. |
| The item enters Inventory but does not equip | Check **Equip**, Item Set Manager, group/name, Character Item, slots, and whether Use or Reload is active. | Complete the item-set setup and retry when the conflicting ability is inactive. |
| A dropped pickup can be collected while still moving | Object Manager's **Dropped Item** has Trajectory Object but no Rigidbody, so the delay starts at initialization rather than waiting for rigidbody velocity. | Increase **Trigger Enable Delay** to cover the flight or add a landing-aware project gate. |
| The model remains but cannot be collected again | **Destroy Delay** is `-1`, which leaves an already depleted object active. | Use a positive delay, Respawner, pooling, or explicitly call `Initialize` as part of a controlled reuse path. |
| Pickup sound does not play | UCC may not find a camera associated with the collecting object. | Assign the character to the active camera workflow or play project-owned feedback from `OnObjectPickedUp`. |
| **On Select** and **On Deselect** never run | Trigger contact alone does not send detection selection events. | Use a Detect Object ability that selects the pickup, or connect feedback to the collection event instead. |
## Persistence, pooling, and multiplayer
Object Pickup does not save depletion, a pending destroy delay, or a Respawner timer. A save integration must persist the authoritative Inventory or Health state and any world pickup state that should survive loading. Otherwise a loaded character can keep the collected value while the scene restores another copy of the pickup.
Pooled pickups use `ObjectPoolBase.Destroy` and initialize again when enabled. Non-pooled objects are deactivated; a Respawner with **Schedule Respawn On Disable** can restore them. The Object Manager adds Respawner to Item Pickup and Health Pickup, but not to Dropped Item.
Multiplayer hooks compile with a supported integration. A pickup created through the Opsive pool uses `NetworkObjectPool.Destroy` when a network pool is active, while Inventory and Respawner each have separate network bridges. Core Object Pickup does not decide combat authority or persist ownership. Let the server or owning peer accept collection once, then replicate the Inventory/Health change and world-object removal through the installed integration.
## Related tasks
- [Health Pickup](https://opsive.com/support/documentation/ultimate-character-controller/objects/object-pickup/health-pickup/) covers the built-in healing result.
- [Item Pickup](https://opsive.com/support/documentation/ultimate-character-controller/objects/object-pickup/item-pickup/) is the direct inventory-pickup reference.
- [Item Pickup workflow](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-pickup/) covers creation, capacity, equipping, animation, and drops in depth.
- [Health](https://opsive.com/support/documentation/ultimate-character-controller/attributes/health/) configures Health, Shield, healing order, and death state.
- [Pickup ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/detect-object-ability-base/pickup/) configures detection, input, and animation timing.
- [Inventory](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/inventory/) owns Item Definition amounts and runtime Character Items.
- [Respawner](https://opsive.com/support/documentation/ultimate-character-controller/spawn-system/respawner/) controls return time and position.
- [Object Manager](https://opsive.com/support/documentation/ultimate-character-controller/objects/objects/) creates the starting pickup prefabs.
- [Trajectory Object](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/) controls a dropped pickup's motion.
## Developer reference
`IObjectPickup` defines `DoPickup(GameObject target)`. `ObjectPickup` implements that interface and requires derived classes to implement both `TriggerEnter(GameObject other)` and `DoPickup(GameObject target)`. Its public runtime surface includes the shared trigger, rotation, audio, message, selection-event properties, `IsDepleted`, `Initialize(bool forceInitialization)`, and `DestroyPickup()`.
The base sends `OnObjectPickedUp(ObjectPickup pickup)` on the collecting GameObject after marking the object depleted. It listens for `OnObjectDetected(GameObject interactor, bool selected)` on the pickup and maps that state to the **On Select** and **On Deselect** UnityEvents.
`ItemPickupBase` wraps an inventory transfer with `OnItemPickupStartPickup` and `OnItemPickupStopPickup`. `ItemPickup` exposes its definition amounts through `GetItemDefinitionAmounts()` and `SetItemDefinitionAmounts(...)`; Drop uses that surface to populate a dropped prefab at runtime.
Health Pickup resolves `IDamageTarget` and calls its `IsAlive()` and `Heal(float)` methods. A custom target owns its healing semantics; the built-in Health implementation fills Health before Shield.
---
# Health Pickup
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/objects/object-pickup/health-pickup/)
Health Pickup restores a living `IDamageTarget` when it enters the pickup's trigger. Use it for health packs that collect on contact, optionally disappear at full health, and can return through Respawner.
## Before you begin
- The receiving character or object needs **Health**, **Character Health**, or another component that implements `IDamageTarget`.
- Built-in Health needs an Attribute Manager on the same GameObject and a valid **Health Attribute**. Assign a **Shield Attribute** only when the target uses one.
- The pickup needs a Collider with **Is Trigger** enabled on the same GameObject as Health Pickup.
- The pickup layer and character collision layers must interact in Unity's Physics settings.
- Decide whether the object should be a one-time pickup, return through Respawner, or be spawned and returned through an object pool.
## Create the Health Pickup
1. Open **Tools > Opsive > Ultimate Character Controller > Object Manager**.
2. In **Object Builder**, enter a **Name**.
3. Set **Object Type** to **Health Pickup**.
4. Assign the visible health-pack model to **GameObject**.
5. Select **Build Object**, save the prefab under the project's `Assets` folder, and open the generated prefab.
6. On the root Sphere Collider, enable **Is Trigger**. Released Version 3 adds the Collider but does not enable this option for Health Pickup.
7. Size the trigger around the intended collection area and confirm it remains on the same GameObject as **Health Pickup**.
8. Configure **Health Amount**, **Always Pickup**, feedback, and lifetime.
9. Place the prefab in the scene and test it against the real character.
Object Manager also adds **Respawner**. Keep it when the scene health pack should return after collection, or remove/disable its respawn-on-disable behavior for a one-time object.
## Configure healing and collection
| Field | Version 3 default | Behavior |
| --- | --- | --- |
| **Health Amount** | `40` | Passed to the target's `Heal` method. Use a positive value. |
| **Always Pickup** | Disabled | When disabled, the pickup depletes only if `Heal` changes a value. When enabled, a living target consumes it even when nothing changes. |
| **Trigger Enable Delay** | `4` seconds | Delays collection after a depleted pickup is reused. The first scene activation enables the trigger immediately. |
| **Pickup On Trigger Enter** | Enabled | Displayed by the shared base Inspector, but ignored by the built-in Health Pickup implementation. |
| **Rotation Speed** | `(0, 0, 0)` | Applies the configured display rotation during each physics update. |
| **Destroy Delay** | `0` seconds | Removes or deactivates the depleted pickup immediately. A positive value delays removal; `-1` leaves it visible but depleted. |
The Inspector also exposes an empty **Pickup Audio Clip Set**, empty **Pickup Message Text**, no **Pickup Message Icon**, and **On Select**/**On Deselect** UnityEvents with no listeners by default.
**Health Amount** has no minimum clamp in released Version 3. Keep it positive. A negative value can reduce partially depleted built-in Health while still using the heal feedback and event path.
## Choose the healing result
### Restore Health, then Shield
The built-in Health implementation fills Health first and puts only the remaining amount into Shield. For example, a `40`-point pack used when Health is missing `25` and Shield is missing `30` restores `25` Health and `15` Shield.
This is the opposite of incoming damage, which consumes Shield before Health. Configure attribute regeneration separately on the Attribute Manager; Health Pickup performs one immediate `Heal` request.
### Leave a pack for a full target
Keep **Always Pickup** disabled when the pack should remain available until it changes Health or Shield. Enable it for an arcade-style pickup that should disappear whenever a living target touches it, even at full values.
`Always Pickup` does not let a dead target collect the object. Health Pickup checks `IsAlive()` before calling `Heal` or consuming the pack.
### Add feedback and respawn
- Set **Pickup Message Text** and **Pickup Message Icon** for a Message Monitor response after collection.
- Assign **Pickup Audio Clip Set** when a collection sound should play. The collector must be associated with a camera that UCC can find.
- Use **On Select** and **On Deselect** only when a Detect Object ability selects this pickup. Trigger contact by itself does not invoke those selection events.
- Configure Respawner's time and position mode when a non-pooled scene pickup should return after it deactivates.
## Pickup ability boundary
Health Pickup always calls `DoPickup` when its trigger receives a valid entry. Disabling the inherited **Pickup On Trigger Enter** checkbox does not stop this behavior.
The character's Pickup ability can classify Health objects, but the standard Health Pickup still handles contact immediately. When healing must wait for input or an animation event, use a custom externally controlled `IObjectPickup` that does not collect from `TriggerEnter`, then let the Pickup ability call its `DoPickup` method.
## How it runs
1. On enable, Object Pickup clears its depleted state and prepares the trigger. First activation is immediate; reuse honors **Trigger Enable Delay**.
2. When a Collider enters, Health Pickup searches that object and its parents for `IDamageTarget`.
3. It rejects a missing or dead target.
4. It calls `Heal(Health Amount)` on a living target.
5. If `Heal` returns `true`, or **Always Pickup** is enabled, the object marks itself depleted and sends `OnObjectPickedUp` on the target owner's GameObject.
6. The pickup optionally plays audio and supplies its message text/icon to Message Monitor.
7. **Destroy Delay** removes the pickup now, later, or not at all. Pooled objects return to the pool; ordinary objects deactivate so Respawner can restore them.
For built-in Health, `Heal` clamps the positive amount to available capacity, fills Health before Shield, sends `OnHealthHeal` with the amount actually applied, and returns `false` when neither attribute changes.
## Editor checkpoint
Before entering Play Mode, confirm that:
- the generated Sphere Collider has **Is Trigger** enabled and sits on the Health Pickup GameObject;
- the pickup's layer collides with the character's main colliders;
- **Health Amount** is positive;
- the target's Health component resolves valid Health and optional Shield attributes;
- **Always Pickup** matches the intended full-health behavior;
- **Destroy Delay** and Respawner describe one deliberate lifetime; and
- audio, message, and selection feedback have the camera, Message Monitor, or Detect Object listener they require.
## Verify in Play Mode
1. Reduce Health by less than **Health Amount**, leave Shield full, and enter the trigger. Confirm Health increases by the available capacity and the pickup depletes once.
2. Reduce both Health and Shield. Confirm Health fills first and only the remainder restores Shield.
3. Start with both attributes full and **Always Pickup** disabled. Confirm the pickup remains available.
4. Repeat at full values with **Always Pickup** enabled. Confirm the living target consumes the pickup even though no value changes.
5. Test a dead target. Confirm it does not consume the pickup in either Always Pickup mode.
6. Confirm `OnHealthHeal` reports the amount actually restored and `OnObjectPickedUp` runs only after the object is consumed.
7. Verify audio and Message Monitor feedback, then wait for Respawner and confirm the trigger can collect again.
8. After reuse, confirm **Trigger Enable Delay** prevents immediate recollection. Do not expect that delay on the first scene activation.
## Troubleshooting and released-Version-3 limitations
| Symptom | Check | Fix |
| --- | --- | --- |
| The Console says a trigger must exist, or the pickup fails during initialization | Object Manager's Health Pickup Sphere Collider is not marked as a trigger. | Enable **Is Trigger** on a Collider on the same GameObject as Health Pickup. |
| Contact does not restore a value | Check the collision matrix, target hierarchy, `IDamageTarget`, alive state, Health/Shield attributes, and **Health Amount**. | Restore a valid trigger collision, select valid attributes, and use a positive amount. |
| Shield remains low while Health increases | Built-in `Health.Heal` deliberately fills Health first. | Increase **Health Amount** enough to leave a remainder for Shield, or implement a custom target when the game needs different healing priority. |
| The pack disappears at full values | **Always Pickup** is enabled. | Disable it when `Heal` must change a value before collection succeeds. |
| A dead target does not consume the pack with **Always Pickup** enabled | Health Pickup checks `IsAlive()` before the Always Pickup decision. | Revive or respawn the target first, or use a project-specific dead-target interaction. |
| Disabling **Pickup On Trigger Enter** has no effect | Health Pickup does not read the inherited field. | Use a custom externally controlled `IObjectPickup` for input- or animation-gated healing. |
| A placed pickup ignores **Trigger Enable Delay** | The first initialization enables its trigger immediately. | Use a separate startup gate when the initial scene object must wait; reserve this field for reuse. |
| The model stays visible but cannot heal again | **Destroy Delay** is `-1`, leaving an already depleted object active. | Use a positive delay, Respawner, pooling, or a controlled call to `Initialize`. |
| The pickup deactivates but never returns | Respawner may be absent, disabled, or have **Schedule Respawn On Disable** off. | Add/configure Respawner or spawn the pickup through the intended pool. |
| No collection sound or message appears | UCC may not find the collector's camera, or Message Monitor may not be assigned to the character. | Complete the character camera/UI setup or respond to `OnObjectPickedUp` with project-owned feedback. |
## Persistence and multiplayer
Health Pickup does not save its depleted state, destroy delay, or respawn timer. Persist the authoritative Health values and any world-pickup state that must survive loading; otherwise a restored scene can recreate a pack that the saved character already consumed.
In a supported multiplayer build, Health uses its network health monitor and pooled pickups can use the network object pool for removal. Core Health Pickup does not decide which peer owns the trigger result. Let the server or owning peer accept the heal once, then replicate both the Health change and world-object lifetime through the installed integration.
## Related tasks
- [Object Pickup](https://opsive.com/support/documentation/ultimate-character-controller/objects/object-pickup/) explains shared trigger, feedback, pooling, and lifetime behavior.
- [Health](https://opsive.com/support/documentation/ultimate-character-controller/attributes/health/) configures Health, Shield, healing order, events, death, and respawn behavior.
- [Attributes](https://opsive.com/support/documentation/ultimate-character-controller/attributes/) configures starting values, limits, and regeneration.
- [Respawner](https://opsive.com/support/documentation/ultimate-character-controller/spawn-system/respawner/) controls when and where a scene pickup returns.
- [Pickup ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/detect-object-ability-base/pickup/) explains detection, input, and the custom `IObjectPickup` route.
- [Item Pickup](https://opsive.com/support/documentation/ultimate-character-controller/objects/object-pickup/item-pickup/) covers inventory collection instead of healing.
- [Object Manager](https://opsive.com/support/documentation/ultimate-character-controller/objects/objects/) creates the starting prefab.
- [Events](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/) explains UCC event registration and cleanup.
## Developer reference
`HealthPickup` derives from `ObjectPickup` and exposes `HealthAmount` and `AlwaysPickup`. `TriggerEnter(GameObject other)` directly calls `DoPickup(other)`; the inherited `PickupOnTriggerEnter` property is not consulted.
`DoPickup` resolves a parent `IDamageTarget`, checks `IsAlive()`, calls `Heal(float)`, and completes the pickup when healing succeeds or **Always Pickup** is enabled. The object then sends `OnObjectPickedUp(ObjectPickup pickup)` on `damageTarget.Owner`.
The built-in Health target sends `OnHealthHeal(float amount)` with the value actually applied. Object Pickup also listens for `OnObjectDetected(GameObject interactor, bool selected)` on its own GameObject and maps that event to the Inspector's **On Select** and **On Deselect** UnityEvents.
---
# Item Pickup
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/objects/object-pickup/item-pickup/)
Item Pickup transfers one or more Item Definitions from a world object into a character's Inventory and can optionally equip a matching Item Set. Use it for placed loot, ammunition bundles, and Character Items that can be dropped and collected again.
## Before you begin
- Create every Item Definition that the pickup will grant. An equippable definition also needs a Character Item prefab, a compatible slot, and a valid Item Set Rule.
- Confirm the character has an enabled [Inventory](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/inventory/). Equipping also requires an Item Set Manager.
- Prepare a visible world model. In Object Manager, assign the model rather than an already built Character Item.
- Confirm the pickup layer can collide with the character's main collision layer. Item and ragdoll colliders do not collect an Item Pickup.
## Create the pickup object
1. Open **Tools > Opsive > Ultimate Character Controller > Object Manager**.
2. In **Object Builder**, enter a **Name**.
3. Set **Object Type** to **Item Pickup** for loot placed in a scene, or **Dropped Item** for a prefab that will be assigned to a Character Item's **Drop Prefab**.
4. Assign the visible model to **GameObject**.
5. Select **Build Object**, choose a path under the project's `Assets` folder, and open the generated prefab.
6. Confirm the root has Item Pickup, a solid Box Collider, and a Sphere Collider with **Is Trigger** enabled. Object Manager also adds Respawner to **Item Pickup**, or Trajectory Object to **Dropped Item**.
7. Size the trigger around the collection area. Keep it on the same GameObject as Item Pickup.
8. For a scene pickup, add each definition and quantity under **Item Definition Amounts**. A Character Item drop replaces this list with the removed item and any additional definitions at runtime.
### Editor checkpoint
A scene pickup should have Item Pickup, a trigger collider, a solid collider, and Respawner. A dropped-item prefab should have Item Pickup, both colliders, and Trajectory Object. Its Character Item should reference that prefab in **Drop Prefab**.
## Configure what the pickup grants
Each **Item Definition Amounts** row has an **Item Definition** and an integer **Amount**. The Inventory accepts up to that Item Type's configured capacity.
### Iron Sword pickup
1. Add the Iron Sword Item Definition with an amount of `1`.
2. Leave **Equip** enabled when the sword should become active after collection.
3. Leave **Item Set Group** at `-1` to search all groups, or enter the group that owns the sword.
4. Leave **Item Set Name** empty to select the first valid set containing the sword. Enter a name only when a specific Item Set State should be selected; the text must match its State name exactly.
Disable **Equip** when the sword should enter the Inventory without changing the active loadout.
### Firearm and ammunition pickup
Add the firearm Item Definition with an amount of `1`, then add its ammunition Item Definition with the desired quantity. The firearm needs a Character Item prefab in a valid slot; count-only ammunition does not need a visible Character Item.
Enable **Equip** when a valid firearm Item Set should become active after both definitions are added. Use separate ammunition-only pickups when collecting ammunition should not change equipment.
## Choose how collection starts
### Collect on contact
Keep **Pickup On Trigger Enter** enabled for automatic collection. When an eligible main character collider enters the trigger, Item Pickup finds the enabled Inventory, adds the configured amounts, optionally requests an Item Set, and depletes the world object.
This route does not require the Pickup ability. Use it for ammunition and other loot where walking through the trigger is the complete interaction.
### Use input and an animation
Disable **Pickup On Trigger Enter** when the character should select the object, press an input, and play a pickup animation.
1. Add the [Pickup ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/detect-object-ability-base/pickup/) to the character.
2. Keep **Allowed Pickups** set to **Item**, and include the pickup layer in **Detect Layers**.
3. Leave **Pickup Item Definitions** empty to animate every Item Definition, or add the definition that should use this animation.
4. Configure **Pickup Event** to use `OnAnimatorPickup`, or use its duration mode when the animation has no matching event.
5. Configure **Pickup Complete Event** to use `OnAnimatorPickupComplete`, or use its duration mode.
When an Item Definition matches the animated route, the ability reserves and depletes the world object as it prepares the pickup. The Inventory transfer waits for **Pickup Event**. This prevents a second character from collecting the same object during the animation, but it also means a zero-delay object can disappear before the hand reaches it. Use a positive **Destroy Delay** when the model should remain visible through the reach.
### Reuse an item as a world drop
1. Build the prefab with **Object Type** set to **Dropped Item**.
2. Assign it to the Character Item's **Drop Prefab** field.
3. Add and configure the [Drop ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/drop/).
When the Character Item is dropped, Inventory spawns the prefab, replaces **Item Definition Amounts** with the removed unit and any additional definitions supplied by the item, initializes the pickup, and starts Trajectory Object. Do not hard-code the carried item amount on a reusable dropped-item prefab.
## Key settings
| Field | Version 3 default | Use it when |
| --- | --- | --- |
| **Always Pickup** | Disabled | The object should be consumed even when no amount can be added. See the capacity limitation below before relying on the disabled state to preserve a full pickup. |
| **Equip** | Enabled | A valid collected Character Item should become active. Use and Reload can prevent the equipment change while either ability is active. |
| **Item Set Group** | `-1` | All Item Set groups should be searched. Enter a group index to constrain the request. |
| **Item Set Name** | Empty | The first valid set containing the item is acceptable. Enter an exact Item Set State name to request a specific set. |
| **Item Definition Amounts** | Empty | A scene object should grant fixed definitions and quantities. A dropped-item workflow supplies them at runtime. |
| **Trigger Enable Delay** | `4` seconds | A reused or dropped pickup should wait before becoming collectible again. The first scene activation is immediate. |
| **Pickup On Trigger Enter** | Enabled | Contact should collect the object. Disable it for the input-and-animation route. |
| **Destroy Delay** | `0` seconds | The depleted object should be removed immediately. A positive value delays removal; `-1` leaves it visible but already depleted. |
**Rotation Speed** starts at `(0, 0, 0)`. **Pickup Audio Clip Set**, **Pickup Message Text**, and **Pickup Message Icon** start empty, while **On Select** and **On Deselect** have no listeners.
For a reused pickup with a Rigidbody, **Trigger Enable Delay** begins after the body settles. Object Manager's **Dropped Item** adds Trajectory Object without adding a Rigidbody, so its delay begins when the pickup is initialized rather than when the visible flight ends. Use a delay that covers the flight when immediate recollection would be a problem.
## How it runs
1. Item Pickup ignores colliders that do not resolve to an enabled Inventory on the character's main layer.
2. With **Pickup On Trigger Enter** enabled, it requests each configured amount immediately. With the animated route, the Pickup ability first reserves the object and later performs the transfer at **Pickup Event**.
3. Inventory limits the accepted amount according to the Item Type and raises its pickup events for amounts that were added.
4. If **Equip** is enabled, Item Pickup updates Item Sets and tries the exact **Item Set Name** first. Otherwise it searches for a valid set containing a collected Character Item. It skips this equipment request while Use or Reload is active.
5. A successful result marks the object depleted and sends `OnObjectPickedUp` on the collecting character.
6. **Destroy Delay** removes the object immediately, schedules removal, or leaves the depleted model present. A pooled object returns to its pool; an ordinary object deactivates so Respawner can restore it.
## Verify in Play Mode
1. Keep the character's Inventory and the pickup's Item Pickup component visible.
2. Enter an automatic Iron Sword pickup. Confirm the amount increases once, the object depletes, and **Equip** selects the intended Item Set when enabled.
3. Test a firearm-and-ammunition pickup. Confirm both amounts change and the ammunition entry does not create an unwanted held object.
4. Fill an Item Type close to capacity, collect a larger amount, and confirm the Inventory accepts only the remaining space. Test the full-capacity case described below.
5. For an animated pickup, confirm the object is reserved when the ability starts, the Inventory changes at `OnAnimatorPickup`, and the ability ends at `OnAnimatorPickupComplete` or its configured duration.
6. Drop an equipped item. Confirm the spawned prefab receives the removed definition and amount, follows its trajectory, cannot be recollected before **Trigger Enable Delay**, and returns the item when collected.
7. For a scene pickup, wait for Respawner and confirm the object returns and can be collected exactly once again.
## Troubleshooting and released-Version-3 limitations
| Symptom | Check | Fix |
| --- | --- | --- |
| Contact does not collect the object | Check for a trigger collider on the Item Pickup GameObject, an enabled Inventory, the collision matrix, the character's main layer, and **Pickup On Trigger Enter**. | Restore the trigger and layer interaction. Enable contact collection, or finish the Pickup ability setup for an input-driven object. |
| The item is collected without the intended animation | Check **Pickup On Trigger Enter**, the Pickup ability's **Start Type**, **Enabled** state, **Allowed Pickups**, and **Pickup Item Definitions**. | Disable contact collection and use an enabled, input-driven Pickup ability whose filter contains the definition. |
| The animation starts but Inventory does not change | **Pickup Event** may be waiting for a missing `OnAnimatorPickup`. | Add the event to the active clip or switch the trigger to duration mode. |
| Inventory changes but Pickup remains active | **Pickup Complete Event** may be waiting for a missing `OnAnimatorPickupComplete`. | Add the completion event or use duration mode. |
| Inventory changes but no held item appears | Check the Character Item prefab, slot, Item Set Rule, **Equip**, group/name, and whether Use or Reload is active. | Complete the Character Item and Item Set setup, correct the exact State name, and retry without the conflicting ability. |
| A full Inventory consumes the world object | Released Version 3.2.0 treats Inventory's `0` return as a successful Item Pickup result, even with **Always Pickup** disabled. | Precheck capacity or use a corrected custom Item Pickup when a full Inventory must leave the object available. |
| One of several Pickup ability filter entries does not animate | In released Version 3.2.0, a nonmatching first **Pickup Item Definitions** entry can stop the later entries from being considered. | Prefer one definition per Pickup ability, or put the matching definition first and verify every pickup. |
| A dropped item can be collected while it is still moving | The generated Dropped Item has Trajectory Object but no Rigidbody, so the reuse delay does not wait for Rigidbody settling. | Increase **Trigger Enable Delay** to cover the flight or add a project-owned landing gate. |
| The model remains but cannot be collected again | **Destroy Delay** is `-1`, so the object is visible but depleted. | Use Respawner, pooling, a positive delay, or an explicit controlled reinitialization. |
## Persistence, pooling, and multiplayer
Item Pickup does not save its depleted state, pending destroy delay, or Respawner timer. Persist the authoritative Inventory and any world-pickup state that must survive loading; otherwise a loaded Inventory can coexist with a restored copy of the collected object.
Pooled pickups return through the Opsive object pool and initialize when reused. Non-pooled scene pickups deactivate, allowing Respawner to return them. Keep one deliberate lifetime path and verify that it restores the pickup only once.
In a supported multiplayer build, the authoritative peer owns the Inventory change and network spawn or removal. Core Item Pickup does not provide transport or resolve simultaneous collection by itself. Verify that the installed integration accepts one collection, replicates the Inventory result, and removes the world object for every peer.
## Related tasks
- [Object Pickup](https://opsive.com/support/documentation/ultimate-character-controller/objects/object-pickup/) explains the shared trigger, feedback, depletion, pooling, and lifetime behavior.
- [Complete Item Pickup workflow](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-pickup/) covers the Inventory and Character Item side in more depth.
- [Inventory](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/inventory/) configures capacities and runtime item ownership.
- [Item Creation](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-creation/) creates the Item Definition and Character Item used by an equippable pickup.
- [Character Item](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/) configures the held object and its **Drop Prefab**.
- [Item Set Rules](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-set-rules/) determine which collected items form valid loadouts.
- [Pickup ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/detect-object-ability-base/pickup/) configures detection, input, filters, and animation timing.
- [Drop](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/drop/) removes an item and initializes its dropped prefab.
- [Trajectory Object](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/) controls dropped-object motion.
- [Respawner](https://opsive.com/support/documentation/ultimate-character-controller/spawn-system/respawner/) controls when a scene pickup returns.
- [Object Manager](https://opsive.com/support/documentation/ultimate-character-controller/objects/objects/) creates the starting prefab.
## Developer reference
`ItemPickup` derives from `ItemPickupBase`, which derives from `ObjectPickup`. `GetItemDefinitionAmounts()` and `SetItemDefinitionAmounts(...)` expose the pickup contents; Inventory uses this surface to populate a dropped prefab.
`DoItemPickup(...)` owns reservation and depletion, while `DoItemIdentifierPickup(...)` wraps the Inventory transfer with `OnItemPickupStartPickup` and `OnItemPickupStopPickup`. A completed object sends `OnObjectPickedUp(ObjectPickup pickup)`. Successful Inventory additions send `OnInventoryPickupItemIdentifier`; a spawned Character Item also sends `OnInventoryPickupItem`.
See [Events](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/) for registration and cleanup patterns.
---
# Trajectory Object
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/)
Trajectory Object moves a launched object along a kinematic arc and can simulate the same path for a preview line. It owns movement, collision casts, reflection, settling, and basic surface feedback; the firing or throwing module and a derived Projectile, Grenade, or Shell own gameplay impact, lifetime, and removal.
## Before you begin
- Decide whether the object is fired by a Shootable Action, thrown by a Throwable Action, spawned by a Magic Action, or initialized from project code.
- Prepare a visible model for Projectile, Grenade, or Shell. Object Manager creates the particle-based Magic Projectile without a supplied model.
- Choose the layers that can be hit and whether the moving object should stop, bounce, pass through, or report a gameplay impact.
- Use a solid Sphere Collider, Capsule Collider, or Box Collider on the Trajectory Object GameObject when the collision cast should match its volume. Without a supported solid collider, Trajectory Object uses a raycast from its transform.
## Choose a trajectory object
| Goal | Built-in type | Runtime owner | Starting behavior |
| --- | --- | --- | --- |
| Fire an arrow, rocket, or moving bullet | [Projectile](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/projectile/) | Shootable Action's Projectile Shooter, Magic Spawn Projectile, or project code | Projectile adds impact data, destruction, pooling, and a `10`-second **Lifespan**. |
| Throw and cook an explosive | [Grenade](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/grenade/) | Throwable Action plus the optional Throwable Grenade module | Grenade adds a `5`-second **Lifespan** and optional **Pin**. The fuse starts only when `StartCooking` is called. |
| Eject a cosmetic casing | [Shell](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/shell/) | A Shootable Action's Shell Effect or project code | Shell uses a `10`-second **Lifespan**, **Persistence** `1`, shrinking removal, and extra random spin on hard impacts. |
| Send a Magic Action impact through a moving effect | [Magic Projectile](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/magic-projectile/) | Magic Action's Spawn Projectile Cast Effect | Object Manager creates a Particle System and Projectile. The Cast Effect's **Speed** starts at `1`. |
Use plain Trajectory Object for a custom kinematic prop or a preview simulator only when another system deliberately owns its impact result and lifetime.
## Build the prefab
1. Open **Tools > Opsive > Ultimate Character Controller > Object Manager**.
2. In **Object Builder**, enter a **Name**.
3. Select **Projectile**, **Grenade**, **Shell**, or **Magic Projectile** under **Object Type**.
4. For Projectile, Grenade, or Shell, assign the visible model to **GameObject**. Magic Projectile does not show this field.
5. For Magic Projectile, enable **Magic Particle Collisions** only when individual Particle System particles should invoke Magic impacts.
6. Select **Build Object**, choose a path under the project's `Assets` folder, and open the generated prefab.
7. Adjust the generated collider to match the visible object, then configure the shared Trajectory Object and type-specific fields.
8. Assign the prefab to the matching Shootable, Throwable, or Magic module and configure that module's origin, velocity, layer change, and impact result.
Object Manager creates these starting components:
| Object Type | Generated result |
| --- | --- |
| **Projectile** | Rigidbody, Capsule Collider, and Projectile. |
| **Grenade** | Rigidbody, Capsule Collider, and Grenade, with **Destroy On Collision** disabled. |
| **Shell** | Rigidbody, Capsule Collider, Shell, and a 3D Audio Source with **Spatial Blend** `1` and **Max Distance** `10`. |
| **Magic Projectile** | Rigidbody, Particle System, and Projectile, with **Collision Mode** serialized as **Ignore**. **Magic Particle Collisions** additionally adds Magic Particle. |
The Rigidbody does not drive the arc. Trajectory Object disables Rigidbody gravity and makes it kinematic; Projectile-derived types and Shell also freeze its constraints.
## Configure the shared trajectory
These are the released Version 3 starting values that most often change a result:
| Field | Default | What to decide |
| --- | --- | --- |
| **Initialize On Enable** | Disabled | Leave this off when a Shootable, Throwable, or Magic module supplies launch data. Enable it only for a self-starting object that should initialize with zero velocity. |
| **Mass** / **Start Velocity Multiplier** | `1` / `1` | Runtime divides the supplied launch velocity by both values. Keep both positive; values above `1` reduce initial speed. |
| **Gravity Magnitude** / **Speed** | `9.8` / `1` | Gravity follows the owning character's gravity direction when one exists. Speed scales each movement step. |
| **Rotation Speed** / **Damping** / **Rotation Damping** | `5` / `0.1` / `0.1` | Tune settling and visual rotation. **Rotate In Move Direction** starts disabled. |
| **Settle Position Threshold** / **Settle Rotation Threshold** | `0.01` / `0.01` | Movement and rotation stop when their values fall below these thresholds. Nonpositive values are not a never-settle mode in released Version 3. |
| **Sideways Settle Threshold** / **Start Sideways Velocity Magnitude** | `0.75` / `3` | Choose when a Capsule or Box settles on its side and when it begins rotating toward that resting pose. |
| **Impact Layers** | All except Ignore Raycast, Water, SubCharacter, Overlay, and Visual Effect | Restrict the physics queries to intended surfaces and targets. Trigger colliders are ignored. |
| **Collision Mode** / **Reflect Multiplier** | **Reflect** / `1` | Choose stop, bounce, random bounce, or pass-through behavior. |
| **Surface Impact** / **Force Multiplier** | None / `40` | Add surface feedback and scale forces later applied through `AddForce`. Gameplay damage still belongs to Projectile impact data/actions or the calling item action. |
| **Max Collision Count** / **Max Position Count** | `5` / `150` | Size the collision buffers and cap a displayed curve. Increase only when the scene or preview needs it. |
**Active Audio Clip Set** starts empty, and the **On Collision Event** UnityEvent has no listeners.
## Choose collision and impact behavior
| Collision Mode | Motion after a hit | Use it for |
| --- | --- | --- |
| **Collide** | Stops movement and disables Trajectory Object. A Projectile can parent to an allowed **Sticky Layers** target with uniform scale. | Arrows, rockets, sticky objects, and one-hit projectiles. |
| **Reflect** | Reflects velocity from the hit normal and applies collider material friction plus **Reflect Multiplier**. | Predictable bounces and most thrown objects. |
| **Random Reflect** | Adds a random direction change before reflection. | Local visual effects such as casings; do not use it for authoritative network motion. |
| **Ignore** | Reports the collision but leaves velocity unchanged. | Pass-through queries where another system owns filtering and cleanup. Projectile destruction settings can still remove the object. |
Trajectory Object invokes **On Collision Event**, stops its active audio, applies force to a hit Rigidbody, and spawns **Surface Impact** feedback. Projectile and Grenade then build an `ImpactCallbackContext`, notify their owner, and optionally run **Internal Impact** through their Impact Action Group. A base Trajectory Object does not deal damage by itself.
ProjectileBase also owns **Disable Collider On Impact**, **Destroy On Collision**, **Wait For Particle Stop**, **Destruction Delay**, **Spawned Objects On Destruction**, and the impact-data choice. A spawned Explosion receives the projectile's impact data and damage-source chain.
## Show a trajectory preview
The same simulator can populate an attached Line Renderer. For a Version 3 Throwable Action, keep the preview Trajectory Object on the Character Item and use the **Throwable Visualize Trajectory** Extra module.
1. Add Trajectory Object and Line Renderer to the Character Item or another dedicated preview GameObject.
2. Match **Mass**, **Start Velocity Multiplier**, gravity, speed, damping, collision mode, layers, and collider shape to the live thrown prefab.
3. If the live object uses a Sphere, Capsule, or Box, add the same collider type and dimensions to the simulator. Leave it solid; simulation disables it while drawing the curve.
4. On Line Renderer, disable shadow casting and receiving, assign the line material, leave **Positions** at `0`, and choose a readable width. The legacy example uses `0.15`.
5. In the Throwable Action's Extra Module Group, enable **Throwable Visualize Trajectory** and **Show Trajectory On Aim**. The preview appears only for input-driven Aim and clears when use starts.
The preview is deterministic for a stable start, static colliders, and nonrandom collision behavior. Released Version 3's Throwable preview does not apply Trigger force or add the character's forward velocity even though the live throw does. Tune an exact preview while stationary with a Simple Trigger, or use a custom preview module for charged or moving throws.
## How it runs
1. The caller spawns the object, usually through the Opsive pool, and calls an `Initialize` overload with velocity, torque, owner, and impact context.
2. Trajectory Object resolves the owner's gravity direction and local time scale, enables its supported collider, ignores the owner's colliders initially, starts active audio, and registers with Simulation Manager.
3. Each physics step applies gravity and damping, casts the configured shape along the next movement segment, then moves and rotates the transform.
4. A hit runs the shared collision feedback and the selected collision response. ProjectileBase can additionally run impact actions, stick, delay destruction, spawn effects, and return to a pool.
5. The built-in Projectile launch paths start its lifespan during initialization. Grenade starts its fuse only through `StartCooking`. Shell removes itself after its lifespan or an earlier soft-bounce decision. Plain Trajectory Object has no automatic removal policy.
6. A preview uses the same simulation without moving the live object, writes the resulting positions to Line Renderer, disables its collider, and stops updating until the next simulation.
## Editor checkpoint
Before Play Mode, confirm that:
- the intended derived component and supported solid collider are on the prefab root;
- Rigidbody is present for Projectile, Grenade, and Shell but is not being treated as the movement driver;
- Mass and Start Velocity Multiplier are positive;
- **Impact Layers**, **Collision Mode**, and destruction settings describe one coherent result;
- Projectile or Grenade has valid impact data/actions when it should damage or apply force;
- the caller references the prefab and supplies its origin, launch velocity, layer, and lifetime trigger;
- a Grenade has a caller that starts cooking when its fuse should begin;
- a Magic Particle path has Particle System Collision enabled with **Send Collision Messages** enabled; and
- a visible preview has a Line Renderer, a matching collider/physics setup, and the Version 3 visualization module.
## Verify in Play Mode
1. Fire a Projectile at an included layer and an excluded layer. Confirm only the included hit invokes collision feedback and gameplay impact, then confirm the object returns to its pool on collision or lifespan.
2. Throw a Grenade against the same surface. Confirm it reflects or settles according to its mode, keeps its fuse after the bounce, and spawns the configured destruction result when the cook time expires.
3. Eject several Shells. Confirm each uses local cosmetic motion, shrinks after its lifespan, and that **Persistence** changes whether a soft impact shortens its life.
4. Cast a Magic Projectile. Confirm exactly one intended collision path invokes the Magic Impact group and that the particle, root Projectile, and spawned effects all clean up.
5. Aim a stationary Throwable using a Simple Trigger and compare the displayed line with the landing point. Repeat while moving or charging to evaluate the released-Version-3 preview difference.
6. Reuse every prefab from its pool. Confirm its collider, trail, particle, audio, parent, velocity, impact state, lifespan, and visible scale reset before the next launch.
7. In multiplayer, compare server, owner, and observer. Confirm authoritative Projectile/Grenade results match, and keep Random Reflect/Shell presentation local.
## Troubleshooting and released-Version-3 limitations
| Symptom | Check | Fix |
| --- | --- | --- |
| The object enables but does not move | **Initialize On Enable** is disabled and no firing, throwing, Magic, or project caller initialized it. | Let the owning module initialize it, or enable self-initialization only for a deliberate zero-velocity setup. |
| Launch speed is infinite, invalid, or unexpectedly low | **Mass** or **Start Velocity Multiplier** is zero or large. Released Version 3 divides velocity by their product. | Keep both values positive, normally `1`, and match the preview and live prefab. |
| Setting a settle threshold to `0` does not prevent settling | `Awake` and the public setters coerce nonpositive **Settle Position Threshold** and **Settle Rotation Threshold** values to `0.001`. | Use positive thresholds and a project-specific mover when the object must never settle. |
| A generated Projectile logs a collision-mode warning and stops instead of reflecting | Object Manager leaves Projectile's inherited **Collision Mode** at **Reflect** while **Destroy On Collision** starts enabled. ProjectileBase forces **Collide** during `Awake`. | Set **Collision Mode** to **Collide** explicitly for a one-hit projectile, or disable **Destroy On Collision** and provide a tested alternative lifetime. |
| A generated Magic Projectile does not remain in **Ignore** mode | Object Manager serializes **Ignore**, but the same enabled **Destroy On Collision** guard forces **Collide** at runtime. | Use **Collide** for a one-hit spell. For true pass-through behavior, disable collision destruction and add explicit project-owned cleanup; do not rely on the default combination. |
| Magic Particle collisions log an error or never invoke the Magic impact | **Magic Particle Collisions** adds Magic Particle but does not configure the generated Particle System's Collision module. | Enable Particle System **Collision** and **Send Collision Messages**, then test whether root Projectile and per-particle impacts should both be active. |
| The line and live throw diverge while moving or charging | The Version 3 preview omits Trigger force and character forward velocity. | Tune while stationary with Simple, or implement a custom preview that uses the live launch calculation. |
| The line is missing | Check Line Renderer, its material, the simulator, the matching collider, input-driven Aim, and **Show Trajectory On Aim**. | Restore the components and module, then verify that Aim starts from input before throwing. |
| A mesh-shaped object clips a surface or detects only along its center | Mesh Collider and trigger-only setups are not supported shape casts. | Add a solid Sphere, Capsule, or Box approximation on the Trajectory Object root. |
| Collision feedback runs but no damage occurs | Only shared Trajectory Object feedback is configured. | Use Projectile/Grenade impact data and **Internal Impact**, or let the Shootable, Throwable, or Magic action own the gameplay result. |
| A plain Trajectory Object remains forever | Base Trajectory Object has no lifespan or pool-return behavior. | Use Projectile, Grenade, or Shell, or have the caller return the object explicitly. |
## Saving, pooling, and multiplayer
The prefab stores its physics, impact, audio, curve, and derived-type settings. Current velocity, torque, collision state, platform attachment, pending lifespan/fuse/destruction events, and preview positions are runtime state. Save the durable gameplay result and deliberately respawn or discard active moving objects around a load boundary rather than expecting a flight to resume automatically.
ProjectileBase and Shell return through `ObjectPoolBase`; a supported network build can use `NetworkObjectPool` for authoritative Projectile/Grenade destruction and spawning. Plain Trajectory Object has no pool-return behavior, so its caller owns cleanup.
**Random Reflect** and Shell's random torque are not deterministic across peers. Treat Shell as local visual feedback and keep authoritative hits, damage, explosions, and object removal on the server or owning peer through the installed integration.
## Related tasks
- [Object Manager](https://opsive.com/support/documentation/ultimate-character-controller/objects/objects/) creates the starting prefabs.
- [Shootable Action](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/shootable/) configures hitscan and moving Projectile weapons.
- [Throwable Action](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/throwable/) configures live throw velocity, preview, Grenade cooking, and inventory use.
- [Magic Action](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/magic/) configures Spawn Projectile and Magic impact modules.
- [Explosion](https://opsive.com/support/documentation/ultimate-character-controller/objects/explosions/) configures a spawned area result.
- [Surface System](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/) configures **Surface Impact** feedback.
- [Object Pool](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/object-pool/) explains reusable object ownership.
## Developer reference
`TrajectoryObject` implements `IForceObject`, `IDamageSource`, and `ISmoothedObject`. Its public runtime surface includes `Initialize(...)`, `SimulateTrajectory(...)`, `ClearTrajectory()`, `AddForce(...)`, `Velocity`, `Torque`, `Owner`, and `LineRenderer`.
The base **On Collision Event** UnityEvent receives a `RaycastHit` only for a physical hit. `ProjectileBase` separately exposes the C# `OnImpact` and `OnDestruct` events and notifies an `IProjectileOwner` through `OnProjectileImpact` and `OnProjectileDestruct`. Whether a target receives `OnObjectImpact` depends on the configured Impact Actions; it is not emitted by base Trajectory Object.
Use [Events](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/) for project listeners, and unregister C# or Event System callbacks when a pooled owner is disabled or destroyed.
---
# Grenade
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/grenade/)
A Grenade gives a Throwable Action a timed, physical explosive that can begin cooking while it is still in the character's hand. Use it when the object should follow a trajectory, bounce or settle, and spawn a separate Explosion when its fuse expires.
## Before you begin
- Prepare a visible grenade model and a separate [Explosion](https://opsive.com/support/documentation/ultimate-character-controller/objects/explosions/) prefab for the final area effect.
- Configure a [Throwable Action](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/throwable/) with an enabled Thrower, Ammo, Projectile, and Re-Equipper module.
- Decide whether touching a target should also cause an immediate impact result, or whether all damage should come from the final Explosion.
- Use a solid Sphere, Capsule, or Box Collider on the grenade root. The trajectory casts ignore trigger colliders.
## Build the grenade prefab
1. Open **Tools > Opsive > Ultimate Character Controller > Object Manager**.
2. In **Object Builder**, enter a **Name**, set **Object Type** to **Grenade**, and assign the visible model to **GameObject**.
3. Select **Build Object**, save the prefab under the project's `Assets` folder, and open the generated prefab.
4. Confirm the root has **Rigidbody**, **Capsule Collider**, and **Grenade** components. Object Manager disables **Destroy On Collision** for this object type so the generated grenade can keep moving after a hit.
5. Resize the Capsule Collider to the model, or replace it with a solid Sphere Collider when that better matches a round grenade. The Grenade component makes the Rigidbody kinematic and disables Rigidbody gravity at runtime; Trajectory Object owns the arc.
6. In the Grenade component's trajectory settings, keep **Initialize On Enable** disabled when the Throwable Action will launch the object. **Collision Mode** starts as **Reflect**, so the generated object bounces.
7. Under **Destruction**, keep **Destroy On Collision** disabled and **Destruction Delay** at `0` for a fuse-only result. Add the Explosion prefab to **Spawned Objects On Destruction** and leave its **Probability** at `1` when every cooked grenade should explode.
8. Under the impact settings, configure **Default Impact Damage Data** even when the Explosion owns the visible damage result. Disable **Internal Impact** if a bounce should not run the Grenade's own Impact Action Group.
## Connect the Throwable Action
1. On the Character Item's Throwable Action, assign the prefab to **Spawn Projectile > Thrown Object**.
2. Add **Throwable Grenade** to the action's **Extra** module group. The released Version 3 Item Manager recipe does not add this module automatically.
3. On the Grenade prefab, set **Lifespan**. Its released Version 3 default is `5` seconds.
4. For a removable pin, make the pin a child Transform of the grenade and assign it to **Pin**. A root pin with no parent cannot be detached and restored by the built-in component.
5. In **Throwable Grenade**, leave **Animate Pin Removal** enabled when the animation shows the pin being pulled. Assign **Pin Attachment Location** for each enabled perspective, then synchronize **Remove Pin Event** with `OnAnimatorItemRemovePin`. The trigger waits for that animation event by default; its stored **Duration** is `0.4` seconds when event waiting is disabled.
6. Match the Throwable Action's **Use Event** to the release frame. The fuse starts when item use starts, before this release event, so time spent holding the cooked grenade counts toward **Lifespan**.
The held object and the launched object are the same pooled Grenade instance. Do not add a separate timer to the Throwable Action unless it deliberately replaces the built-in cooking flow.
## Key choices
| Goal | Configure | Result |
| --- | --- | --- |
| Bounce until the fuse expires | **Collision Mode Reflect**, **Destroy On Collision** disabled, **Destruction Delay** `0` | Contact changes the trajectory but does not schedule destruction. |
| Stop on the first surface, then wait for the fuse | **Collision Mode Collide**, **Destroy On Collision** disabled, and include every intended stop surface in **Sticky Layers** | The object stops and attaches at the hit while the cook event remains active. A uniform-scale target outside Sticky Layers forces destruction. |
| Explode immediately on contact | **Collision Mode Collide** and **Destroy On Collision** enabled | The first valid collision destroys the Grenade without waiting for the remaining fuse. |
| Damage only through the final blast | Disable **Internal Impact** and configure the spawned Explosion | Bounces provide trajectory and surface feedback without applying the Grenade's collision Impact Action Group. |
| Damage on contact and at the final blast | Keep **Internal Impact** enabled, configure its Impact Action Group, and configure the Explosion separately | Each path owns an explicit result; test for unintended double damage near the final contact. |
| Keep collider-based interactions after a bounce | Disable **Disable Collider On Impact** | The physical Collider remains enabled after the first impact. The released Version 3 default disables it on impact even when the Grenade continues moving. |
**Impact Layers** decides which colliders the trajectory can hit. **Sticky Layers** matters only in **Collide** mode. A positive **Destruction Delay** schedules destruction after the first collision even if **Destroy On Collision** is disabled, so it is not an extra fuse duration.
## How it runs
1. **Spawn Projectile** takes a Grenade from the pool, initializes its projectile data, attaches it to the held item, and keeps trajectory movement disabled.
2. When the Use ability starts successfully, **Throwable Grenade** calls `StartCooking`. This records the character and Throwable Action as the damage-owner chain and schedules destruction after **Lifespan**.
3. If pin removal is animated, the selected animation-event or duration mode moves the pin to **Pin Attachment Location**. Enabling a reused Grenade restores the pin to its original parent and local pose.
4. At **Use Event**, the Projectile Thrower releases and initializes the trajectory. Hits run shared collision feedback and can run the Grenade's own impact path, while the selected collision mode decides whether motion stops, reflects, or continues.
5. When the cook event expires, the Grenade temporarily moves to Ignore Raycast so its own spawned Explosion does not detect it, then destructs at its current position.
6. Destruction invokes the configured result, passes the Grenade's impact and ownership data to a spawned Explosion, and returns the Grenade through the object or network pool.
## Editor checkpoint
Before Play Mode, confirm that:
- the prefab root has Grenade, Rigidbody, and one supported solid Collider;
- **Initialize On Enable** is disabled and **Mass** plus **Start Velocity Multiplier** are positive;
- **Impact Layers**, **Collision Mode**, **Destroy On Collision**, and **Destruction Delay** describe one coherent contact result;
- **Default Impact Damage Data** is populated and **Internal Impact** matches the intended collision damage;
- **Spawned Objects On Destruction** contains the Explosion with **Probability** `1` for a guaranteed blast;
- the Throwable Action's **Spawn Projectile > Thrown Object** references this prefab;
- **Throwable Grenade** is enabled in the Extra group; and
- an assigned **Pin** has an original parent, a perspective-specific attachment location, and either a matching animation event or duration mode.
## Verify in Play Mode
1. Start using the grenade and keep holding it. Confirm the pin moves at the intended frame and the grenade destructs in the hand after **Lifespan**.
2. Start again and release quickly. Confirm the object leaves the hand at **Use Event**, follows the expected arc, and keeps the remaining fuse time rather than restarting it.
3. Throw against an included surface. Confirm **Reflect** bounces or **Collide** stops as configured, and confirm a fuse-only grenade does not destruct on first contact.
4. Throw against an excluded layer. Confirm the trajectory does not report the contact or run the collision impact path.
5. Let the fuse expire after a bounce. Confirm one Explosion appears at the Grenade's current position, attributes damage to the character/item owner chain, and the Grenade returns to its pool.
6. Reuse the prefab several times. Confirm the pin, collider, visible model, fuse, ownership, and destruction result reset on every throw.
## Troubleshooting and released-Version-3 limitations
| Symptom | Check | Fix |
| --- | --- | --- |
| The Grenade flies forever | **Throwable Grenade** is missing or no project code calls `StartCooking`. Enabling or launching a Grenade does not start its fuse. | Add **Throwable Grenade** to the Extra group, or call `StartCooking` from the system that deliberately owns activation. |
| The use starts with a null-reference error | **Throwable Grenade** is enabled but **Thrown Object** is not a Grenade prefab. | Assign a prefab with the Grenade component, or remove the grenade-specific Extra module. |
| The Grenade explodes on its first bounce | **Destroy On Collision** is enabled or **Destruction Delay** is greater than `0`. | Disable collision destruction and set the delay to `0` for a fuse-only grenade. |
| Reflect changes to Collide and a warning appears | **Destroy On Collision** is enabled with a non-Collide mode. | Disable collision destruction for a bouncing grenade. ProjectileBase forces **Collide** for that conflicting combination during `Awake`. |
| The pin never moves | The Grenade's **Pin** has no original parent, the attachment location is empty, or event waiting is enabled but `OnAnimatorItemRemovePin` never occurs. | Keep the pin as a child, assign **Pin Attachment Location**, then supply the animation event or disable event waiting and use the configured **Duration**. |
| The first bounce stops later collider-based interactions | **Disable Collider On Impact** remains at its enabled default. | Disable that field when the Collider must remain active after contact, then retest the intended collision and pooling behavior. |
| Bounces deal damage when only the blast should | **Internal Impact** and its Impact Action Group are enabled. | Disable **Internal Impact** and keep damage on the spawned Explosion. |
| The Console reports missing impact damage data | **Default Impact Damage Data** is not populated before the Throwable modules initialize the Grenade. | Configure the Grenade's default impact data, including its layers and damage ownership choices. |
| Canceling a cooked use leaves a live fuse | Released Version 3 starts cooking at the beginning of use, but the built-in cancellation path does not cancel that scheduled Grenade event. | Prevent interruption after cooking starts, or add project-owned cancellation that returns or safely destructs the pre-spawned object. |
| No Explosion appears at the end of the fuse | **Spawned Objects On Destruction** has no valid object, its probability is below `1`, or the Explosion prefab is misconfigured. | Assign the tested Explosion prefab, use probability `1` for a guaranteed result, and verify that prefab separately. |
## Saving, pooling, and multiplayer
The prefab stores its trajectory, fuse, pin, impact, and destruction configuration. The remaining cook time, current flight, detached pin, contact state, and active owner are runtime state. Around a save/load boundary, preserve the gameplay consequence you need and deliberately respawn or discard an active Grenade rather than expecting its scheduled fuse and trajectory to resume.
Grenade destruction returns through `ObjectPoolBase`. With the supported multiplayer integration active, destruction and spawned results use the network path and only the server is allowed to explode the ProjectileBase. Configure and test the prefab through that integration; the base component does not by itself synchronize a custom save or networking policy.
## Related tasks
- [Trajectory Object](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/) explains shared movement, collision, settling, and preview settings.
- [Throwable Action](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/throwable/) configures spawning, cooking, release timing, inventory use, and re-equipping.
- [Explosion](https://opsive.com/support/documentation/ultimate-character-controller/objects/explosions/) configures the area damage and effects spawned at destruction.
- [Projectile](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/projectile/) is the corresponding one-hit or lifespan-based moving object.
- [Object Pool](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/object-pool/) explains reusable object ownership.
- [Events](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/) explains project-level event listeners.
## Developer reference
`Grenade` derives from `ProjectileBase`. Its public members are `Lifespan`, `Pin`, `StartCooking(GameObject originator, IDamageSource ownerSource = null)`, and `DetachAttachPin(Transform attachTransform)`. `ProjectileBase` exposes the C# `OnImpact` and `OnDestruct` events and notifies an `IProjectileOwner` through `OnProjectileImpact` and `OnProjectileDestruct`.
`StartCooking` schedules its fuse through the Opsive `Scheduler`; `OnDisable` cancels that event. `DetachAttachPin(null)` restores the cached original parent, position, and rotation. Subscribe and unsubscribe listeners with the pooled object's enable/disable lifecycle, and use [Events](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/) for project-level Event System callbacks.
---
# Magic Projectile
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/magic-projectile/)
A Magic Projectile gives a Magic Action a pooled, trajectory-driven fireball or similar moving effect whose collision can enter the spell's Impact Module Group. In released Version 3, Magic Projectile is an Object Manager recipe that creates a Particle System and the standard `Projectile` component; there is no separate Magic Projectile runtime component.
## Before you begin
- Create a [Magic Action](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/magic/) with an enabled Trigger, Simple Caster, **Spawn Projectile** Cast Effect, and the intended Magic Impact modules.
- Decide whether one root Projectile collision or individual Particle System collisions should report the hit. Do not enable both paths for the same visible fireball unless two impacts are intentional.
- Prepare any Particle System material, shape, emission, and renderer settings required for the effect. Object Manager creates a new Particle System instead of accepting a visible model in this recipe.
- Decide which layers the root trajectory can hit and whether trigger-only targets need a different collision system. Trajectory Object casts ignore trigger colliders.
## Build the projectile prefab
1. Open **Tools > Opsive > Ultimate Character Controller > Object Manager**.
2. In **Object Builder**, enter a **Name** and set **Object Type** to **Magic Projectile**. This object type does not show a **GameObject** field.
3. Leave **Magic Particle Collisions** disabled for a normal one-hit fireball. Enable it only when individual Particle System collisions should invoke the Magic Action's impact path.
4. Select **Build Object**, save the prefab under the project's `Assets` folder, and open the generated prefab.
5. Confirm that the root contains **Rigidbody**, **Particle System**, and **Projectile**. When requested, Object Manager also adds **Magic Particle**. It does not add a Collider.
6. For a thin effect, the no-collider setup uses a raycast from the root along each movement step. Add and size a solid Sphere, Capsule, or Box Collider when the cast should match the fireball's visible volume.
7. Configure the Particle System's material, lifetime, emission, and rendering. ProjectileBase stops the Particle System while idle and plays it when the projectile is initialized.
8. Configure the Projectile as a one-hit Magic collision owner: use **Collision Mode Collide**, keep **Destroy On Collision** enabled, set **Lifespan** for missed shots, and disable **Internal Impact** so only the Magic Action's Impact Module Group applies the gameplay result.
9. Configure **Default Impact Damage Data**. Its layer mask and Surface Impact are supplied to the Magic impact callback; unless **Use Object Impact Layer And Surface** is enabled, they also overwrite the Projectile's **Impact Layers** and **Surface Impact** when the shot initializes.
10. Leave **Wait For Particle Stop** disabled for immediate pool return, or enable it to stop emission and delay destruction by the Particle System's main **Duration** after a hit or lifespan expiry.
Object Manager serializes **Collision Mode** as **Ignore**, but the same generated Projectile keeps **Destroy On Collision** enabled. ProjectileBase treats that combination as invalid during `Awake`, logs a warning, and changes the mode to **Collide**. Set **Collide** explicitly for the normal one-hit setup instead of relying on the contradictory generated values.
## Connect the Magic Action
1. On the Character Item's Magic Action, add **Spawn Projectile** to **Cast Effects Module Group**.
2. Assign the generated prefab to **Projectile Prefab**. The `Projectile` component must be on the prefab root.
3. Leave **Position Offset** and **Rotation Offset** at `(0, 0, 0)` until the effect is aligned with the Caster's first- and third-person **Cast Origin**.
4. Set **Speed** for the scene scale. Its released Version 3 default is `1`; the module launches the Projectile in the current cast direction at that speed.
5. Keep **Parent To Origin** disabled for an independent fireball. Enabling it leaves the moving Projectile under the wand-tip or hand Transform.
6. For one projectile per use, use **Delay** `0`, **Initial Delay** `-1`, and a non-continuous Caster. **Allow Multi Target** starts enabled; disable it unless the Caster should create one projectile for every selected target.
7. In **Impact Module Group**, add **Generic Magic Impact Module** and configure its Conditions plus successful and failed Impact Action Groups. A Projectile hit forwards its complete impact context to every enabled Magic Impact module.
## Choose collision and result ownership
| Goal | Root Projectile | Magic Particle | Cleanup |
| --- | --- | --- | --- |
| One physical fireball hit | **Collide**, **Destroy On Collision** enabled, **Internal Impact** disabled | Do not add it | Collision or the default `10`-second **Lifespan** returns the object. |
| Let the visual finish after the hit | Same as one-hit, with **Wait For Particle Stop** enabled | Do not add it | Movement and emission stop; pool return waits for the Particle System's main **Duration**. |
| Report individual particle collisions | Prevent root hits with deliberate **Impact Layers** and keep a tested lifetime | Add and configure it | Particle System collisions invoke Magic impacts; the root Projectile still owns lifetime and pool return. |
| Run only Projectile-local Impact Actions | Keep **Internal Impact** enabled and leave the Magic Action's Impact group empty | Do not add it | The prefab owns the result, but the Spawn Projectile owner callback still reaches the empty Magic group. |
| Pass through and report root contacts | **Ignore**, **Destroy On Collision** disabled, **Internal Impact** as intended | Do not add it | Add project-owned cleanup. The built-in lifespan does not destroy this `Ignore`/no-destruction/zero-delay combination. |
For a particle-collision spell, enable Particle System **Collision** and **Send Collision Messages**, configure **Collides With**, and follow [Magic Particle](https://opsive.com/support/documentation/ultimate-character-controller/objects/magic-particle/). Object Manager's **Magic Particle Collisions** toggle only adds the component; it does not configure the Particle System Collision module. Keep the root Projectile and particle collision masks separate so exactly one path owns each target encounter.
The Projectile callback reaches the Magic Action first, then **Internal Impact** runs the Projectile's local Impact Action Group. Leaving both configured can apply damage, force, surface effects, or events twice.
## How it runs
1. At the Magic Action's start-cast event, **Spawn Projectile** gets the prefab from `ObjectPoolBase` and positions it from the Caster's origin, cast position, and offsets.
2. The module finds `Projectile` on the root and initializes it with the cast ID, cast direction multiplied by **Speed**, the Magic Action as the damage source, and the prefab's **Default Impact Damage Data**.
3. The Projectile starts its Particle System, schedules its **Lifespan**, enables trajectory simulation, and ignores collisions between any projectile Colliders and the casting character's locomotion Colliders.
4. A root trajectory hit creates an `ImpactCallbackContext`. **Spawn Projectile** forwards that context to `MagicAction.PerformImpact`, which invokes every enabled Magic Impact module. The Projectile then invokes its own group when **Internal Impact** remains enabled.
5. An optional Magic Particle follows a separate route: Unity sends `OnParticleCollision`, and Magic Particle reconstructs a hit before invoking the same Magic Action Impact modules.
6. **Destroy On Collision**, **Destruction Delay**, **Wait For Particle Stop**, or **Lifespan** decides when the root destructs. Destruction restores ignored character collisions and returns the object through the local or network pool.
The Spawn Projectile Cast Effect completes after creating the object; it does not wait for the projectile to hit or expire. Ending or interrupting the Magic Action therefore does not recall an in-flight Projectile. Its prefab owns the remaining lifetime and cleanup.
## Editor checkpoint
Before Play Mode, confirm that:
- the root has Projectile, Rigidbody, Particle System, and an optional supported solid Collider;
- **Initialize On Enable** is disabled, **Mass** and **Start Velocity Multiplier** are positive, and **Lifespan** is greater than `0` for missed shots;
- **Collision Mode**, **Destroy On Collision**, **Destruction Delay**, and **Wait For Particle Stop** describe one coherent cleanup result;
- **Default Impact Damage Data**, its layer mask, and the **Use Object Impact Layer And Surface** choice match the intended targets and surface feedback;
- **Internal Impact** is disabled when the Magic Action's Impact Module Group owns damage and effects;
- **Projectile Prefab** references this prefab and **Speed**, offsets, origin, parenting, delay, and multi-target choices are deliberate;
- the Magic Action has at least one enabled Impact module when a hit should produce a result; and
- when Magic Particle is present, Particle System **Collision** and **Send Collision Messages** are enabled and the root and particle paths cannot double-report the same hit.
## Verify in Play Mode
1. Equip the spell item, expand the Magic Action's **Debug** view, and cast once. Confirm one projectile starts at the current perspective's Cast Origin and travels at the configured **Speed**.
2. Hit a target on an included layer. Confirm the Projectile invokes the Magic Impact modules exactly once, produces the intended damage and surface result, then becomes inactive or finishes its configured particle delay.
3. Cast at an excluded layer and at a trigger-only collider. Confirm neither enters the root trajectory impact path.
4. Miss every target. Confirm the Projectile returns to its pool after **Lifespan** and does not leave a live Particle System in the scene.
5. Switch perspectives and cast while the character moves. Confirm offsets remain aligned and **Parent To Origin** has the intended independent or parented result.
6. Reuse the same pooled prefab repeatedly. Confirm the Particle System, Collider, ignored character collisions, impact state, lifespan, position, and ownership reset for every shot.
7. If using Magic Particle, repeat with the root impact path excluded. Confirm particle collisions invoke the Magic Impact modules once per intended contact and the root still cleans up.
8. With multiplayer enabled, repeat as owner, server, and observer. Confirm the authoritative role owns impact and destruction, remote roles show one visual, and the object returns through the registered network pool.
## Troubleshooting and released-Version-3 limitations
| Symptom | Check | Fix |
| --- | --- | --- |
| The Console says the prefab has no Magic Projectile component | **Projectile Prefab** does not contain `Projectile` on its root. The warning uses the legacy Magic Projectile name, but released Version 3 looks for `Projectile`. | Add Projectile to the root or rebuild with Object Manager's **Magic Projectile** type. |
| The generated prefab logs a collision-mode warning and changes to Collide | Object Manager serialized **Ignore** while inherited **Destroy On Collision** remained enabled. | Set **Collide** explicitly for a one-hit spell. For true pass-through, disable collision destruction and add explicit cleanup. |
| A pass-through projectile never returns after Lifespan | **Ignore**, **Destroy On Collision** disabled, and **Destruction Delay** `0` leave no destruction condition when the lifespan callback runs. | Use a one-hit configuration or return the object from project code. A positive Destruction Delay also starts after the first contact, so it is not a pure miss-only lifetime. |
| Impact modules never run | The prefab lacks root Projectile, the target is outside the active impact layer mask, or the Magic Action has no enabled Impact module. | Restore Projectile, configure **Default Impact Damage Data** and the layer/surface ownership choice, then add the intended Magic Impact module. |
| Damage or effects occur twice | **Internal Impact** and the Magic Impact group are both configured, or Magic Particle and root Projectile both report the same encounter. | Choose one gameplay collision owner and disable or exclude the other path. |
| The fireball only detects a line through its center | Object Manager does not add a Collider to Magic Projectile. | Add a solid Sphere, Capsule, or Box Collider sized to the visible volume. |
| The Projectile hits layers that differ from its Inspector's Impact Layers | **Use Object Impact Layer And Surface** is disabled, so initialization copies the layer mask and Surface Impact from **Default Impact Damage Data**. | Configure the default data to match, or enable the object-level override deliberately. |
| Magic Particle logs that Collision or Send Collision Messages is disabled | Object Manager added Magic Particle but left the Particle System Collision module at its Unity defaults. | Enable both Particle System options and configure **Collides With**, or remove Magic Particle for a root-projectile spell. |
| The projectile follows or rotates with the wand | **Parent To Origin** is enabled. | Disable it for an independent world-space projectile. |
| The particle disappears abruptly on impact | **Wait For Particle Stop** is disabled. | Enable it when the root should stop emission and delay pool return by the Particle System's main Duration, then test the effect's remaining lifetime. |
| Stopping the cast leaves a projectile in flight | Spawn Projectile completes immediately and does not keep ownership for cast-stop cleanup. | Let collision or Lifespan own cleanup, or add a project module that tracks and recalls its spawned objects. |
| A network cast duplicates or loses the projectile | The prefab is not registered with the installed integration's network pool, or custom spawning also runs on observers. | Register and spawn through the supported integration, keep gameplay impact authoritative, and do not independently spawn the same projectile on remote roles. |
## Saving, pooling, and multiplayer
The prefab stores its trajectory, particle, impact, collision, and destruction configuration. The current cast ID, flight, remaining lifespan or destruction delay, ignored collision pairs, active particle state, impact state, and owner are runtime data. Finish or discard an in-flight projectile around a save/load boundary rather than expecting that transient state to resume.
Projectile destruction uses `ObjectPoolBase`. With the supported multiplayer integration enabled, the authoritative Spawn Projectile path uses `NetworkObjectPool`, the server manages the Projectile, and ProjectileBase restricts network destruction to the server. Prefab registration, custom-module synchronization, save behavior, and authoritative damage remain integration or project responsibilities.
## Related tasks
- [Magic Action](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/magic/) configures the Caster, Cast Effect, Impact modules, timing, and animation flow.
- [Trajectory Object](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/) explains the shared movement, collision, and preview settings.
- [Projectile](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/projectile/) documents the underlying one-hit and lifespan behavior.
- [Magic Particle](https://opsive.com/support/documentation/ultimate-character-controller/objects/magic-particle/) configures individual Particle System collisions instead of one root trajectory hit.
- [Impact Actions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/impact-actions/) configure damage, force, surface effects, and callbacks.
- [Object Pool](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/object-pool/) explains reusable object ownership.
- [Events](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/) explains project-level event registration and cleanup.
## Developer reference
The Cast Effect type is `Opsive.UltimateCharacterController.Items.Actions.Modules.Magic.CastEffects.SpawnProjectile`. It implements `IProjectileOwner` and exposes `ProjectilePrefab`, `PositionOffset`, `RotationOffset`, `Speed`, and `ParentToOrigin`. `Owner` is the character, `SourceComponent` is the Character Item Action, and `DamageSource` is the Magic Action.
`OnProjectileImpact` forwards the Projectile's `ImpactCallbackContext` to `MagicAction.PerformImpact`, preserving its Impact Damage Data while replacing the source ID with the cast ID and associating the Magic Action as the source item action. `OnProjectileDestruct` restores the ignored character/projectile Collider pairs.
`Projectile` exposes `Lifespan` and inherits `Initialize`, `Destruct`, `OnImpact`, and `OnDestruct` behavior from ProjectileBase and Trajectory Object. `MagicParticle.Initialize(MagicAction, uint castID)` is a separate optional collision route. The Magic Action publishes `OnMagicItemCast(CharacterItem)` through the Event System when its Cast Effects have cast; impact callbacks such as `OnObjectImpact` depend on the configured Impact Actions. Subscribe and unsubscribe C# or [Event System](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/) listeners with the pooled object's enable/disable lifecycle.
---
# Projectile
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/projectile/)
A Projectile gives a Shootable Action a physical shot with visible travel time, gravity, collision volume, and its own lifetime. Use it for a rocket, arrow, grenade-launcher round, or slow energy bolt; use Hitscan instead when the hit should resolve immediately without a moving object.
## Before you begin
- Create a [Shootable Action](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/shootable/) with **Projectile Shooter**, **Spawn Projectile**, and the intended Shootable Impact modules.
- Prepare a visible projectile model. For a rocket that explodes, also prepare a separate [Explosion](https://opsive.com/support/documentation/ultimate-character-controller/objects/explosions/) prefab.
- Decide whether the Shootable Action's Impact Module Group or the Projectile prefab's **Internal Impact** group owns damage and effects. Configure one primary path to avoid duplicate results.
- Decide whether the shot should destruct, stick, bounce, or pass through on contact before configuring its collision and cleanup.
## Build the projectile prefab
1. Open **Tools > Opsive > Ultimate Character Controller > Object Manager**.
2. In **Object Builder**, enter a **Name**, set **Object Type** to **Projectile**, and assign the visible model to **GameObject**.
3. Select **Build Object**, save the prefab under the project's `Assets` folder, and open the generated prefab.
4. Confirm that the root contains **Rigidbody**, **Capsule Collider**, and **Projectile**. Resize the Capsule Collider to the model, or replace it with a solid Sphere or Box Collider when that better represents the shot. Trigger colliders are ignored by Trajectory Object casts.
5. Set **Collision Mode** to **Collide** for a normal one-hit projectile. Object Manager leaves the inherited **Reflect** value while **Destroy On Collision** starts enabled; ProjectileBase logs a warning and forces that conflicting combination to **Collide** during `Awake`.
6. Keep **Initialize On Enable** disabled when Shootable or Magic modules launch the object. The released Version 3 movement defaults are **Mass** `1`, **Start Velocity Multiplier** `1`, **Gravity Magnitude** `9.8`, **Speed** `1`, and movement plus rotation **Damping** `0.1`.
7. Configure **Impact Layers** and **Surface Impact**, then configure **Default Impact Damage Data**. Unless **Use Object Impact Layer And Surface** is enabled, initialization copies the layer mask and Surface Impact from that default data over the object-level values.
8. For a Shootable Action that owns the gameplay hit, disable **Internal Impact** and configure **Generic Shootable Impact** on the item. Keep **Internal Impact** enabled only when the prefab's own Impact Action Group is an intentional second or alternative result.
9. For a one-hit shot, keep **Destroy On Collision** enabled and set **Destruction Delay** to `0`. **Lifespan** defaults to `10` seconds and removes a missed projectile in this configuration.
10. Add optional prefabs under **Spawned Objects On Destruction**. Use **Probability** `1` for a guaranteed Explosion or effect, and enable **Random Spin** only for a presentation object whose orientation may vary.
ProjectileBase makes the Rigidbody kinematic, disables Rigidbody gravity, and freezes its constraints. Trajectory Object owns the movement; do not tune the Rigidbody as though Unity physics launches the shot.
## Connect the Shootable Action
1. In **Shooter Action Module Group**, add **Projectile Shooter** and make it the first enabled Shooter.
2. In **Projectile Action Module Group**, add **Spawn Projectile** and make it the first enabled Projectile module. Assign the prefab to its **Projectile** field; the `Projectile` component must be on the prefab root.
3. Assign **Fire Point Location** for every enabled perspective. Keep **Use Look Source Position** disabled to spawn there, or enable it for the Look Source position when the current Movement Type does not use independent look.
4. Enable **Fire In Look Source Direction** for crosshair-directed fire. Leave it disabled when the Fire Point's forward direction should aim the shot.
5. Set **Projectile Fire Velocity Magnitude**. Its released Version 3 default is `10`. **Spread** defaults to `0.01`, **Fire Count** to `1`, and **Inherit Character Velocity** is disabled.
6. Keep **Projectile Fired Layer** at **VisualEffect** only when that layer is correct for the project, and choose **Layer Change Delay**. Its default is `0`. The Shooter's **Impact Layers** aim and obstruction-check the shot; the Projectile prefab's impact data and layers control the moving object's actual hits.
7. **Spawn Projectile > Projectile Visibility** defaults to **On Fire**, so the object is created when fired. Choose **On Aim**, **On Reload**, or **Always** only when a loaded arrow or round should be visible before release. **Projectile Start Layer** defaults to Ignore Raycast for that attached state.
8. Add **Generic Shootable Impact** and configure its Conditions plus pass and fail Impact Action Groups. The Projectile Shooter forwards the Projectile's collision context to every enabled Shootable Impact module.
The launch velocity is **Projectile Fire Velocity Magnitude** multiplied by Trigger force, plus the character's forward local velocity when **Inherit Character Velocity** is enabled. Trajectory Object then divides that velocity by the product of **Mass** and **Start Velocity Multiplier** before applying its gravity, speed, and damping.
## Choose the contact result
| Goal | Configure | Cleanup behavior |
| --- | --- | --- |
| Rocket or ordinary one-hit round | **Collide**, **Destroy On Collision** enabled, **Destruction Delay** `0` | The hit invokes impacts, spawns destruction objects, and returns the Projectile immediately. |
| Delay an explosion after impact | **Collide**, **Destroy On Collision** enabled, positive **Destruction Delay** | The Projectile stays until the delay expires; its Collider is disabled on impact by default. |
| Arrow that follows a target | **Collide**, **Destroy On Collision** disabled, include the target in **Sticky Layers**, and use a positive **Destruction Delay** or project cleanup | A uniform-scale target becomes the parent. The first hit cancels the normal Lifespan, so cleanup must be explicit. |
| Bouncing shot | **Reflect** or **Random Reflect**, **Destroy On Collision** disabled | Add project-owned cleanup. The first hit cancels Projectile's Lifespan; a positive Destruction Delay instead counts from that first bounce. |
| Pass-through detector | **Ignore**, **Destroy On Collision** disabled | Add project-owned cleanup and hit filtering. Contacts are reported without changing velocity, but the built-in Lifespan does not destroy this zero-delay configuration. |
| Let a root Particle System finish after stopping emission | **Wait For Particle Stop** enabled | On impact or Lifespan, emission and movement stop and destruction waits for the root Particle System's main **Duration**. This value replaces, rather than adds to, Destruction Delay. |
**Sticky Layers** is used only in **Collide** mode. A uniform-scale hit outside that mask forces destruction even when **Destroy On Collision** is disabled. A nonuniform target cannot become the parent, so a stopped arrow will not follow it.
**Disable Collider On Impact** starts enabled. That suits a one-hit or stuck shot. Disable it for a bouncing or pass-through design only when later Collider-based interactions must remain active; the trajectory simulator continues using its cached shape for casts.
## How it runs
1. **Spawn Projectile** obtains the prefab from `ObjectPoolBase` at fire time, or prepares it earlier when **Projectile Visibility** shows a loaded object.
2. Projectile Shooter reads the current clip round, calculates the Fire Point and direction, and obtains the object from Spawn Projectile. A pre-spawned object is linecast from the Look Source to prevent separate first-person arms from placing it through an obstruction.
3. The Shooter changes the hierarchy to **Projectile Fired Layer** after **Layer Change Delay**, then initializes the root Projectile with velocity, Trigger force, Shootable Action ownership, and the prefab's Default Impact Damage Data.
4. Projectile schedules **Lifespan**, enables its Collider and trajectory simulation, starts active audio or particles, and ignores its owner's hierarchy during trajectory casts.
5. A hit runs shared collision and surface feedback. Projectile Shooter forwards the context to the Shootable Action's Impact Module Group; ProjectileBase then runs its local group when **Internal Impact** is enabled.
6. The first hit cancels the scheduled Lifespan. Collision mode changes movement, while destruction settings decide whether and when the object spawns its configured results and returns through the local or network pool.
7. A shot that never hits reaches **Lifespan**. With **Destroy On Collision** enabled, this uses the same destruction path without a RaycastHit and returns the object.
## Editor checkpoint
Before Play Mode, confirm that:
- Rigidbody, Projectile, and one supported solid Collider are on the prefab root;
- **Initialize On Enable** is disabled and **Mass**, **Start Velocity Multiplier**, and **Lifespan** are positive;
- **Collision Mode**, **Sticky Layers**, **Destroy On Collision**, **Destruction Delay**, and **Wait For Particle Stop** form one coherent contact and cleanup policy;
- **Default Impact Damage Data**, its layer mask, and **Use Object Impact Layer And Surface** match the intended targets and feedback;
- **Internal Impact** is disabled when Generic Shootable Impact owns damage and effects;
- Projectile Shooter and Spawn Projectile are the first enabled modules in their groups, and the **Projectile** field references this prefab;
- every perspective has a valid **Fire Point Location**, and look direction, velocity, fired layer, spread, Fire Count, and inherited velocity are intentional; and
- a pre-spawned projectile has the correct visibility, start layer, reload attachment, and animation-event or duration timing.
## Verify with a firearm in Play Mode
1. Equip the firearm or launcher, expand the Shootable Action's **Debug** section, and fire one round. Confirm one Projectile appears at the active perspective's Fire Point and the clip decreases by one.
2. Compare Fire Point direction with **Fire In Look Source Direction** enabled and disabled. Confirm velocity, Trigger force, character movement inheritance, spread, and gravity produce the intended path.
3. Hit a target on an included layer. Confirm Generic Shootable Impact runs exactly once, applies the intended damage and surface result, and the Projectile follows its one-hit, delayed, or sticky policy.
4. Fire at an excluded layer and a trigger-only collider. Confirm the moving Projectile does not report those contacts even when the Shooter's aiming mask includes nearby scenery.
5. Miss every target. Confirm the Projectile returns to its pool after **Lifespan**.
6. Test an arrow against a uniform moving target and a nonuniform target. Confirm only the supported target becomes its parent, and verify the explicit delayed or project-owned cleanup.
7. Reuse the same prefab repeatedly. Confirm its Collider, parent, layer, particles, trail, impact state, ownership, position, and lifespan reset before every shot.
8. With multiplayer enabled, repeat as owner, server, and observer. Confirm one authoritative impact and destruction result, one remote visual, and correct network-pool return.
## Troubleshooting and released-Version-3 limitations
| Symptom | Check | Fix |
| --- | --- | --- |
| The projectile is null, does not move, or throws when fired | Projectile Shooter is paired with Basic Projectile, **Spawn Projectile > Projectile** is empty, or the prefab lacks `Projectile` on its root. | Pair Projectile Shooter with Spawn Projectile, assign the prefab, and keep Projectile on the root. |
| A generated Projectile logs a collision warning and changes to Collide | Object Manager left **Collision Mode Reflect** while **Destroy On Collision** starts enabled. | Set **Collide** explicitly for a one-hit shot. Disable collision destruction only with a tested alternative cleanup policy. |
| The shot hits the wrong layers | Shooter **Impact Layers** are being treated as the flight collision mask, or prefab **Impact Layers** are overwritten at initialization. | Use the Shooter mask for aiming and pre-spawn obstruction; configure **Default Impact Damage Data** and **Use Object Impact Layer And Surface** for the moving Projectile. |
| Damage or effects occur twice | Generic Shootable Impact and Projectile **Internal Impact** both contain gameplay actions. | Choose one result owner, normally Generic Shootable Impact, and disable the other path. |
| `OnObjectImpact` never arrives | The legacy workflow assumed every collision emitted the event. Released Version 3 sends it only when a configured Impact Action, such as Impact Event, invokes it. | Add the appropriate Impact Action and enable its source or target callback. Use Projectile's C# `OnImpact` or **On Collision Event** for direct collision observation. |
| An arrow disappears instead of sticking | **Destroy On Collision** is enabled, the target layer is outside **Sticky Layers**, or Collision Mode is not Collide. | Disable collision destruction, use Collide, include the target layer, and test its scale and parenting. |
| A stuck arrow or bouncing shot never disappears | Its first hit canceled Projectile's Lifespan and no destruction event was scheduled. | Give a stuck arrow a positive Destruction Delay, or add project-owned cleanup. For a timed bounce independent of first contact, use project-owned cleanup rather than Destruction Delay. |
| A stopped arrow does not follow the moving target | The target Transform has nonuniform scale, so ProjectileBase does not parent to it. | Use a uniform-scale attachment transform or handle attachment in project code. |
| The first bounce disables later collider interactions | **Disable Collider On Impact** remains enabled. | Disable it for a tested multi-contact setup when the Collider itself must remain active. |
| A pass-through Projectile never returns after Lifespan | **Ignore**, **Destroy On Collision** disabled, and zero Destruction Delay leave no destruction condition; any earlier contact also canceled Lifespan. | Return it from project code or use a one-hit configuration. A positive delay starts from the first contact, not from launch. |
| A spawned Explosion or effect is missing | **Spawned Objects On Destruction** is empty, its probability is below `1`, or destruction never occurs. | Assign the tested prefab, use probability `1` for a guaranteed result, and verify the Projectile's cleanup path. |
| A delayed Explosion appears at the old impact point | Destruction was scheduled from a collision before the target moved. Released Version 3 retains that original `RaycastHit` point and normal. | Use immediate destruction for that result, or implement project cleanup that spawns from the Projectile's current Transform. |
| **Wait For Particle Stop** does not preserve a child effect | ProjectileBase searches only the Projectile root for Particle System and waits its main Duration; child systems and Trail Renderer lifetime are not included. | Put the coordinating Particle System on the root or use project-owned effect cleanup. |
| **Projectile Enable Delay After Other Use** has no effect | Projectile Shooter serializes the default `0.4` field but does not read it in released Version 3. | Coordinate dual-item timing with Use Rate, animation events, or project code. |
| Weapon-source conditions fail only for moving projectiles | Projectile Shooter clears the direct Shootable Action reference before **Check Weapon Source Category** and **Check Weapon Source Definition** evaluate. | Avoid those filters unless **Allow Non Weapon Impact** matches the design; use projectile/target conditions or a project-fixed Shooter module. |
| A network shot duplicates or disappears | The prefab is not registered with the network pool or custom spawning also runs on observers. | Register the prefab with the installed integration, keep impacts authoritative, and do not independently spawn the same shot on remote roles. |
## Saving, pooling, and multiplayer
The prefab stores trajectory, collision, impact, destruction, lifetime, particle, and audio configuration. Current position, velocity, parent, ignored owner, remaining lifetime or destruction delay, impact state, and active visual state are runtime data. Save the durable gameplay result and deliberately respawn or discard in-flight projectiles around a load boundary rather than expecting a flight to resume.
Projectile destruction uses `ObjectPoolBase`. With the supported multiplayer integration enabled, Projectile Shooter spawns through `NetworkObjectPool`, non-server local instances defer to the server, and ProjectileBase restricts network destruction to the server. Prefab registration, custom-module replication, save behavior, and authoritative damage remain integration or project responsibilities.
## Related tasks
- [Shootable Action](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/shootable/) configures Shooter, Projectile, ammo, clip, impact, feedback, and reload modules.
- [Trajectory Object](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/) explains shared movement, collision, settling, and preview settings.
- [Impact Actions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/impact-actions/) configure damage, force, surface effects, and callbacks.
- [Damage Processor](https://opsive.com/support/documentation/ultimate-character-controller/objects/damage-processor/) configures project-specific damage rules.
- [Explosion](https://opsive.com/support/documentation/ultimate-character-controller/objects/explosions/) configures an area result spawned on destruction.
- [Magic Projectile](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/magic-projectile/) connects the same runtime Projectile to a Magic Action.
- [Object Pool](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/object-pool/) explains reusable object ownership.
- [Events](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/) explains Event System registration and cleanup.
## Developer reference
`Projectile` derives from `ProjectileBase` and adds `Lifespan`. ProjectileBase exposes `Initialize(...)`, `InitializeProjectileProperties(...)`, `Destruct(...)`, `OnImpact`, and `OnDestruct`. Trajectory Object exposes movement, collision, force, and simulation members.
`ProjectileShooter` implements `IProjectileOwner`. Its `Owner` is the character, `SourceComponent` is the Character Item Action, and `DamageSource` is the Shootable Action. `OnProjectileImpact` associates the collision with the Shootable Action and invokes `ShootableAction.OnFireImpact`; its `OnProjectileDestruct` callback is intentionally empty.
Base **On Collision Event** is a UnityEvent receiving the physical `RaycastHit`. `OnObjectImpact` is an Opsive Event System callback produced only by configured Impact Actions. Spawn Projectile also publishes `OnShootableWeaponShowProjectile(GameObject, bool)` when a loaded projectile is shown or hidden. Subscribe and unsubscribe C# or [Event System](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/) listeners with the pooled object's lifecycle.
---
# Shell
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/shell/)
Shell creates a cosmetic casing that ejects from a Shootable Action, follows a small kinematic arc, bounces, settles, and returns to the object pool. Use it for firearm feedback, not for the fired round, ammo state, damage, or another authoritative gameplay result.
## Before you begin
- Create or select a [Shootable Action](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/shootable/). The standard Shootable recipe already includes **Shell Effect** in its **Fire Effects Module Group**.
- Prepare a small casing model with its pivot and scale suitable for a solid Capsule, Sphere, or Box Collider.
- Make sure every enabled item perspective has a visible object and a transform where the casing should appear.
- Decide whether impacts need [Surface System](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/) feedback. The generated Audio Source does not assign a clip by itself.
Shell is presentation-only. Keep the projectile, impact modules, inventory, and server-authoritative damage responsible for gameplay.
## Build the Shell prefab
1. Open **Tools > Opsive > Ultimate Character Controller > Object Manager**.
2. In **Object Builder**, enter a **Name**, set **Object Type** to **Shell**, and assign the casing model to **GameObject**.
3. Select **Build Object**, save the prefab under the project's `Assets` folder, and open the generated prefab.
4. Confirm that the root contains **Rigidbody**, **Capsule Collider**, **Shell**, and **Audio Source**. Object Manager sets the Audio Source to **Spatial Blend** `1` and **Max Distance** `10`.
5. Resize the Capsule Collider to the casing, or replace it with a solid Sphere or Box Collider when that is a closer fit. Trajectory Object ignores trigger colliders and uses a raycast when it cannot find one of those supported solid shapes.
6. Leave **Initialize On Enable** disabled when **Shell Effect** launches the prefab. Keep **Mass** and **Start Velocity Multiplier** at their released Version 3 defaults of `1` unless the effect needs deliberate speed scaling.
7. Keep **Collision Mode** at its default **Reflect** for ordinary casing bounces. Configure **Impact Layers**, optional **Surface Impact**, and the collider's Physics Material for the intended floors and walls.
8. In the **Shell** foldout, start with **Lifespan** `10` and **Persistence** `1`. Lifespan controls normal cleanup. Persistence controls whether a low-speed impact can shorten that remaining life.
9. Leave **Active Audio Clip Set** empty unless the casing needs a sound while it is moving. It is stopped by the first physical hit. Use **Surface Impact** or **On Collision Event** for collision-specific feedback.
The Rigidbody only notifies Unity that the casing is not static; it does not move the casing. Shell makes it kinematic, freezes its constraints, and lets [Trajectory Object](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/) update the transform.
## Connect the Shootable Action
1. Open **Tools > Opsive > Ultimate Character Controller > Item Manager** and select the Character Item with the Shootable Action.
2. Expand the Shootable Action's **Fire Effects Module Group**. Enable **Shell Effect**, or add it if this item was built without the standard Shootable recipe.
3. Assign the generated prefab to **Shell**.
4. Assign **Shell Location** for every enabled perspective. Place each transform at the ejection port and rotate it to give the spawned casing the intended initial orientation.
5. Set **Shell Velocity**. Its default randomized range is `(3, 0, 0)` to `(4, 2, 0)`. These values use the active visible object's local axes, so the default moves mainly along local positive X with some positive Y variation.
6. Set **Shell Torque**. Its default range is `(-50, -50, -50)` to `(50, 50, 50)`.
7. Keep **Shell Eject Delay** at its default `0` for immediate ejection, or use a short tested delay when the casing should appear at a particular frame of the firing animation.
Shell Effect does not have **Inherit Character Velocity**. It transforms only the randomized **Shell Velocity** by the active visible object, so the character's current movement velocity is not added to the casing.
## Choose the presentation
| Goal | Configure | Result |
| --- | --- | --- |
| Consistent firearm ejection | Use a narrow **Shell Velocity** and **Shell Torque** range | Casings leave in a predictable direction with modest variation. |
| More varied brass motion | Widen the velocity and torque ranges, then test the active visible object's axes | Each casing starts differently; hard hits also add random torque. |
| Long-lived floor dressing | Keep **Persistence** at `1` and choose an appropriate **Lifespan** | Soft impacts do not shorten the normal lifetime. |
| Clear busy scenes sooner | Lower **Persistence** | A low-speed impact has a greater chance to move cleanup earlier. |
| Audible contact | Assign **Surface Impact** for the intended surface types | Each valid physical hit can use Surface System feedback. |
| Looping flight sound | Assign **Active Audio Clip Set** | Audio starts on initialization and stops on the first valid physical hit, even when the casing reflects and keeps moving. |
**Shell Location** controls spawn position and orientation, but released Version 3 calculates ejection direction from the active visible object's transform rather than from Shell Location. Rotating only Shell Location therefore does not rotate **Shell Velocity**.
## How it runs
1. When the Shootable Action fires, it invokes every enabled Fire Effects module. Shell Effect schedules ejection using **Shell Eject Delay**.
2. At ejection time, the module resolves the current perspective's **Shell Location** and obtains the prefab from `ObjectPoolBase` at that position and rotation.
3. If the root has a Shell component, the module chooses random velocity and torque values. It converts velocity from the active visible object's local axes to world space and initializes the casing with the character as owner.
4. Trajectory Object resolves the character's gravity direction and local time scale, ignores the owner's hierarchy during its initial collision check, starts active audio, and simulates the supported Collider. It divides the supplied velocity by **Mass** multiplied by **Start Velocity Multiplier**.
5. A physical hit stops active audio, applies optional surface feedback, invokes **On Collision Event**, and reflects according to the Collider materials and **Reflect Multiplier**. A hit above a velocity magnitude of `2` adds random torque.
6. On a lower-speed hit, a random test against **Persistence** can shorten cleanup. A value of `1` never takes this early-removal branch; lower values make it progressively more likely.
7. At **Lifespan**, the casing begins shrinking and returns through `ObjectPoolBase.Destroy` half a second later. A lower-speed early-removal decision first sets the removal time to half a second after that hit, so pool return occurs about one second after the hit. Reuse restores the original scale and enables the Collider.
## Editor checkpoint
Before Play Mode, confirm that:
- Rigidbody, Shell, and one supported solid Collider are on the prefab root;
- **Initialize On Enable** is disabled, **Mass** and **Start Velocity Multiplier** are positive, and **Collision Mode** is **Reflect**;
- **Impact Layers** include the intended floors and walls, while **Surface Impact** and audio are configured only when needed;
- **Lifespan** and **Persistence** match the desired casing count and cleanup rate;
- **Shell Effect** is enabled in Fire Effects and its **Shell** field references this prefab;
- every enabled perspective resolves a valid **Shell Location**;
- the active visible object's local X and Y axes make the configured **Shell Velocity** leave the weapon in the intended direction; and
- **Shell Eject Delay** remains short enough that the same item and perspective are still active when the callback runs.
## Verify with a firearm in Play Mode
1. Equip the firearm while stationary and fire once. Confirm exactly one casing appears at the active perspective's Shell Location and leaves mainly along the visible object's local positive X direction.
2. Fire several times. Confirm **Shell Velocity**, **Shell Torque**, gravity, and hard-impact random torque create controlled variation without spawning inside the weapon or character.
3. Switch between first and third person and fire again. Confirm each perspective uses its own Shell Location and the same Shell prefab.
4. Walk or run while firing. Confirm the casing starts at the moving ejection point but does not add the character's movement velocity. Adjust the local velocity range or use a custom module if movement inheritance is required.
5. Hit an included surface, an excluded layer, and a trigger-only Collider. Confirm only supported included contacts reflect and produce the configured surface or collision-event feedback.
6. Compare **Persistence** `1` with `0` across several low-speed impacts. Confirm `1` keeps the normal Lifespan, while `0` normally schedules the shorter cleanup path.
7. Wait beyond **Lifespan**. Confirm the casing shrinks, returns to the pool, and reappears at full scale with an enabled Collider on the next shot.
8. In a multiplayer test, compare owner and observer. Confirm shell feedback appears where the integration invokes the fire effect, but do not require identical bounce paths or use the casing as an authoritative result.
## Troubleshooting and released-Version-3 limitations
| Symptom | Check | Fix |
| --- | --- | --- |
| No casing appears | **Shell Effect** is disabled, **Shell** is empty, or **Shell Location** does not resolve for the active perspective. | Enable the module, assign the prefab, and assign a location for every enabled perspective. |
| The object appears but does not move | The prefab root does not have Shell. Shell Effect still instantiates the assigned GameObject, but it initializes motion only when it finds that component. | Build or repair the prefab so Shell and a supported solid Collider are on its root. |
| The casing ejects in the wrong direction | **Shell Velocity** is interpreted in the active visible object's local axes, not Shell Location's axes. | Inspect the visible object's local axes and change the velocity range. Use a corrected parent or custom module when the model axes cannot be changed safely. |
| Rotating Shell Location changes orientation but not the path | Released Version 3 uses Shell Location for spawn pose, then uses the active visible object for `TransformDirection`. | Treat Shell Location as the spawn pose and tune velocity against the visible object's axes. |
| Casings trail behind a moving character | Shell Effect does not add character velocity and has no inheritance setting. | Increase the local ejection velocity for presentation, or implement a custom fire-effect module that deliberately adds character velocity. |
| Ejection fails after a delay or perspective change | The scheduled callback is not retained or canceled by Shell Effect, and it resolves Shell Location plus the active visible object when the delay expires. | Keep the delay within the active firing sequence and maintain valid perspective references. Use an animation-timed custom module for a long or cancelable delay. |
| The casing passes through or misses a surface | The Collider is a trigger, the shape is unsupported, **Impact Layers** excludes the surface, or the casing is too small or fast for the configured cast. | Use a solid Sphere, Capsule, or Box Collider sized to the model, include the layer, and test the velocity range. |
| Initial speed becomes invalid or unexpectedly low | **Mass** or **Start Velocity Multiplier** is zero or large. Released Version 3 divides velocity by their product despite the multiplier wording. | Keep both values positive, normally `1`, and tune **Shell Velocity** first. |
| The casing makes no sound | Object Manager added an Audio Source but **Active Audio Clip Set** and **Surface Impact** start empty. | Assign the intended clip set or surface feedback. Use Surface Impact or On Collision Event for bounce sounds. |
| A looping sound stops while the casing is still bouncing | Trajectory Object stops **Active Audio Clip Set** on the first valid physical hit. | Reserve Active Audio for flight, and use collision feedback for later bounce sounds. |
| Casings disappear too early or remain too long | **Persistence** was treated as a settle duration or removal percentage. It is a probability check on lower-speed impacts; Lifespan is still the normal timer. | Use **Lifespan** for the overall maximum and test Persistence statistically with repeated low-speed contacts. |
| Peers show different resting positions | Shell adds random torque and its kinematic trajectory is not synchronized. | Treat casings as local presentation and keep gameplay impacts, ammo, and damage authoritative elsewhere. |
## Saving, pooling, and multiplayer
The prefab stores its trajectory, collision, audio, **Lifespan**, and **Persistence** settings. Shell Effect stores the prefab, velocity and torque ranges, delay, and perspective locations. Current position, velocity, torque, owner, random choices, remaining lifetime, and scale are transient runtime state. Do not save individual active casings; discard them across a load boundary and let later shots create new presentation objects.
Shell uses `ObjectPoolBase` for spawn and return. A supported multiplayer integration can relay the Shootable Fire Effects module invocation so each peer creates presentation locally, but the Shell path does not network-synchronize its position, random torque, collision, or removal. Do not register gameplay listeners that make a Shell collision authoritative.
## Related tasks
- [Shootable Action](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/shootable/) configures firing, ammo, projectiles, fire effects, impacts, and reload.
- [Trajectory Object](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/) explains shared kinematic movement, collision, settling, and preview behavior.
- [Object Manager](https://opsive.com/support/documentation/ultimate-character-controller/objects/objects/) creates the starting casing prefab.
- [Surface System](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/) configures material-specific collision feedback.
- [Audio](https://opsive.com/support/documentation/ultimate-character-controller/audio/) explains shared audio configuration.
- [Object Pool](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/object-pool/) explains reusable object ownership.
- [Events](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/) explains Event System registration and cleanup.
## Developer reference
`Shell` derives from `TrajectoryObject`. It overrides `Awake`, `OnEnable`, `Move`, and `OnCollision`; movement initialization remains the inherited `Initialize(Vector3 velocity, Vector3 torque, GameObject owner)` path. Shell has no damage or ammo interface and exposes no shell-specific runtime event.
`ShellEffect` derives from `ShootableFireEffectModule` and exposes `Shell`, `ShellVelocity`, `ShellTorque`, `ShellEjectDelay`, and `ShellLocation`. `InvokeEffects` schedules `EjectShell`; that callback uses `ObjectPoolBase.Instantiate`, resolves the current perspective, and initializes the root Shell. The scheduled handle is not stored, so the built-in module has no cancellation path for delayed ejection.
Trajectory Object's **On Collision Event** is a UnityEvent receiving the physical `RaycastHit`. Its active-audio, Surface Impact, and owner time-scale behavior are inherited by Shell. Register and unregister project listeners with the pooled object's lifecycle.
---
# Moving Platforms
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/moving-platforms/)
Moving Platform keeps elevators, trains, doors, and other moving surfaces synchronized with the Ultimate Character Controller character. Use it for a waypoint-driven object; use Animator Update when an Animator drives the motion.
## Before you begin
- Prepare the scene and its managers with [Quick Setup](https://opsive.com/support/documentation/ultimate-character-controller/getting-started/quick-setup/).
- Confirm that the project has the required `MovingPlatform` layer in the [Layer Manager](https://opsive.com/support/documentation/ultimate-character-controller/layer-manager/).
- Decide which transform will actually move. Put its visible geometry and solid colliders on that transform.
Set the component GameObject, and any separate child surface collider that the character can stand on, to the `MovingPlatform` layer. The component warns and corrects its own GameObject at runtime, but it does not change child layers.
## Build a waypoint platform
1. Create an empty GameObject to hold the route. Leave this container stationary.
2. Add the platform object and its colliders as a child of the route container.
3. Add the **Moving Platform** component to the platform object. Unity also adds the required Rigidbody; the component configures that Rigidbody for its synchronized movement.
4. Create one GameObject for each destination. Keep these waypoints beside the platform object under the stationary route container, not below the moving object.
5. Position and rotate each waypoint. Place the first waypoint at the platform's starting pose unless the platform should travel there when Play Mode begins.
6. Open **Path** on the Moving Platform component. Add rows and assign each **Transform** in travel order.
7. For each waypoint, optionally set **Delay** and **State**. The state becomes active when that waypoint is the destination and remains active through its delay, until another destination is selected.
8. Choose **Direction** and **Movement Type**, then open **Movement** to set the speed and interpolation.
The Scene view draws the waypoint poses and connecting route. Under **Editor**, enable **Draw Debug Labels** to include the delay and distance labels while tuning the path.
## Choose the route behavior
| Scenario | Movement Type | What it does |
| --- | --- | --- |
| Elevator, shuttle, or sliding door | **Ping Pong** | Travels to the last waypoint, reverses, and follows the same route back. |
| Train or continuously circulating platform | **Loop** | Travels through the list and then takes a direct segment from the last waypoint to the first. |
| Called elevator or scripted destination | **Target** | Follows the waypoint sequence until it reaches **Target Waypoint**, then stops there. |
| Unpredictable destination | **Random** | Selects a waypoint at random after each delay. Use **Random Seed** for a repeatable sequence, or `-1` to leave the random sequence unseeded by this component. |
**Direction** controls whether the route begins by increasing or decreasing the waypoint index. In **Target** mode, choose the direction that leads through the intended intermediate stops.
## Tune movement and rotation
- Start with **Movement Speed** `0.1`, **Movement Interpolation** **Ease In Out**, and **Rotation Interpolation** **Sync To Movement** for a smooth passenger platform.
- Choose **Ease In** or **Ease Out** when only the departure or arrival should be softened. **Ease Out 2**, **Slerp**, and **Lerp** provide alternative path interpolation when the standard easing does not fit the motion.
- **Sync To Movement** blends between waypoint rotations as the platform travels. **Ease Out** and **Custom Ease Out** let the rotation settle independently; the latter reveals **Rotation Ease Amount**.
- Choose **Custom Rotate** for a continuously revolving object and set **Custom Rotation Speed**. This rotation mode also works without waypoints.
- **Max Rotation Delta Angle** limits the rotation applied in one simulation step. Keep `-1` when no limit is required.
Do not animate or otherwise move the same transform independently while the Moving Platform component controls it.
## Start or change the platform through gameplay
Open **Interaction** on the Moving Platform component for these options:
- Enable **Enable On Interact** when the platform should remain stopped until the character activates it. Add an **Interactable** component to the scene object, include Moving Platform in its **Targets**, and configure the character's [Interact ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/detect-object-ability-base/interact/).
- Enable **Change Directions On Interact** when an already-moving platform should reverse. Use this instead of **Enable On Interact**; when both are enabled, starting the platform takes precedence and the interaction does not reverse it.
- Add a trigger Collider and set **Character Trigger State** when standing on the platform should activate a [State System](https://opsive.com/support/documentation/ultimate-character-controller/state-system/) state on the platform. **Character Trigger Layer** determines which colliders count. The first matching collider enables the state and the last one to leave disables it.
The **State** beside each waypoint is a separate route state: it is active while that waypoint is the current destination. Use route states for direction-specific effects and the trigger state for effects that depend on a character being aboard.
## Use Animator-driven motion
When an Animator controls the platform, add **Animator Update** to the animated root instead of Moving Platform. Animator Update advances the Animator through the Ultimate Character Controller simulation so the character and camera receive synchronized motion.
Set the GameObject of each moving surface collider to the `MovingPlatform` layer. Assign **Moving Children** only when the Animator moves child transforms while its root stays in place; list each child whose position and rotation must be smoothed.
## How the character follows the platform
While grounded, Character Locomotion recognizes a surface collider whose hit transform is on the `MovingPlatform` layer and tracks that transform's position and rotation. The character is not reparented, so its own locomotion and jump behavior continue to run normally. The collider the character stands on must move with the same transform hierarchy that Moving Platform or Animator Update synchronizes.
## Verify in Play Mode
1. Enter Play Mode without the character on the platform. Confirm that the platform visits the waypoint positions and rotations in the selected order, pauses for each **Delay**, and follows the expected loop, reversal, target, or random behavior.
2. Watch the component in the Inspector. In the Scene view, the green route line identifies the current destination while the component is enabled.
3. Step onto the platform. The character should remain stable relative to its surface while still accepting movement and jump input.
4. If interaction is enabled, activate the configured Interactable and confirm that the platform starts or reverses according to the selected option.
5. If a waypoint or trigger state is configured, confirm that the state becomes active only during its intended route or occupancy condition.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| The platform does not move. | The **Waypoints** list is empty, contains a missing transform, **Movement Speed** is zero, **Target Waypoint** is already reached, or **Enable On Interact** started the component disabled. | Assign every waypoint, use a positive speed, select a different valid target, or trigger the configured Interactable. A missing waypoint disables the component when Play Mode starts in the Unity Editor. |
| The character jitters, slides, or does not follow. | The moving surface is not on the `MovingPlatform` layer, its collider is outside the synchronized hierarchy, or two systems drive the same transform. | Set up the required layer, move the collider with the synchronized object, and use either Moving Platform or Animator Update as the movement driver. |
| Loop mode takes an unwanted shortcut. | **Loop** connects the last waypoint directly to the first. | Add waypoints along the return route or use **Ping Pong**. |
| Interact starts the platform but never reverses it. | Both **Enable On Interact** and **Change Directions On Interact** are enabled. | Keep only the behavior required for this platform, or switch the option from another script after it starts. |
| A character trigger state never activates. | The platform has no trigger Collider, **Character Trigger Layer** excludes the character collider, or the state name is not configured on the platform. | Add a trigger to the platform's Rigidbody hierarchy, include the character layer, and add a matching state to the Moving Platform component. |
## Related pages
- [Quick Setup](https://opsive.com/support/documentation/ultimate-character-controller/getting-started/quick-setup/)
- [Layer Manager](https://opsive.com/support/documentation/ultimate-character-controller/layer-manager/)
- [Interact](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/detect-object-ability-base/interact/)
- [State System](https://opsive.com/support/documentation/ultimate-character-controller/state-system/)
## Developer reference
`MovingPlatform` implements `IInteractableTarget` and `ISmoothedObject`. Its commonly useful public members include `Waypoints`, `Direction`, `MovementType`, `TargetWaypoint`, `MovementSpeed`, `MovementInterpolation`, `RotationInterpolation`, `CharacterTriggerLayer`, `CharacterTriggerState`, `EnableOnInteract`, `ChangeDirectionsOnInteract`, `NextWaypoint`, and `ActiveCharacterCount`.
### Released defaults
| Inspector area | Default configuration |
| --- | --- |
| **Path** | **Direction** is **Forward**, **Movement Type** is **Ping Pong**, **Target Waypoint** is `0`, and **Random Seed** is `0`. A new waypoint has **Delay** `0` and a blank **State**. |
| **Movement** | **Movement Speed** is `0.1`, **Movement Interpolation** is **Ease In Out**, **Rotation Interpolation** is **Sync To Movement**, **Rotation Ease Amount** is `0.1`, **Custom Rotation Speed** is `(0, 0, 0)`, and **Max Rotation Delta Angle** is `-1`. |
| **Interaction** | **Character Trigger Layer** contains the Character layer, **Character Trigger State** is blank, and both interaction toggles are off. |
| **Editor** | **Gizmo Color** is translucent blue and **Draw Debug Labels** is off. |
At startup, Moving Platform configures its required Rigidbody as kinematic with **Discrete** collision detection and frozen constraints. The Rigidbody reports movement and collisions to Unity; it is not the movement driver.
The component has no dedicated arrival or departure event. For data-driven responses, use the waypoint **State** or **Character Trigger State** fields. Code can inspect `NextWaypoint` and `ActiveCharacterCount`, or set a target at runtime:
```csharp
using Opsive.UltimateCharacterController.Objects;
public void SendPlatformTo(MovingPlatform platform, int waypointIndex,
MovingPlatform.PathDirection direction)
{
if (platform == null || platform.Waypoints == null ||
waypointIndex < 0 || waypointIndex >= platform.Waypoints.Length) {
return;
}
platform.Direction = direction;
platform.MovementType = MovingPlatform.PathMovementType.Target;
platform.TargetWaypoint = waypointIndex;
platform.enabled = true;
}
```
Character Locomotion normally attaches automatically from the grounded `MovingPlatform` layer check. For a special attachment that does not use that grounded check, call `CharacterLocomotion.SetMovingPlatform(transform, true)` and later pass `null` with the override argument to release it.
---
# Layer Manager
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/layer-manager/)
Set up the UCC layers before building characters so movement, targeting, first-person rendering, child colliders, effects, and moving platforms use the intended collision rules.
## Before you begin
The released Version 3 package reserves Unity user-layer indices 26 through 31. Check **Edit > Project Settings > Tags and Layers** before applying the defaults, especially in a project that already has gameplay layers.
Commit or back up `ProjectSettings/TagManager.asset` and the affected prefabs or scenes first. A Unity layer is stored as an index, so renaming or moving a layer can change the meaning of every GameObject and LayerMask that uses it.
## Required layers
| Index | Exact layer name | Main UCC use |
| ---: | --- | --- |
| 26 | `Enemy` | Default target layer for **Enemy Layers**, Crosshairs Monitor, and Assist Aim. |
| 27 | `MovingPlatform` | Marks moving platforms so locomotion and trajectory objects can preserve platform-relative movement. |
| 28 | `VisualEffect` | Keeps projectiles, dropped reload clips, explosions, decals, and other temporary effects out of character and item collision queries. |
| 29 | `Overlay` | Holds first-person arms, items, muzzle flashes, and other objects rendered by the first-person overlay path. |
| 30 | `SubCharacter` | Holds most character children and secondary colliders so they do not interfere with the main locomotion collider. |
| 31 | `Character` | Holds the character root and primary character colliders used by triggers, moving platforms, and character queries. |
These names have no spaces. UCC runtime code uses the fixed indices, while the names make the assignments readable in the Unity Editor.
## Apply the defaults in a new project
1. Open **Edit > Project Settings > Tags and Layers** and confirm that user layers 26 through 31 are empty or already contain the exact UCC names above.
2. Open **Tools > Opsive > Ultimate Character Controller > Setup Manager** and select **Project**.
3. Under **Layers**, select **Update Layers**. A new project can instead use **Update Buttons and Layers** for the Built-in Render Pipeline or **Update Buttons, Layers, and Render Pipeline** for URP or HDRP.
4. Return to **Tags and Layers** and verify all six indices. The update action fills only empty entries; it does not replace a different name already stored in a slot.
5. In **Setup Manager > Scene**, select **Add Managers** under **Manager Setup**. The **Game** GameObject should now contain **Layer Manager**.
6. Create or update the character with the [Character Manager](https://opsive.com/support/documentation/ultimate-character-controller/character/character-creation/). It assigns the character root and primary colliders to `Character`, and most other children to `SubCharacter` while preserving first-person and item-placement objects that need special handling.
Run this project setup before creating characters, items, moving platforms, or trajectory objects. Their builders serialize layer indices and masks when they create those objects.
## Recover occupied layer slots
Do not select **Update Layers** expecting it to replace an existing layer. If any slot from 26 through 31 belongs to another system, choose one of these recovery paths before building UCC content:
### Migrate the existing project layers
This is usually the safer long-term option because UCC can keep its released defaults.
1. Identify every GameObject, prefab, scene, LayerMask, physics query, camera culling mask, and project collision setting that uses the occupied index.
2. Create a replacement user layer in a free index.
3. Reassign the affected objects and masks to that replacement.
4. Rename indices 26 through 31 to the exact UCC names.
5. Reopen representative prefabs and scenes to confirm that no serialized mask still points at the old index.
Version-control the migration as one reviewable change. Renaming a layer does not move the objects that used its index.
### Maintain custom UCC indices
If the existing indices cannot move, embed or otherwise maintain a controlled copy of the Version 3 package and change the custom constants in `Game/LayerManager.cs`. Create matching layer names at the new indices, then rebuild or audit every existing character, item, effect, moving platform, prefab, and serialized LayerMask.
This is an advanced maintenance choice: package updates can restore the released constants, and existing serialized values do not automatically follow a source-code change. Changing only **Character Layer Manager > Character Layer** at runtime is not a complete layer-index migration because other UCC systems also read the static `LayerManager` indices.
## Configure each character's masks
The Character Manager adds **Character Layer Manager** to each character. Its three editable masks answer different questions:
- **Enemy Layers** identifies valid enemies for systems such as Crosshairs Monitor and Assist Aim. Its default is `Enemy` only. Add another project layer here when that layer should also count as a target.
- **Invisible Layers** identifies layers that character, camera, aiming, and crosshairs raycasts should look through. The default contains `TransparentFX`, `Ignore Raycast`, `UI`, `VisualEffect`, `Overlay`, and `SubCharacter`.
- **Solid Object Layers** identifies surfaces that block or support locomotion and related abilities. The default includes every layer except `Ignore Raycast`, `Water`, `UI`, `VisualEffect`, `Overlay`, and `SubCharacter`.
"Invisible" here means ignored by the relevant physics queries; it does not change Renderer visibility. The invisible and solid masks are independent. For example, a transparent object can be ignored by a camera query while still remaining solid for locomotion if the masks deliberately say so.
At runtime, **Character Layer Manager > Character Layer** is derived from the actual layer of the character GameObject during `Awake`. Keep the character root and its primary collider hierarchy consistent instead of using that runtime value to compensate for incorrect project-layer setup.
## Runtime collision rules
The scene **Layer Manager** applies these global `Physics.IgnoreLayerCollision` pairs in `Awake`:
| Layer | Does not collide with |
| --- | --- |
| `VisualEffect` | `Ignore Raycast`, `VisualEffect` |
| `SubCharacter` | `Default`, `VisualEffect` |
| `Overlay` | `Default`, `VisualEffect`, `Enemy`, `SubCharacter`, `Character` |
These are runtime rules; **Update Layers** does not rewrite the collision matrix displayed in Project Settings. **Setup Manager > Scene > Add Managers** places Layer Manager on the **Game** GameObject. If it is missing, Character Layer Manager calls `LayerManager.Initialize()` and creates a fallback **LayerManager** GameObject, but keeping the manager on **Game** makes scene setup explicit and easier to verify.
## Practical scenarios
- **Enemies use an existing project layer:** Keep that layer and add it to each relevant character's **Enemy Layers** mask. Use the reserved `Enemy` layer only where the fixed UCC default is useful.
- **An invisible stair ramp should guide locomotion:** Put it on a layer included in **Invisible Layers** but also included in **Solid Object Layers**. Camera and aim queries can look through it while the character still walks on it.
- **Water should be visible but not ground:** The default solid mask excludes Unity's `Water` layer. Add or remove it only when the game's water geometry should physically support the character.
- **A platform should carry the character:** Add **Moving Platform** to the platform object. The Moving Platform component warns and corrects the layer at runtime, but the prefab should be correct before Play Mode.
- **Ragdoll or model colliders push the main capsule:** Keep secondary character objects on `SubCharacter`; keep the root and primary locomotion colliders on `Character`.
- **First-person arms or weapons interact with world physics:** Verify they use `Overlay` and that the first-person View Type and camera culling masks still use the released overlay index.
## Verify in Play Mode
1. Confirm that **Game** has an enabled **Layer Manager** component and that no unexpected fallback LayerManager GameObject appears.
2. Select the character. Its root and primary collider objects should use `Character`; ordinary model children and secondary colliders should use `SubCharacter` unless a first-person or item component requires another layer.
3. Walk over Default-layer ground, slopes, steps, and any custom ground layer. The character should stay grounded and should not pass through a layer included in **Solid Object Layers**.
4. Step onto a `MovingPlatform` object. The character and a resting trajectory object should preserve platform-relative motion without a layer warning in the Console.
5. Aim at an object included in **Enemy Layers**. Crosshairs or Assist Aim should recognize it; an object outside that mask should not be treated as an enemy.
6. Spawn a projectile, reload clip, muzzle flash, or other effect. `VisualEffect` and `Overlay` objects should not block or push the character.
7. Switch between first- and third-person views when both are available. First-person overlay objects should render through the intended camera path without appearing as world collision.
8. Test respawn and ragdoll. The primary and secondary collider layers should return to their intended states.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| **Update Layers** finishes but a required name is missing. | The target index already contains another layer name. | Resolve the occupied index, then rename it or rerun **Update Layers** after it is empty. Verify all six indices manually. |
| The character falls through ground or cannot move through open space. | **Solid Object Layers** may omit the ground layer or include a non-solid helper/effect layer. | Add real ground layers and remove layers that should not block locomotion. |
| Crosshairs or Assist Aim does not recognize a target. | The target's layer may be absent from **Enemy Layers**. | Add the target layer to the character's Enemy Layers mask or move the target to an included layer. |
| A moving platform does not carry the character. | The platform may not use layer 27 `MovingPlatform`, or that layer may have another name. | Restore the required layer and assign it to the platform prefab. |
| Child or inactive ragdoll colliders interfere with locomotion. | Those objects may use `Default` or `Character` instead of `SubCharacter`, or a custom character query mask may include `SubCharacter`. | Correct the child layers and exclude `SubCharacter` from the relevant collider and solid-object masks. |
| First-person arms or items disappear, render in the world camera, or collide with the character. | Their layer or the View Type culling masks may not use `Overlay`. | Restore layer 29 `Overlay`, update the affected objects, and verify the first-person camera setup. |
| Effects stop projectiles or block movement. | The effect object may not use `VisualEffect`, or a custom mask may include it. | Assign `VisualEffect` and exclude it from the relevant impact or solid masks. |
| A custom layer-index fork breaks after updating UCC. | `LayerManager.cs` constants or serialized masks may have returned to released values. | Reapply the maintained package change and audit existing serialized layers before opening or saving production scenes. |
## Related pages
- [Quick Setup](https://opsive.com/support/documentation/ultimate-character-controller/getting-started/quick-setup/)
- [Character Creation](https://opsive.com/support/documentation/ultimate-character-controller/character/character-creation/)
- [Moving Platforms](https://opsive.com/support/documentation/ultimate-character-controller/moving-platforms/)
- [First Person View Types](https://opsive.com/support/documentation/ultimate-character-controller/camera/view-types/included-view-types/first-person/)
## Developer reference
`Opsive.UltimateCharacterController.Game.LayerManager` exposes the built-in and custom indices through static properties such as `Default`, `IgnoreRaycast`, `Water`, `UI`, `Enemy`, `MovingPlatform`, `VisualEffect`, `Overlay`, `SubCharacter`, and `Character`.
Use `LayerManager.IgnoreCollision(mainCollider, otherCollider)` when a temporary collision exclusion should be tracked by UCC. Later, `LayerManager.RevertCollision(mainCollider)` restores every active collider pair recorded for that main collider. This bookkeeping is separate from the global layer-pair rules installed in `Awake`.
`CharacterLayerManager` exposes `EnemyLayers`, `InvisibleLayers`, `SolidObjectLayers`, and `CharacterLayer`. Its derived `IgnoreInvisibleLayers`, `IgnoreInvisibleCharacterLayers`, and `IgnoreInvisibleCharacterWaterLayers` masks are used throughout movement, camera, aiming, footstep, item, and ability queries.
```csharp
using Opsive.UltimateCharacterController.Character;
using UnityEngine;
public class AddEnemyLayer : MonoBehaviour
{
[SerializeField] private CharacterLayerManager m_CharacterLayerManager;
[SerializeField] private string m_AdditionalEnemyLayer = "Boss";
private void Awake()
{
var layer = LayerMask.NameToLayer(m_AdditionalEnemyLayer);
if (layer >= 0) {
m_CharacterLayerManager.EnemyLayers =
m_CharacterLayerManager.EnemyLayers.value | (1 << layer);
}
}
}
```
---
# Surface System
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/)
Use the Surface System to make the same impact produce material-appropriate feedback: a footstep can sound different on wood and metal, while a projectile can create a different sound, spawned object, or decal on those same surfaces.
## How the system matches an effect
Each result is selected from three project assets:
1. A **Surface Impact** identifies what happened, such as a footstep, projectile hit, melee hit, jump, or landing.
2. A **Surface Type** identifies what was hit, such as wood, metal, dirt, or water. Its **Impact Effects** list pairs each supported Surface Impact with a Surface Effect.
3. A **Surface Effect** is the response recipe. It can spawn objects, choose a decal, play an **Audio Config** or AudioClip, and temporarily activate a named state on the hit object.
When an impact supplies a `RaycastHit`, Surface Manager looks for a **Surface Identifier** associated with the hit collider first. If that does not provide a type, the manager tries a mapped simple texture, a mapped texture from a multi-material mesh or UV region, and then the dominant terrain texture. Its **Fallbacks** can supply a missing Surface Impact or Surface Type.
Configure surface assets and identifiers before entering Play Mode. Surface Manager caches collider, renderer, texture, and impact-to-effect lookups, so changing those relationships after they have been detected is not a reliable runtime workflow.
## Choose your route
- [Surface Manager](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-manager/) explains scene-wide texture mappings, terrain detection, the main texture property, and fallbacks.
- [Surface Impacts](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-impacts/) explains the identity asset assigned by a footstep, item, ability, or other impact source.
- [Surface Types](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-types/) explains the material asset and its **Impact Effects** mappings.
- [Surface Effects](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-effects/) explains the spawned objects, decals, audio, randomness, and optional state response.
- [Surface Identifiers](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-identifiers/) is the recommended route for assigning a Surface Type directly to a collider or scene prefab.
- [Decal Manager](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/decal-manager/) covers the scene decal limit, weathering, fadeout, and placement rejection at exposed edges.
- [Character Foot Effects](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/character-foot-effects/) covers footstep detection and footprint placement on a UCC character.
- [Advanced Surface System Topics](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/advanced-surface-system-topics/) covers cached data, atlases, multiple materials, static renderers, terrain, and other detection limitations.
## Set up a surface response
1. Open **Tools > Opsive > Ultimate Character Controller > Setup Manager**.
2. Select the **Scene** tab and choose **Add Managers** under **Manager Setup**. Confirm that the scene's **Game** GameObject has **Surface Manager** and **Decal Manager**. The setup also adds the shared Object Pool used by spawned effects.
3. Create an impact identity with **Assets > Create > Opsive > Ultimate Character Controller > Surface Impact**. Name it for the cause, such as `Footstep` or `Bullet Hit`; the asset has no settings of its own.
4. Create the feedback recipe with **Assets > Create > Opsive > Ultimate Character Controller > Surface Effect**. Add the audio, spawned objects, or decal needed for this one impact-and-material combination.
5. Create the material identity with **Assets > Create > Opsive > Ultimate Character Controller > Surface Type**. In **Impact Effects**, add the Surface Impact and the Surface Effect that should respond to it.
6. Select the scene object or reusable prefab that owns the hit collider, add **Surface Identifier**, and assign the **Surface Type**. **Allow Decals** is enabled by default; disable it when decals should not attach to this object.
7. Assign the same Surface Impact asset to the feature that causes the hit. For example, assign a footstep impact to **Character Foot Effects**, or assign the appropriate impact to the item action, projectile, jump, or fall setting that produces the hit.
8. Save the assets, prefab, and scene, then verify the complete pairing in Play Mode.
Repeat the **Impact Effects** mapping on every Surface Type that should respond to that cause. A `Bullet Hit` impact can therefore select a wood effect on a wood type and a metal effect on a metal type without changing the projectile.
## Key choices by scenario
| Scenario | Recommended configuration |
| --- | --- |
| Most props and level pieces | Add **Surface Identifier** and assign one **Surface Type**. This direct lookup is predictable and avoids texture analysis. |
| Several objects share a texture | Add the texture under Surface Manager's object-surface list and pair it with a Surface Type. Keep the direct identifier route for exceptions. |
| One atlas contains several materials | Map the same texture more than once and restrict each mapping with its **UV** rectangle. Review the static-object and collider limitations before committing to this layout. |
| Terrain uses several layers | Add each terrain layer's diffuse texture to the corresponding object-surface mapping. Surface Manager chooses the dominant texture at the hit position. Enable **Detect Terrain Tree Textures** only when tree detection is required because it performs extra work. |
| Character footsteps and footprints | Assign a footstep Surface Impact to **Character Foot Effects** and choose **Body Step**, **Trigger**, **Fixed Interval**, or **Camera Bob** for the character and perspective. The component raycasts below the detected footstep and asks Surface Manager to spawn the matched effect. |
| Projectiles, melee, jumps, and landings need different feedback | Give each cause its own Surface Impact, then map those impacts independently on every relevant Surface Type. Do not encode the hit material into the impact name. |
| Unknown impacts or surfaces still need feedback | Configure **Fallback Surface Impact** and **Fallback Surface Type** on Surface Manager. **Fallback Allow Decals** is enabled by default; disable it when an approximate match could place an unsuitable decal. |
| A busy scene accumulates decals | Decal Manager starts with **Decal Limit** `100`, **Weathered Decal Limit** `20`, and **Remove Fadeout Speed** `10`. Tune those limits for the scene. Lower **Allowed Decal Edge Overlap** on the Surface Effect when decals must sit farther inside a surface edge. |
## Verify in Play Mode
1. Place two colliders with different Surface Types, such as wood and metal, and map the same Surface Impact to a visibly or audibly distinct Surface Effect on each type.
2. Trigger the impact on the first collider. Confirm that only the effect mapped by that collider's Surface Type plays at the hit point.
3. Trigger the same impact on the second collider. The impact source should remain unchanged while the sound, spawned object, or decal changes with the Surface Type.
4. If the Surface Effect includes decals, confirm **Allow Decals** controls the identified object and that decals near an exposed edge are rejected according to **Allowed Decal Edge Overlap**.
5. If the Surface Effect includes several clips, objects, or decals, repeat the impact and confirm the configured spawn probabilities and audio or decal selection behave without creating more feedback than intended.
6. Test one missing assignment deliberately. Confirm the configured **Fallbacks** provide the expected approximate response, or that no effect is spawned when no valid pair exists.
7. For footsteps, walk across the boundary between the two surfaces. Each detected step should follow the surface beneath the foot, and footprints should appear only where the identified surface and Surface Type permit them.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| No effect plays. | The impact source has no Surface Impact, the detected Surface Type has no matching entry in **Impact Effects**, or the entry has no Surface Effect. | Assign the same Surface Impact asset at the source and in the Surface Type mapping, then assign a Surface Effect to that pair. |
| Every object produces the same effect. | Surface Manager is using **Fallback Surface Type**, or the objects share a texture mapping and have no direct identifiers. | Add **Surface Identifier** to each exception and assign the intended Surface Type. Temporarily clear the fallback while testing detection. |
| A Surface Identifier appears to be ignored. | It is not associated with the hit collider, has no **Surface Type**, or the collider relationship changed after the manager cached it. | Put the identifier on the collider object or a stable related parent/child, assign its type before Play Mode, and restart Play Mode after hierarchy changes. |
| Texture-based detection fails. | The texture is absent from Surface Manager, **Main Texture Property Name** does not match the shader, or the mesh/material arrangement cannot provide the hit material. | Add the exact texture, use the shader's main texture property, or use a Surface Identifier. See the advanced limitations for atlases, static renderers, and multiple materials. |
| A decal does not appear. | **Allow Decals**, **Fallback Allow Decals**, or the matched surface/effect prevents it; the edge test may also reject the placement. | Enable decals only on the intended route, verify the effect has a decal prefab, and test farther from an edge before adjusting overlap. |
| A decal is stretched or does not follow a moving object. | The target has non-uniform scale. Decal Manager parents decals to uniformly scaled targets and keeps other decals under the manager. | Use uniform scale on moving decal receivers, or disable decals for that object. |
| Footsteps are missing or mistimed. | **Footstep Mode**, feet, movement requirements, intervals, or the footstep Surface Impact do not match the character. | Choose the mode for the rig and perspective, assign the footstep impact, and tune the mode-specific fields while observing movement in Play Mode. |
| Edits made during Play Mode do not change later hits. | Surface Manager already cached the collider, texture, or impact mapping. | Stop Play Mode, make the asset or hierarchy change, and start a fresh test. |
## Related tasks
- [Quick Setup](https://opsive.com/support/documentation/ultimate-character-controller/getting-started/quick-setup/)
- [Item Actions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/)
- [Fall](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/fall/)
- [State System](https://opsive.com/support/documentation/ultimate-character-controller/state-system/)
## Developer reference
The released Version 3 surface types are in `Opsive.UltimateCharacterController.SurfaceSystem`. Gameplay code normally calls a static `SurfaceManager.SpawnEffect` overload with a `RaycastHit`, Surface Impact, gravity direction, time scale, and originator. Overloads can provide a collider explicitly or add footprint direction and flip state. The method returns `true` only when it resolves and spawns a Surface Effect.
With a Surface Manager component reference, `GetSurfaceType(RaycastHit, Collider)` returns the detected Surface Type, and `GetSurfaceEffect(RaycastHit, Collider, SurfaceImpact, ref SurfaceType, ref bool)` exposes both the resolved type and whether the decal route remains allowed. `SurfaceIdentifier` exposes writable `SurfaceType` and `AllowDecals` properties, but set them before detection because the manager caches results.
`CharacterFootEffects.TriggerFootStep(Transform, bool)` supports explicit trigger-driven placement, while its virtual `FootStep(Transform, bool)` performs the ground raycast and forwards the result to Surface Manager. `SurfaceEffect.Spawn` and `SpawnFootprint` are virtual extension points for a custom response. `DecalManager.Spawn` and `SpawnFootprint` are the lower-level static decal entry points.
The built-in Surface System does not publish a dedicated surface-impact event. Built-in consumers such as trajectory objects, item impact actions, Jump, Fall, and Character Foot Effects call Surface Manager directly. A Surface Effect can instead configure **State Name** and **State Disable Timer** to activate a [State System](https://opsive.com/support/documentation/ultimate-character-controller/state-system/) state on the hit object; a timer value of `-1` leaves deactivation to another system.
---
# Surface Manager
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-manager/)
Use Surface Manager to turn a hit collider, material texture, or terrain layer into a Surface Type, then resolve the Surface Effect that matches the incoming Surface Impact. This lets one bullet, footstep, or landing source produce different feedback on wood, metal, dirt, and other materials without placing a Surface Identifier on every simple renderer.
## Before you begin
- Use the released Ultimate Character Controller Version 3 package. The source verified for this page is UCC `3.2.0`; Version 4 development behavior is outside this workflow.
- Create or choose a [Surface Impact](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-impacts/), at least two [Surface Types](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-types/), and a [Surface Effect](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-effects/) for each response you want to compare.
- Give each Surface Type an **Impact Effects** pair that maps the test Surface Impact to its Surface Effect.
- Assign that same Surface Impact to the source that produces the contact, such as Character Foot Effects, Jump, Fall, a Trajectory Object, or an item impact action.
- Make sure each test target has a Collider. Texture-based multi-material and UV-region detection also requires a MeshCollider and readable mesh data.
Use a [Surface Identifier](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-identifiers/) for a critical object, a skinned renderer, a procedural material, or any target whose texture cannot be resolved reliably. Surface Manager's texture lookup is best for many static objects that share ordinary materials.
## Add Surface Manager to the scene
1. Choose **Tools > Opsive > Ultimate Character Controller > Setup Manager**.
2. Select the **Scene** tab.
3. Under **Manager Setup**, select **Add Managers**.
4. In the Hierarchy, select the `Game` object that was created or reused. The setup command adds Surface Manager, Decal Manager, Object Pool, Scheduler, Audio Manager, and the other scene managers to this object.
5. Select **Surface Manager** in the Inspector and confirm that the scene does not contain another active Surface Manager.
6. Set **Main Texture Property Name** to the property that holds the material texture you will register. The component's released code default is `_BaseMap`; many Built-in Render Pipeline shaders instead use `_MainTex`.
7. Leave **Detect Terrain Tree Textures** disabled unless terrain trees must have a different response from the terrain beneath them.
8. Save the scene before adding mappings.
Surface Manager can create an unconfigured `SurfaceManager` GameObject on first static use when none exists. Use the Setup Manager path for a real scene so the configured component and companion managers are present before gameplay starts.
**Editor checkpoint:** one active Surface Manager is on the scene manager object, **Main Texture Property Name** matches the test shader exactly, and the Console is clear after saving the scene.
## Register surfaces and responses
The manager maps a texture to a Surface Type. The Surface Type separately maps a Surface Impact to a Surface Effect.
1. Select the Surface Manager and add an element to **Object Surfaces**.
2. Select the new row and assign its **Surface Type**, such as `Wood`.
3. Select **Add Texture**, then assign the exact texture used by the wood material.
4. Keep **UV** at `X 0`, `Y 0`, `W 1`, `H 1` for the whole texture. Use a smaller rectangle only for a tested MeshCollider atlas workflow.
5. Add another Object Surface for `Metal` and register the metal texture.
6. On both Surface Type assets, add the same Surface Impact under **Impact Effects**, but assign different Surface Effects.
7. Assign the same Surface Impact at the source of the hit.
8. Expand **Fallbacks** and decide whether unknown inputs should resolve or remain silent.
9. Save the Surface Types, Surface Effects, source prefab, and scene, then enter a fresh Play Mode session.
Do not register the same Texture more than once in released 3.2.0. The initializer adds every registered Texture to a unique dictionary before building its UV-region maps; repeating a Texture with another UV rectangle can throw a duplicate-key exception. The legacy recommendation to repeat one atlas texture across multiple Object Surfaces is not a safe no-code workflow in this release. Use separate textures/materials, a Surface Identifier, or a tested project-side extension instead.
## Surface Manager Inspector fields
These are the fields drawn by the released 3.2.0 custom Inspector and their new-component defaults:
| Field | Default | Decision |
| --- | --- | --- |
| **Object Surfaces** | No entries | Maps each Surface Type to one or more unique textures. Selecting an entry exposes **Surface Type**, its texture tiles, **UV**, **Remove**, and **Add Texture**. |
| **Main Texture Property Name** | `_BaseMap` | Name passed to `Shader.PropertyToID` and read from the renderer's shared material. It must match the active shader. |
| **Detect Terrain Tree Textures** | Disabled | When enabled, tests terrain tree instances to find the hit tree's main texture. This is explicitly CPU-intensive. |
| **Fallback Surface Impact** | None | Substituted when the incoming Surface Impact is null and also used as the final impact lookup after a primary pair fails. |
| **Fallback Surface Type** | None | Substituted when no Surface Type is detected and used when a detected Surface Type lacks the requested pair. |
| **Fallback Allow Decals** | Enabled | Controls decals when the incoming impact or detected surface was null and its fallback was substituted. Disable it when an approximate fallback decal would be misleading. |
Adding a texture initializes its UV rectangle to the full `0,0,1,1` range. The component has no separate terrain list: terrain-layer diffuse textures and optional terrain-tree material textures use the same Object Surfaces registrations.
## Choose how the Surface Type is detected
Surface Manager evaluates these routes in order:
| Target | Recommended setup | Released behavior |
| --- | --- | --- |
| Explicit object | Add Surface Identifier and assign its Surface Type | The identifier wins over texture and terrain detection. The manager checks the collider object, then its children, then its parents. |
| One ordinary material | Register the material's main texture in Object Surfaces | The renderer's shared material is read with **Main Texture Property Name** and cached for that collider. |
| Multiple materials | Use a MeshCollider with readable mesh data and register each material texture | The raycast triangle is matched to a submesh and then to the corresponding shared material. |
| One atlas region | Register the texture once with a tested UV rectangle | Runtime applies material tiling and offset, wraps the coordinate, flips Y for the Inspector convention, and tests whether the rectangle contains the hit UV. Multiple regions for one repeated Texture are unsafe in released 3.2.0. |
| Legacy secondary texture | Prefer Surface Identifier; test this compatibility path only if the project already depends on it | Released source contains a `_Mask` and `_MainTex2` branch that selects the secondary texture when readable mask alpha exceeds `0.5`, but its static shader IDs are assigned only through lazy-instance initialization. Do not assume a scene manager or another shader convention resolves it. |
| Terrain ground | Register each Terrain Layer's diffuse texture | The dominant alphamap layer at the hit point supplies the texture. A Surface Identifier is not used for a TerrainCollider. |
| Terrain tree | Register the tree texture and enable **Detect Terrain Tree Textures** | The manager probes terrain tree instances before falling back to the ground texture. Keep it disabled unless the extra per-hit work is necessary. |
| Skinned, generated, or unresolved target | Use Surface Identifier | Released texture resolution deliberately rejects SkinnedMeshRenderer triangle lookup and cannot infer a type without a recognized texture route. |
A Surface Identifier can leave **Surface Type** unassigned and still turn off **Allow Decals** while texture detection supplies the type. Keep the identifier on the collider GameObject when possible so hierarchy lookup is unambiguous.
## Understand response and fallback resolution
After detecting a Surface Type, Surface Manager resolves an effect in this order:
1. Use the incoming Surface Impact. If it is null, substitute **Fallback Surface Impact**.
2. Use the detected Surface Type. If none was detected, substitute **Fallback Surface Type**.
3. Look for the Surface Impact in that Surface Type's **Impact Effects**.
4. If a detected Surface Type lacks the pair, switch to **Fallback Surface Type** and try the original or substituted impact there.
5. If no effect was found, try **Fallback Surface Impact** on the Surface Type currently being used.
6. Spawn nothing and return `false` when no Surface Effect resolves.
If a Surface Type contains the same Surface Impact more than once, the manager logs a warning and caches only the first pair. Keep one unambiguous pair.
**Fallback Allow Decals** is narrower than its label may suggest. Released 3.2.0 applies it only when the incoming Surface Impact or initially detected Surface Type was null. A fallback reached solely because a known Surface Type lacked a pair is not flagged for this decal check. For sensitive surfaces, also disable **Allow Decals** on a Surface Identifier or use a fallback Surface Effect with no decals.
## Control decals and runtime lifetime
Surface Manager decides only whether the resolved effect may request a decal:
- A null collider blocks decals.
- A discovered Surface Identifier with **Allow Decals** disabled blocks them.
- An applicable fallback uses **Fallback Allow Decals**.
- A Surface Effect with no decal prefabs cannot spawn one.
[Decal Manager](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/decal-manager/) performs placement, limits, weathering, fadeout, and object-pool return. In released 3.2.0, a decal on a uniformly scaled receiver is parented to the hit transform; a decal on a non-uniformly scaled receiver is parented under Decal Manager to avoid inherited distortion. There is no current **Allow Non Uniform Decals** field or **Placement Tests** toggle. Use Surface Identifier's **Allow Decals** for per-object policy.
Surface Effect spawned objects and decals use the shared [Object Pool](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/object-pool/). Audio and temporary state responses follow the selected Surface Effect; Surface Manager does not own their cleanup.
## Check the editor setup
Before Play Mode, confirm:
- The scene contains one intended Surface Manager and its companion managers.
- **Main Texture Property Name** exists on every material that relies on texture detection.
- Every registered Texture appears only once in Object Surfaces.
- Each Object Surface has a Surface Type and at least one non-null Texture.
- Multi-material or UV tests use a MeshCollider and readable mesh; mask sampling uses a readable Texture2D.
- Terrain Layer diffuse textures are registered and tree detection is enabled only when required.
- Each Surface Type has one pair for the Surface Impact used by the source.
- Fallback Surface Type contains the pairs that the fallback path is expected to find.
- Fallback decal policy and every relevant Surface Identifier's **Allow Decals** value are intentional.
Stop and restart Play Mode after changing a mapping, hierarchy, material, identifier, or Surface Type pair. The released manager caches these lookups and exposes no Inspector command to rebuild them in place.
## Verify on multiple surfaces in Play Mode
1. Create adjacent Wood and Metal test objects with colliders, one ordinary material each, and visibly different registered textures. Do not add Surface Identifiers yet.
2. Map the two textures to distinct Wood and Metal Surface Types in Object Surfaces.
3. Pair one Bullet Hit Surface Impact with a wood response on Wood and a clearly different metal response on Metal.
4. Trigger the same source on Wood. Confirm only the wood audio, spawned objects, decal, and optional state run.
5. Trigger that source on Metal without changing the source. Confirm the metal pair runs instead.
6. Add a Surface Identifier to the metal collider and temporarily assign the Wood Surface Type. Restart Play Mode and confirm the identifier overrides the registered metal texture; then restore the intended type.
7. If the scene uses terrain, map two Terrain Layer diffuse textures, hit a point where each layer is dominant, and confirm the response changes across the blend.
8. Hit an unmapped object and trigger a null Surface Impact. Confirm the configured fallback pair, including its decal policy, or confirm silence if the fallbacks are intentionally unassigned.
9. Disable **Allow Decals** on one receiver's Surface Identifier, restart Play Mode, and confirm its audio and spawned objects remain while its decal is absent.
10. Repeat the test after changing a mapping outside Play Mode. Confirm a fresh session uses the new mapping and produces no duplicate-key exception or duplicate-impact warning.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| No response plays | The source impact, detected type, or Impact Effects pair is missing | Assign the same Surface Impact at the source and in the Surface Type, then assign a Surface Effect to that pair. |
| Every object uses the fallback | **Main Texture Property Name** does not exist on the shader, or the material texture is not registered | Enter the exact shader property, register the actual shared-material texture, and restart Play Mode. |
| Unity reports that the same key was added during `Awake` | One Texture appears with more than one distinct UV entry | Register that Texture once. Use separate materials, Surface Identifiers, or project code instead of repeated atlas entries in released 3.2.0. |
| A multi-material or UV hit resolves incorrectly | The target is not a MeshCollider, the raycast has no triangle index, or the mesh is not readable | Use a readable MeshCollider workflow or assign a Surface Identifier. |
| A secondary texture is ignored | The material differs from the legacy `_Mask` and `_MainTex2` convention, the mask is unreadable, or the scene-manager path did not initialize those static property IDs | Bypass this fragile released path with Surface Identifier, or apply and verify a project-side initialization fix before relying on it. |
| Terrain always reports one material | The diffuse textures are not registered, or that layer is dominant at the sampled alphamap cell | Register each Terrain Layer diffuse texture and test well inside each painted region. |
| A terrain tree uses the ground response | Tree detection is disabled, the tree prefab has no usable collider, or its texture is unmapped | Enable detection only for this test, provide the collider and mapping, then measure the cost before shipping. |
| Inspector edits do not change later hits | The collider, texture, identifier, or pair was already cached | Stop Play Mode, make the change, and start a fresh session. |
| The wrong hierarchy type is selected | Multiple Surface Identifiers are found across the collider's children or parents | Put one intended identifier on the collider GameObject and restart Play Mode. |
| A fallback decal appears unexpectedly | **Fallback Allow Decals** defaults to enabled, or the fallback was reached through a missing pair rather than a null input | Disable fallback decals, disable them on the receiver, or remove decals from the approximate fallback effect. |
| The old non-uniform or placement setting is missing | The page or project was based on an older Inspector | Use the current automatic parenting and Surface Effect edge-overlap behavior; those manager toggles are not present in 3.2.0. |
| Duplicate managers produce inconsistent results | More than one active Surface Manager exists and the static lookup selects one | Keep one configured scene manager and remove the unintended duplicate through a recoverable editor change. |
## Related pages
- [Surface System](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/)
- [Surface Types](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-types/)
- [Surface Impacts](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-impacts/)
- [Surface Effects](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-effects/)
- [Surface Identifiers](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-identifiers/)
- [Decal Manager](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/decal-manager/)
- [Character Foot Effects](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/character-foot-effects/)
- [Advanced Surface System Topics](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/advanced-surface-system-topics/)
- [Object Pool](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/object-pool/)
## Developer reference
`SurfaceManager`, `SurfaceType`, `SurfaceImpact`, `SurfaceEffect`, and `SurfaceIdentifier` are in `Opsive.UltimateCharacterController.SurfaceSystem`.
### Runtime APIs and lifecycle
`SurfaceManager.SpawnEffect` has four static overloads: regular and footprint-aware calls, each with either the `RaycastHit.collider` or an explicit Collider. A successful resolution invokes the Surface Effect and returns `true`; failure returns `false`. Footprint-aware calls use `SurfaceType.AllowFootprints` to choose `SpawnFootprint` or the regular spawn path.
The public instance methods `GetSurfaceType`, `GetSurfaceIdentifier`, and `GetSurfaceEffect` support custom callers that need to inspect resolution before spawning. `GetSurfaceEffect` returns the chosen Surface Effect and writes the resolved Surface Type and decal permission through `ref` parameters.
Static use locates the first Surface Manager or creates an unconfigured `SurfaceManager` GameObject. Scene unload and subsystem registration reset the static instance. Keep one configured manager per gameplay scene; there is no dedicated surface-resolution event.
### Caches and runtime changes
Object Surface texture dictionaries are built in `Awake`. Collider lookups then cache identifiers, decal permission, resolved simple types, renderer, mesh, main texture, terrain, and material complexity. Surface Type impact maps are built lazily on first use. The released API exposes no cache invalidation or Object Surface rebuild method.
Configure mappings before `Awake`, and treat collider/material/hierarchy edits as next-session changes unless project code deliberately recreates the manager. A runtime Surface Type edit may also leave its already-built impact map unchanged.
### Pooling, saving, and networking
Surface Manager does not pool the manager or a resolved effect. Its optional terrain-tree probe temporarily instantiates tree prefabs through `ObjectPoolBase` and returns them after each test; this per-tree work is why the Inspector labels the option CPU-intensive. Surface Effects and Decal Manager own the pooled cosmetic objects they spawn.
Scene serialization preserves the manager's configured fields, while Surface Type, Impact, and Effect assets preserve their mappings. Runtime caches, random selection state, spawned decals, particles, audio, and temporary states are not save-game state. Persist any underlying gameplay consequence separately.
Surface Manager does not replicate resolution or effects. In a networked project, choose which peer or server resolves the hit, replicate the authoritative impact or cosmetic result, and prevent prediction plus replication from spawning the same response twice.
### Released 3.2.0 source notes
- Repeating a Texture with a different UV rectangle can throw during `InitObjectSurfaces`; do not rely on legacy first-overlap/list-order guidance for atlas regions without a project-side fix.
- **Fallback Allow Decals** is applied only to fallbacks caused by an initially null Surface Impact or Surface Type. A pair-missing fallback is not marked by those flags.
- The released Decal Manager has no **Allow Non Uniform Decals** field. It parents decals from uniform receivers to the hit transform and decals from non-uniform receivers to the manager transform.
- The `_Mask` and `_MainTex2` shader-property IDs are assigned inside the lazy static `Instance` lookup, while a scene component's `OnEnable` can mark the singleton initialized without that assignment. Treat secondary-texture detection as a source-level compatibility path that requires a project fix and focused verification.
---
# Surface Impacts
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-impacts/)
Use a Surface Impact asset to identify what caused contact, such as a bullet hit, melee strike, footstep, jump, or landing, so each target Surface Type can select the appropriate Surface Effect.
## Before you begin
1. Open **Tools > Opsive > Ultimate Character Controller > Setup Manager**.
2. Select **Scene > Manager Setup > Add Managers**. Confirm that the scene's **Game** object contains **Surface Manager**, **Decal Manager**, and the shared **Object Pool**.
3. Decide which causes need different response matrices. Create one reusable impact for each cause, such as `BulletHit`, `MeleeHit`, and `Footstep`; do not create `BulletHitOnWood` as the impact.
4. Create or choose at least two [Surface Types](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-types/), such as Wood and Metal, and make their test Colliders resolve those types through [Surface Identifiers](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-identifiers/).
A Surface Impact contains no sound, particle, decal, damage, or force values. It is a blank `ScriptableObject` used as an object-reference key. Renaming the asset does not change a serialized reference; duplicating it creates a different key that must be mapped separately.
## Create and map a Surface Impact
1. In the Project window, choose **Assets > Create > Opsive > Ultimate Character Controller > Surface Impact**.
2. Save the asset under `Assets` and name it for the cause, such as `BulletHit`.
3. Create a [Surface Effect](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-effects/) for each target-specific response, such as `BulletHitOnWood` and `BulletHitOnMetal`, with **Assets > Create > Opsive > Ultimate Character Controller > Surface Effect**.
4. Select the Wood Surface Type. In **Impact Effects**, add an element, assign `BulletHit` to **Surface Impact**, and assign `BulletHitOnWood` to **Surface Effect**.
5. Repeat on Metal, using the same `BulletHit` asset and the metal-specific effect.
6. Assign `BulletHit` to exactly one contact consumer. The correct field depends on whether the source is a hitscan item, moving projectile, melee attack, footstep, or ability.
7. On Surface Manager, configure **Fallback Surface Impact**, **Fallback Surface Type**, and **Fallback Allow Decals** only when unknown or incomplete input should produce an approximate response.
The Surface Impact Inspector has no configurable fields or defaults. All behavior comes from where that asset is referenced.
## Build the source and target matrix
The source supplies the Surface Impact; the target supplies the Surface Type. Their intersection supplies the Surface Effect:
| Target Surface Type | Bullet Hit impact | Melee Hit impact | Footstep impact |
| --- | --- | --- | --- |
| Wood | `BulletHitOnWood` effect | `MeleeHitOnWood` effect | `FootstepOnWood` effect |
| Metal | `BulletHitOnMetal` effect | `MeleeHitOnMetal` effect | `FootstepOnMetal` effect |
Use the same impact asset down a column. A Surface Type's **Impact Effects** starts empty; each element starts with **Surface Impact** `None` and **Surface Effect** `None`. Add only one element for each Surface Impact. On first use, Surface Manager builds a dictionary for that Surface Type; if the same impact appears more than once, it warns and keeps only the first entry.
### Resolution and fallback order
Surface Manager first detects the target type and decal permission from the hit. It then resolves the response in this order:
1. uses the incoming Surface Impact, or substitutes **Fallback Surface Impact** when the incoming value is null;
2. stops if both are null;
3. uses the detected target Surface Type, or substitutes **Fallback Surface Type** when detection returned null;
4. stops if the resulting type is null or its **Impact Effects** array is null or empty;
5. tries the current impact on the current type;
6. if that pair is missing and the fallback type was not already selected, tries the current impact on **Fallback Surface Type**;
7. if still missing, tries **Fallback Surface Impact** on the type from the previous step; and
8. spawns nothing when no valid pair exists.
**Fallback Surface Impact** and **Fallback Surface Type** default to `None`; **Fallback Allow Decals** defaults to enabled. A known Surface Type with an empty **Impact Effects** list returns before the pair-fallback steps, so give every production type at least one deliberate mapping.
Released Version 3.2.0 applies **Fallback Allow Decals** when the incoming impact or detected type was initially null. It does not mark the later "known pair missing, switch to fallback type" path as a fallback for that decal check. Use an explicit pair or a fallback effect with no decal when approximate feedback must never leave a decal.
On that known-pair-missing path, the released code replaces the current type with **Fallback Surface Type** even when the field is `None`; it does not then try **Fallback Surface Impact** against the original detected type. Configure a populated fallback type or, preferably, complete the explicit matrix.
A fallback can act only after a consumer calls Surface Manager. Character Foot Effects and the item **Spawn Surface Effect** action can pass a null impact into that call. Jump, Fall, and Trajectory Object guard their direct calls with a non-null check, so leaving those source fields `None` skips the request instead of invoking **Fallback Surface Impact**.
## Configure the Surface Effect response
The selected Surface Effect owns target-dependent presentation. These are the released new-asset defaults most relevant to an impact setup:
| Response | Fields | Defaults |
| --- | --- | --- |
| Pooled particle, dust, spark, or debris prefab | **Spawned Objects** entries: **Object**, **Probability**, **Random Spin** | No entries; `None`, `1`, disabled per new entry |
| Decal or footprint | **Decals > Prefabs**, **Min Scale**, **Max Scale**, **Allowed Decal Edge Overlap** | No entries; `1`, `1`, `0.25` |
| Shared audio recipe | **Audio > Audio Config** | `None` |
| Raw audio clips | **Audio Clips**, **Min/Max Volume**, **Min/Max Pitch**, **Random Clip Selection**, **Min Audio Clip Frame Interval** | No entries; `1`/`1`, `1`/`1`, enabled, `-1` |
| Temporary target State | **State Name**, **State Disable Timer** | Empty, `10` seconds |
When **Audio Config** is assigned, the raw clip, volume, pitch, and selection controls are hidden and ignored; **Min Audio Clip Frame Interval** still applies. `-1` disables that frame throttle, while `0` permits at most one play from the shared effect asset per frame.
There is no dedicated particle field. Put a particle prefab in **Spawned Objects**, or use the item **Spawn Particle** Impact Action when the same particle should appear regardless of target Surface Type.
## Choose one contact consumer
One physical contact can pass through several systems. Choose one place to request the Surface Effect or the same feedback can spawn more than once.
Like every Impact Action, a newly added **Spawn Surface Effect** starts **Enabled**, with **Delay** `0` and **Allow Multi Hits** disabled. Its own **Use Context Data** starts disabled and **Surface Impact** starts `None`. The default damage group is a special constructor path that creates this action with context use enabled.
### Projectile and hitscan sources
For a hitscan Shootable Action:
1. Open **Impact Action Module Group > Generic Shootable Impact > Impact Actions**.
2. Add or keep **Spawn Surface Effect**.
3. Assign the local **Surface Impact** to `BulletHit`. A newly added action has **Use Context Data** disabled and **Surface Impact** `None`; the built-in default damage group constructs its copy with context use enabled.
4. Keep one surface-effect action in the successful impact path.
The action uses `ImpactDamageData.SurfaceImpact` when **Use Context Data** is enabled and that value is non-null; otherwise it uses its local **Surface Impact**. It does not read `ImpactCollisionData.SurfaceImpact` for this choice. A valid `RaycastHit` is required for detection and placement.
A moving Projectile can request the same response through as many as three routes:
- the inherited Trajectory Object **Surface Impact**, called directly during base collision handling;
- the owning Shootable Action's **Spawn Surface Effect** action; and
- the Projectile's own **Impact Action Group** when **Internal Impact** is enabled.
Use exactly one. For an action-based route, leave the Trajectory Object **Surface Impact** null, keep **Surface Impact** null in projectile damage data when initialization would copy it to the Trajectory Object, assign the action's local impact, and remove or disable the duplicate **Spawn Surface Effect** action. For a direct Trajectory Object route, keep its impact and remove the action-based duplicates while retaining any required damage, force, and event actions.
ProjectileBase initialization normally copies `ImpactDamageData.SurfaceImpact` to the Trajectory Object unless **Use Object Impact Layer And Surface** is enabled. This makes duplicate-consumer auditing essential on projectile prefabs.
### Melee sources
For a Melee Action, add **Spawn Surface Effect** to **Generic Melee Impact Module > Impact Actions** and assign the local **Surface Impact**. The built-in action falls back to that local value because ordinary melee context has no `ImpactDamageData`.
Released Version 3.2.0 stores a Melee Hitbox's optional **Surface Impact** in `ImpactCollisionData.SurfaceImpact`, but **Spawn Surface Effect** reads only `ImpactDamageData.SurfaceImpact` or its local field. The hitbox value alone therefore does not select the built-in surface response. Use the local action field for one melee cause, separate action configurations for different attacks, or a project-owned Impact Action that deliberately reads the collision value.
### Footstep, jump, and landing sources
- Assign **Surface Impact** on [Character Foot Effects](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/character-foot-effects/) for footsteps. It raycasts below the selected foot and calls the footprint-aware Surface Manager overload with forward direction and left/right flip.
- Assign **Jump Surface Impact** on Jump for takeoff feedback. It calls the ordinary overload with the grounded hit.
- Assign **Land Surface Impact** on Fall and tune **Min Surface Impact Velocity** for landing feedback. Fall calls the footprint-aware overload with character-forward direction and no flip.
These character sources call Surface Manager directly; they do not need an item Impact Action.
## Separate presentation from force and damage
| Desired result | Correct owner |
| --- | --- |
| Material-dependent audio, decal, particle/debris prefab, or State | Surface Effect selected by the impact-and-type pair |
| Material-independent hit particle or sound | **Spawn Particle** or **Play Audio Clip** Impact Action |
| Damage and push configured together | **Simple Damage** Impact Action |
| Additional linear or angular push | **Add Force** or **Add Torque** Impact Action |
| Projectile's physical Rigidbody push | Trajectory Object collision handling, which applies its current velocity independently of Surface Effect |
| Gravity-relative movement on spawned visual debris | **Directional Constant Force** on a Surface Effect spawned-object prefab; Surface Effect sets its direction but does not push the hit target |
Do not encode force strength in separate Surface Impact assets. The impact selects a response recipe; damage, force, impact strength, and radius remain part of the item or projectile context. Avoid combining Trajectory Object Rigidbody force, **Simple Damage**, and **Add Force** unless cumulative force is intentional.
The item **Spawn Surface Effect** action suppresses a non-shield response when an available damage context reports exactly zero damage. A **Shield Collider** is the explicit exception. Use another feedback path or project code when a harmless zero-damage hit must still show a response.
## Follow the runtime lifecycle and pooling
1. A source detects contact and supplies a `RaycastHit`, hit Collider, Surface Impact, gravity direction, time scale, and originator.
2. Surface Manager resolves the target Surface Type and decal permission, then applies the impact/type fallback chain.
3. On a Surface Type's first resolved use, the manager caches its Surface Impact-to-Surface Effect dictionary. Later edits do not rebuild that dictionary during the same manager lifetime.
4. The ordinary Surface Effect path spawns configured objects, plays audio at the hit point, activates the optional State on `hit.transform.gameObject`, then requests a decal when permitted.
5. The footprint path performs the same response order but plays audio on its supplied originator and sends direction/flip to Decal Manager. If the resolved type does not allow footprints, Surface Manager calls the ordinary path instead.
6. Source-owned gameplay actions such as damage and force run independently in their own configured order.
**Spawned Objects** uses `ObjectPoolBase.Instantiate`; Surface Effect does not return those objects itself. Give particle prefabs **Particle Pooler**, **Remover**, or another explicit return lifecycle. Decal Manager obtains and returns decals through the shared Object Pool according to its limits and weathering lifecycle.
The Surface Impact is a shared asset reference and is not instantiated or pooled. A Surface Effect also holds shared nonserialized selection state: last decal, last raw AudioClip, last audio frame, and sequential clip index. Every source using the same Surface Effect asset shares its audio throttle and selection history.
Delayed item Impact Actions duplicate their impact context from generic pools, then return the duplicate after execution. That context pooling is separate from Surface Effect object and decal pooling.
## Editor checkpoint
Before Play Mode, confirm that:
- each cause uses one intentional Surface Impact asset, and source fields reference the same asset object used in Surface Type mappings;
- every target Collider resolves the intended Surface Type;
- each Surface Type has one **Impact Effects** entry per tested impact, with a non-null Surface Effect;
- no duplicate entry precedes the intended pair;
- every projectile contact has exactly one surface-effect consumer;
- melee uses the local **Spawn Surface Effect > Surface Impact** unless project code deliberately consumes the hitbox collision value;
- each Surface Effect contains only material-dependent feedback, while force and damage remain in their intended impact actions;
- spawned particles and decals have valid pool-return lifecycles and receiver decal permission is deliberate;
- fallbacks are explicitly configured or intentionally remain `None`; and
- authored mapping changes are saved before a fresh Play Mode start.
## Verify in Play Mode
1. Place adjacent Wood and Metal Colliders with distinct Surface Types. Map the same `BulletHit` impact to dust and a dull clip on Wood, then sparks and a ricochet clip on Metal.
2. Fire the same hitscan source at both. Confirm the source impact remains `BulletHit` while the target type changes the selected Surface Effect.
3. Map `MeleeHit` and `Footstep` on both target types. Strike and walk across Wood, then Metal. Confirm each matrix cell produces its own effect without changing the target identifiers.
4. For melee, temporarily clear the action's local impact and **Fallback Surface Impact**, then assign only the hitbox Surface Impact. Confirm that it is not a working built-in selector in 3.2.0. Restore the local **Spawn Surface Effect** impact and confirm the expected effect resolves.
5. Fire one moving projectile once. Confirm the surface response occurs exactly once. If it repeats, audit the direct Trajectory Object, owner Impact Action, and Internal Impact routes.
6. On a footstep effect containing audio and a footprint decal, confirm audio follows the foot originator and the decal uses the correct direction/left-right flip. Disable receiver **Allow Decals**, restart Play Mode, and confirm audio remains while the decal is absent.
7. Through Character Foot Effects or an item action that still calls Surface Manager, test a null incoming impact, an unknown target type, and a known but unmapped pair separately. Confirm each follows the documented fallback branch and decal policy, or intentionally spawns nothing.
8. Give the hit target a non-kinematic Rigidbody and compare the surface response with gameplay force actions disabled and enabled. Confirm changing Surface Effect content does not change the force.
9. Repeat impacts rapidly. Confirm the shared audio interval behaves as configured and spawned particles and decals return to their pools rather than accumulating indefinitely.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| The Surface Impact Inspector appears empty | The released asset intentionally declares no fields. | Configure the source reference and each Surface Type's **Impact Effects** pair; do not look for response settings on the impact asset. |
| No effect plays | Source impact, detected Surface Type, exact pair, and Surface Effect reference | Assign the same asset object at the source and in one mapping, then test with fallbacks temporarily cleared. |
| Renaming an impact changes nothing | Resolution uses the ScriptableObject reference, not the filename. | Rename freely for organization. Update mappings only when replacing or duplicating the asset. |
| Unity warns about a duplicate impact | The same Surface Impact appears more than once in one Surface Type. | Keep one entry. Released Version 3.2.0 caches and uses only the first. |
| A newly added hitscan action uses the fallback impact | **Spawn Surface Effect > Surface Impact** is `None`, and context damage has no impact. | Assign the local bullet impact; do not rely on the scene fallback for a known source. |
| A Melee Hitbox impact is ignored | It was written to collision context, while the built-in action reads damage context or its local field. | Assign the action's local Surface Impact or implement an action that reads `ImpactCollisionData.SurfaceImpact`. |
| One projectile spawns two or three identical effects | Direct Trajectory Object, owner, and Internal Impact consumers are all enabled. | Keep one surface-effect route and remove only the duplicate **Spawn Surface Effect** actions. |
| A zero-damage item hit has no surface feedback | The built-in action suppresses non-shield effects when context damage equals zero. | Use a non-suppressed feedback action or a custom surface action for harmless contacts. |
| A known Surface Type with no mappings does not reach fallback | Resolution stops when its **Impact Effects** is null or empty. | Add at least one explicit mapping to that type; an empty known type cannot fall through to pair fallback. |
| A missing pair creates an unexpected fallback decal | The later fallback-type branch is not flagged for **Fallback Allow Decals** in 3.2.0. | Add the explicit pair or use a fallback Surface Effect with no decal. |
| A particle never returns to the pool | Surface Effect spawns it but does not own its cleanup. | Add Particle Pooler, Remover, or another explicit return path and avoid an endless looping particle. |
| The target receives no force | Surface Effect has no target-force field. | Configure **Simple Damage**, **Add Force**, projectile collision force, or another gameplay action and verify its Rigidbody/force target. |
| Audio is unexpectedly throttled across several characters | They share one Surface Effect and its **Min Audio Clip Frame Interval** state. | Use `-1`, reduce the interval, or use separate effect assets when independent histories are required. |
| A footstep reports success but nothing is heard | Character Foot Effects returns success when its ground raycast hits, even if no effect pair resolves. | Diagnose the Surface Impact, detected type, and mapping separately from foot timing. |
| Inspector mapping edits do not affect later hits | Surface Manager cached the type's impact dictionary. | Stop and restart Play Mode after changing **Impact Effects**. |
## Related tasks
- [Surface System](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/) explains the full source, target, and response relationship.
- [Surface Types](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-types/) owns the impact-to-effect mapping for each target material.
- [Surface Effects](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-effects/) configures pooled objects, decals, audio, and State responses.
- [Surface Identifiers](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-identifiers/) assigns deterministic target identity to a Collider.
- [Surface Manager](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-manager/) configures alternate identity detection and fallbacks.
- [Character Foot Effects](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/character-foot-effects/) configures footstep timing and footprint placement.
- [Decal Manager](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/decal-manager/) controls decal placement, limits, weathering, and pooling.
- [Advanced Surface System Topics](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/advanced-surface-system-topics/) covers lookup caches and complex targets.
- [Impact Actions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/impact-actions/) configures item feedback, damage, force, and callbacks.
- [Melee Action](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/melee/) and [Shootable Action](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/shootable/) configure the item contact sources.
- [Projectile](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/projectile/) configures moving projectile collision and Internal Impact behavior.
- [Jump](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/jump/) and [Fall](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/fall/) configure takeoff and landing impacts.
- [Object Pool](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/object-pool/) explains reusable response-object ownership.
## Developer reference
`SurfaceImpact` is an intentionally empty `ScriptableObject` in `Opsive.UltimateCharacterController.SurfaceSystem`. The mapping key is the asset reference. `ImpactCollisionData.SurfaceImpact` and `IImpactDamageData.SurfaceImpact` are separate context locations; released `SpawnSurfaceEffect` selects only the damage-data value when **Use Context Data** is enabled, then falls back to its local property.
Call Surface Manager directly when project code already owns a valid hit:
```csharp
using Opsive.UltimateCharacterController.SurfaceSystem;
using UnityEngine;
public sealed class SurfaceImpactEmitter : MonoBehaviour
{
[SerializeField] private SurfaceImpact m_SurfaceImpact;
public bool Emit(RaycastHit hit)
{
return SurfaceManager.SpawnEffect(
hit, m_SurfaceImpact, Vector3.down, 1f, gameObject);
}
}
```
`SurfaceManager.SpawnEffect` provides ordinary and footprint-aware static overloads, each also available with an explicit Collider. The ordinary overload returns `true` when a Surface Effect resolves and `Spawn` is invoked; an effect with empty response lists can therefore still report success. `SurfaceManager.GetSurfaceEffect(RaycastHit, Collider, SurfaceImpact, ref SurfaceType, ref bool)` exposes the final type, effect, and decal decision for diagnostics. `SurfaceEffect.Spawn` and `SpawnFootprint` are virtual extension points.
### Events
Surface Impact and Surface Manager emit no dedicated event when a pair resolves. `ProjectileBase.OnImpact` is a C# event, Trajectory Object exposes its collision UnityEvent, and an item **Impact Event** action can invoke source and target callbacks. These report contact independently of whether Surface Manager found an effect. See the [Event System](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/) and [Impact Actions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/impact-actions/).
### Save and network ownership
Authored references are serialized in assets, prefabs, scenes, abilities, and action modules. Runtime changes to a consumer's Surface Impact, Surface Manager mappings, shared effect selection state, active decals, particles, audio, and temporary States are not a durable save record. Save a stable project-owned impact key when the selected cause must persist, then map that key back to the local asset after load.
A Surface Impact reference and a manual `SurfaceManager.SpawnEffect` call do not replicate themselves. The optional multiplayer integrations route selected built-in item impact modules and projectile ownership, but custom calls, random Surface Effect choices, and cosmetic pool activity still need an explicit authority and duplication policy. Resolve gameplay damage and force on the authoritative peer, decide where presentation runs, and transmit a stable impact identifier rather than assuming a Unity asset reference is a network message.
---
# Surface Types
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-types/)
A Surface Type is the material identity used by the Surface System. Each asset maps a cause, represented by a [Surface Impact](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-impacts/), to the [Surface Effect](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-effects/) that should run on that material. After completing this workflow, the same footstep or projectile can produce different feedback on Ground, Metal, and Wood.
## Before you begin
- Add the scene managers with **Tools > Opsive > Ultimate Character Controller > Setup Manager**, select **Scene**, and choose **Manager Setup > Add Managers**. Confirm that the created manager object has a **Surface Manager** component.
- Create the Surface Impact assets that describe causes such as `Footstep` or `BulletHit`.
- Create the Surface Effect assets that contain the audio, spawned objects, decals, and state changes for each response.
- Ensure every tested surface has a Collider. Texture and material detection also requires a compatible Renderer; multi-material detection requires a readable mesh and a MeshCollider hit.
## Create and configure a Surface Type
1. In the Project window, select the folder that should contain the asset.
2. Choose **Assets > Create > Opsive > Ultimate Character Controller > Surface Type**. The same command is available from the Project window's context menu.
3. In **Save Surface Type**, enter a descriptive filename such as `Ground`, `Metal`, or `Wood` and save the asset under the project's `Assets` folder. The suggested filename for a new asset is `SurfaceType.asset`.
4. Select the new asset and expand **Impact Effects**.
5. Set the array **Size** to the number of responses this material needs.
6. For each element, assign one **Surface Impact** and the **Surface Effect** that it should trigger. Add separate rows for `Footstep`, `BulletHit`, and every other cause the type supports.
7. Make the asset reachable with a [Surface Identifier](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-identifiers/), an **Object Surfaces** texture entry on the Surface Manager, or **Fallback Surface Type**. Creating the asset alone does not register it with a scene.
The released 3.2.0 asset has these serialized values:
| Field | New-asset value | Purpose |
| --- | --- | --- |
| **Impact Effects** | No elements | Maps each **Surface Impact** reference to one **Surface Effect** reference. |
| Element > **Surface Impact** | **None** | The cause used as the lookup key. A row with no impact is skipped. |
| Element > **Surface Effect** | **None** | The response returned for that impact. Assign a real effect for a usable pair. |
| **Allow Footprints** | Enabled | Chooses footprint-oriented spawning for footprint requests. In 3.2.0 this serialized field is not drawn by the released custom Inspector, so there is no standard Inspector control for it. |
Do not add the same Surface Impact twice to one Surface Type. The first lookup builds a dictionary, logs a warning for a duplicate key, and keeps the first row.
### Understand the footprint setting
**Allow Footprints** does not enable or disable the whole footstep response. When it is enabled, a footprint request uses the Surface Effect's footprint-oriented spawn path. When it is disabled, the same request uses the ordinary effect spawn path, so audio and other configured response objects can still run. The public 3.2.0 API exposes this value as read-only; changing the hidden serialized value requires project-owned editor or asset-migration tooling.
## Use names without assuming inheritance
Use names to communicate intent, but do not rely on names for lookup:
| Asset kind | Example | Meaning |
| --- | --- | --- |
| Surface Type | `Ground`, `Metal`, `Wood` | The material identity. |
| Surface Impact | `Footstep`, `BulletHit` | The cause of the contact. |
| Surface Effect | `FootstepOnMetal`, `BulletHitOnWood` | The response for one cause/material pair. |
Surface Types are flat, independent ScriptableObjects. There is no parent, base type, or inherited Impact Effects list. Duplicating `Ground` to start `Wood` copies the rows once; later changes to either asset do not propagate. Likewise, naming an asset `Ground` has no runtime meaning: the system compares asset references.
To reuse behavior, assign the same Surface Effect asset to explicit rows on several Surface Types. Manager fallbacks provide missing-response behavior, not type inheritance.
## Register each material identity
Choose the most stable identity source for the object:
| Surface | Setup | Use when |
| --- | --- | --- |
| Collider or prefab | Add **Surface Identifier** and assign **Surface Type**. | One collider hierarchy has one explicit identity. This is checked before texture detection. |
| Simple rendered object | On **Surface Manager > Object Surfaces**, add an element, assign **Surface Type**, choose **Add Texture**, assign the material's main texture, and leave **UV** at `(0, 0, 1, 1)`. | A single-material object should be identified from its texture. |
| Multi-material mesh | Register each material's main texture in **Object Surfaces**. Use a readable mesh and a MeshCollider so the hit triangle can select the material. | Different submeshes represent different surfaces. Object Surfaces map textures, not Material assets. |
| Texture atlas or secondary map | Add the texture and the intended **UV** region to **Object Surfaces**. | One texture contains more than one material region. See [Advanced Surface System Topics](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/advanced-surface-system-topics/) for the released limitations. |
| Terrain | Register each Terrain Layer's diffuse texture in **Object Surfaces**. | The dominant painted terrain layer at the hit point should choose the type. A Surface Identifier is ignored for a TerrainCollider. |
| Unknown surface | Open **Surface Manager > Fallbacks** and assign **Fallback Surface Type**. | An impact can reach an object whose type cannot be detected. |
| Runtime-spawned collider | Include a stable Surface Identifier and its Surface Type before the collider's first query. | A spawned or pooled object needs explicit identity. |
A new Surface Manager starts with no **Object Surfaces** entries. **Main Texture Property Name** defaults to `_BaseMap`; change it to the shader's actual main-texture property before the manager initializes if the shader uses another property. **Detect Terrain Tree Textures** defaults to disabled. Enable it only when tree-texture detection is required because that path is CPU intensive.
For ordinary terrain painting, the manager chooses the Terrain Layer with the greatest weight at the hit point and looks up that layer's diffuse texture. **Detect Terrain Tree Textures** is a separate choice for terrain trees.
### Set fallbacks deliberately
Under **Surface Manager > Fallbacks**, a new manager has **Fallback Surface Impact** set to **None**, **Fallback Surface Type** set to **None**, and **Fallback Allow Decals** enabled.
In 3.2.0, **Fallback Allow Decals** is consulted when a missing incoming impact or missing detected type is initially replaced by its fallback. A later pair-missing hop from a known type to **Fallback Surface Type** does not set that fallback flag.
Resolution follows these boundaries:
1. A missing incoming Surface Impact is replaced with **Fallback Surface Impact**. If both are null, resolution stops.
2. A missing detected Surface Type is replaced with **Fallback Surface Type**. If there is still no type, resolution stops.
3. The manager checks the chosen impact/type pair.
4. If that pair is missing on a non-fallback type, it tries the same impact on **Fallback Surface Type**.
5. If the pair is still missing, it tries **Fallback Surface Impact** on the type currently being checked, which is normally the fallback type.
A detected Surface Type whose **Impact Effects** array is null or empty returns no effect before the pair-fallback checks. Add at least one valid row rather than expecting an empty type to inherit the manager fallback. Also note that the pair-missing path replaces the detected type with **Fallback Surface Type**; it does not try **Fallback Surface Impact** against the original type.
## Understand the runtime lifecycle
The Surface Manager prepares its Object Surfaces texture maps and shader property ID during `Awake`. For each contact it then:
1. Resolves an explicit Surface Identifier, then simple texture, complex material or UV region, and finally terrain texture.
2. Applies the configured fallback type when identity is still unknown.
3. Builds and caches the Surface Type's impact-to-effect dictionary on that type's first effect lookup.
4. Returns the mapped Surface Effect and lets the caller spawn the response.
The manager caches collider identity components, renderers, meshes, main textures, material complexity, and several resolved texture/type results. It also caches each Surface Type's Impact Effects map. As a result:
- Author Impact Effects and Object Surfaces before entering Play Mode. Object Surfaces changes after `Awake` are not reindexed, and Impact Effects changes after that type's first lookup do not rebuild its dictionary in 3.2.0.
- Keep a Surface Identifier on a collider before its first lookup. Adding or replacing the component later can leave the cached component result unchanged.
- Changing the `SurfaceType` value on an already-discovered Surface Identifier is supported because the manager reads that value for each query.
- Changing a renderer's material or main texture after its first lookup can leave the collider associated with the old cached identity.
- Reused pooled colliders keep the same manager cache entries. Give a pooled object a stable Surface Identifier, then change that identifier's Surface Type if the reused instance needs a new material identity.
## Editor checkpoint
Before entering Play Mode, verify all of the following:
- The scene contains one active Surface Manager.
- `Ground`, `Metal`, and `Wood` are three separate Surface Type assets.
- Every type has one row per required Surface Impact, with both references assigned and no duplicate impact keys.
- Each collider has an explicit Surface Identifier, or its texture is registered exactly once in **Object Surfaces**.
- Terrain Layer diffuse textures, not Terrain Layer assets, are registered for terrain detection.
- **Main Texture Property Name** matches the shader used by texture-detected objects.
- **Fallback Surface Type**, **Fallback Surface Impact**, and **Fallback Allow Decals** reflect an intentional fallback policy.
## Verify Ground, Metal, and Wood in Play Mode
Use visibly or audibly distinct Surface Effects so the result is unambiguous.
1. Create `Footstep` and `BulletHit` Surface Impacts.
2. Give each of `Ground`, `Metal`, and `Wood` a `Footstep` row and a `BulletHit` row. Map them to six distinguishable effects, such as ground thuds and dust, metal rings and sparks, and wood knocks and splinters.
3. Make a Ground pad with a Surface Identifier assigned to `Ground`.
4. Make a single-material Metal pad with no Surface Identifier. Register its main texture to `Metal` in **Object Surfaces**.
5. Paint a Wood Terrain Layer as the dominant layer in a small terrain area and register that layer's diffuse texture to `Wood`.
6. Enter Play Mode and walk the same character across all three surfaces. Each contact should retain the `Footstep` cause but select the Ground, Metal, or Wood effect from the detected type.
7. Fire the same projectile at all three surfaces. Each hit should retain the `BulletHit` cause and select the corresponding material response.
8. Add an otherwise unidentifiable test collider. With **Fallback Surface Type** set to `Ground`, verify that it uses the Ground mapping; with the fallback cleared, verify that no surface response is selected.
9. While still in Play Mode, change the Ground pad's existing Surface Identifier from `Ground` to `Metal` and repeat the same contact. The next lookup should use Metal. Restore the value before leaving Play Mode if the scene should remain Ground.
For a cache-boundary test, use a disposable duplicate asset: trigger it once, change one Impact Effects row during Play Mode, and trigger it again. The first cached mapping remains in use until the manager is recreated. Exit Play Mode and restore or discard the test asset rather than saving that temporary edit.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| The asset shows no configurable response rows | **Impact Effects** is collapsed or has **Size** `0`. | Expand the array and create one element per supported Surface Impact. |
| **Allow Footprints** is missing from the Inspector | The released 3.2.0 custom Inspector only draws **Impact Effects**. | Treat the serialized default as enabled, or use project-owned editor tooling if the asset truly requires a different value. |
| A known type produces no response and never reaches the fallback | Its **Impact Effects** array is empty. | Add a valid mapping. An empty detected type stops before pair fallback. |
| One cause always uses the wrong response | The Surface Impact appears more than once in the type. | Remove duplicate keys. The first row wins and the manager logs a warning. |
| An Inspector mapping change has no effect in Play Mode | That Surface Type was already queried, so its dictionary is cached. | Exit and re-enter Play Mode after authoring the asset. There is no released public cache-rebuild API. |
| A texture mapping is ignored | A Surface Identifier on the collider, a child, or a parent resolves first. | Correct or remove that identifier, or keep the explicit assignment and stop relying on texture detection. |
| A Terrain Surface Identifier is ignored | The hit collider is a TerrainCollider. | Register each Terrain Layer's diffuse texture in **Object Surfaces**. |
| A multi-material mesh always resolves one type or none | The hit is not returning a mesh triangle, the mesh is not readable, or a material texture is unregistered. | Use a MeshCollider with a readable mesh and register every relevant main texture. |
| A runtime material swap keeps the old type | Renderer, texture, and collider results may already be cached. | Use an existing Surface Identifier and change its Surface Type instead of changing the material identity source. |
| A duplicated type does not receive changes from the original | Surface Types do not inherit. | Add the mapping to both assets or reference the same Surface Effect explicitly. |
| An unregistered object produces no response | **Fallback Surface Type** or its required impact mapping is missing. | Assign a populated fallback type and, when the incoming impact can be null, a populated **Fallback Surface Impact**. |
## Related tasks
- [Surface System](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/)
- [Surface Manager](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-manager/)
- [Surface Identifiers](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-identifiers/)
- [Surface Impacts](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-impacts/)
- [Surface Effects](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-effects/)
- [Character Foot Effects](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/character-foot-effects/)
- [Decal Manager](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/decal-manager/)
- [Advanced Surface System Topics](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/advanced-surface-system-topics/)
## Developer reference
`SurfaceType`, `ImpactEffect`, `SurfaceIdentifier`, and `SurfaceManager` are in `Opsive.UltimateCharacterController.SurfaceSystem`.
- `SurfaceType.ImpactEffects` returns the serialized `ImpactEffect[]`; each element exposes read-only `SurfaceImpact` and `SurfaceEffect` references.
- `SurfaceType.AllowFootprints` is a read-only property whose serialized default is `true`.
- `SurfaceIdentifier.SurfaceType` is writable and is the supported direct identity to change on an already-discovered identifier.
- `SurfaceManager.GetSurfaceType(RaycastHit, Collider)` returns the detected type or `null`; it does not apply **Fallback Surface Type** by itself.
- `SurfaceManager.GetSurfaceEffect(RaycastHit, Collider, SurfaceImpact, ref SurfaceType, ref bool)` detects identity, applies pair fallbacks, returns the resolved effect or `null`, and updates the referenced type and decal decision.
Surface Type assets are not instantiated or pooled per contact. The effect's spawned objects can use the [Object Pool](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/object-pool/); the type asset and the manager's lookup dictionary remain shared configuration. Version 3.2.0 exposes no Surface Type change event and no public method to clear or rebuild the impact map, so systems that cache derived data should be initialized after asset configuration is final.
### Save and network boundaries
Surface Type mappings are project-authored ScriptableObject data referenced by scenes and prefabs. They are not per-player state and do not need a runtime save record in the normal case. A runtime assignment to `SurfaceIdentifier.SurfaceType` is not written back as saved gameplay state unless the project records and restores that choice explicitly.
The Surface Type API has no network serialization or replication. All peers should ship matching assets and scene references. If gameplay changes a Surface Identifier's type at runtime, replicate the material-state decision or the stable identifier needed to reconstruct it; do not assume the Surface System transmits the asset reference or spawned presentation effect automatically.
---
# Surface Effects
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-effects/)
Use a Surface Effect asset to define the material-specific feedback for one kind of contact: the same Bullet Hit Surface Impact can produce sparks and a ricochet on metal, dust on dirt, and a different result on wood. The asset is a shared response recipe; it is never instantiated as a scene object.
## Before you begin
- Use the released Ultimate Character Controller Version 3 package. The source verified for this page is UCC `3.2.0`; Version 4 development APIs are outside this workflow.
- Add **Surface Manager**, **Decal Manager**, and the shared Object Pool through **Tools > Opsive > Ultimate Character Controller > Setup Manager > Scene > Add Managers**. Surface and decal managers can create themselves on first use, but scene components expose the fallbacks and lifetime limits that should be reviewed before testing.
- Create or choose a [Surface Impact](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-impacts/) for what happened and a [Surface Type](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-types/) for what was hit.
- Give the hit collider a [Surface Identifier](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-identifiers/), or register its texture with [Surface Manager](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-manager/), so the manager can resolve a Surface Type.
- Prepare any Audio Config, AudioClip, particle, debris, or flat decal prefabs the effect will use.
A Surface Effect provides spawned objects, a decal, audio, and an optional state. It does not directly apply damage, force, torque, or knockback; use the item impact actions for gameplay consequences.
## Create and register a Surface Effect
1. In the Project window, choose **Assets > Create > Opsive > Ultimate Character Controller > Surface Effect**.
2. Save the asset under `Assets` and name it for the pair it represents, such as `BulletHitOnMetal` or `FootstepOnWood`.
3. Configure only the response groups needed for this pair: **Spawned Objects**, **Decals**, **Audio**, and **State**.
4. Select the matching Surface Type. In **Impact Effects**, add an element and assign the Surface Impact plus this Surface Effect.
5. Assign the Surface Type to the target through a Surface Identifier or a Surface Manager **Object Surfaces** texture mapping.
6. Assign the same Surface Impact asset to the source that causes the contact, such as Character Foot Effects, Jump, Fall, a Trajectory Object, or an item's **Spawn Surface Effect** impact action.
7. Configure Surface Manager's **Fallback Surface Impact**, **Fallback Surface Type**, and **Fallback Allow Decals** only when unknown or incomplete pairs should still produce feedback.
8. Save the asset, prefab, and scene before entering Play Mode.
The Surface Effect is not added directly to Surface Manager. Registration is the **Surface Impact > Surface Effect** pair stored in a Surface Type. If one Surface Type contains the same Surface Impact more than once, the released manager warns and uses only the first pair.
**Editor checkpoint:** the source and Surface Type reference the same Surface Impact asset, the Surface Type has one unambiguous pair for it, the hit collider resolves that Surface Type, and every referenced prefab is a project asset rather than a scene instance.
## Built-in response types and defaults
Released UCC 3.2.0 has exactly four built-in Surface Effect response groups. The current fields and new-asset defaults are:
| Group | Field | Default | Runtime behavior |
| --- | --- | --- | --- |
| Spawned Objects | Entries | No entries | Every entry is evaluated independently, so one hit can spawn several objects. |
| Spawned Objects | **Object** | None | Prefab instantiated at the hit point with its forward axis aligned to the hit normal. |
| Spawned Objects | **Probability** | `1` | Chance for this entry to spawn; `0` disables it and `1` is the intended always-spawn setting. |
| Spawned Objects | **Random Spin** | Disabled | Adds a random 0-360 degree rotation around the hit normal. |
| Decals | **Prefabs** | No entries | Selects one prefab at random and avoids an immediate repeat when more than one valid choice exists. |
| Decals | **Min Scale** / **Max Scale** | `1` / `1` | Inspector range is `0.01`-`2`; a random value is selected for each decal. |
| Decals | **Allowed Decal Edge Overlap** | `0.25` | Range is `0`-`0.5`; lower values require more of the decal mesh to remain over the hit surface. |
| Audio | **Audio Config** | None | When assigned, it is used instead of the raw AudioClip, volume, pitch, and selection fields. |
| Audio | **Audio Clips** | No entries | Used only when Audio Config is unassigned. |
| Audio | **Min Volume** / **Max Volume** | `1` / `1` | Raw-clip random volume range; Inspector range is `0`-`1`. |
| Audio | **Min Pitch** / **Max Pitch** | `1` / `1` | Raw-clip random pitch range; Inspector range is `-2`-`2`, then runtime time-scale values are applied. |
| Audio | **Random Clip Selection** | Enabled | Random selection avoids an immediate repeat when the list contains more than one usable clip; disabled selection advances through the list. |
| Audio | **Min Audio Clip Frame Interval** | `-1` | `-1` disables throttling, `0` allows at most one play per frame, and positive values require additional frames between plays. |
| State | **State Name** | Empty | Activates this State System state on the hit transform's GameObject. |
| State | **State Disable Timer** | `10` seconds | Schedules deactivation; `-1` leaves the state active until another system disables it. |
The former **One Clip Per Frame** checkbox is not a current field. Use **Min Audio Clip Frame Interval**. The current Inspector also includes **Audio Config**, which takes precedence over the raw clip controls.
## Configure spawned particles, debris, and force-driven visuals
Use **Spawned Objects** for particle bursts, dust, sparks, rubble, shell effects, or another one-shot prefab.
- Each entry has its own probability. Entries are not alternatives unless their probabilities and prefab design make them so.
- The object is spawned through `ObjectPoolBase` at the hit point. Add **Particle Pooler** to a root Particle System so it returns after all child particles finish, or add **Remover** for a fixed lifetime; Surface Effect does not remove spawned objects itself.
- A looping Particle System never becomes dead, so Particle Pooler keeps rescheduling its check. Stop the loop or use a deliberate removal policy.
- If the spawned root has **Directional Constant Force**, Surface Effect replaces that component's direction with the supplied gravity direction. Use it for gravity-relative visual debris. It does not push the hit target.
- Put force, torque, damage, ricochet, or character knockback that affects gameplay in the corresponding [Impact Actions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/impact-actions/).
## Configure decals and footprints
Add one or more decal prefabs under **Decals > Prefabs**. A usable decal root needs a Mesh Filter with a mesh and a Renderer with a material. A flat quad whose forward axis faces away from the receiver gives the predictable result, but the released cache code does not explicitly require a two-triangle mesh as the old field description claimed.
Decal placement follows these rules:
- Ordinary impacts rotate the decal to the hit normal and add a random spin.
- Footprint-aware consumers provide a forward direction and left/right flip value, so Decal Manager aligns and optionally mirrors the footprint instead.
- A sampled scale of exactly `1` preserves the prefab's original local scale. Any other sampled value sets local X and Y to that value and Z to `1`; it does not multiply arbitrary prefab X/Y values.
- **Allowed Decal Edge Overlap** below `0.5` runs the edge test automatically by raycasting the decal mesh vertices toward the receiver. At `0.5`, that test is skipped. Released 3.2.0 has no **Placement Tests** toggle on Decal Manager.
- A Surface Identifier with **Allow Decals** disabled blocks decals for its collider. A missing collider also blocks them. Surface Manager's fallback setting can further restrict a fallback selected for an unknown incoming impact or surface.
- Decal Manager owns the active list, weathering, fadeout, and pooling. Its defaults are **Decal Limit** `100`, **Weathered Decal Limit** `20`, and **Remove Fadeout Speed** `10`.
If a footprint-aware call resolves a Surface Type whose serialized **Allow Footprints** is false, Surface Manager invokes the ordinary Surface Effect spawn instead. In the released 3.2.0 custom Surface Type Inspector, only **Impact Effects** is drawn and the serialized footprint setting defaults to enabled.
## Configure audio
Prefer **Audio Config** when the response needs the shared audio selection, mixer, source prefab, or modifier workflow. When Audio Config is assigned, raw **Audio Clips**, volume, pitch, and random-selection settings are hidden and ignored; **Min Audio Clip Frame Interval** still applies.
Use the raw clip route for a small one-shot list:
1. Leave **Audio Config** unassigned.
2. Add the clips under **Audio Clips**.
3. Keep volume and pitch at `1` for unchanged playback, or set min/max ranges for variation.
4. Leave **Random Clip Selection** enabled for randomized variation, or disable it for list order.
5. Set **Min Audio Clip Frame Interval** to `0` when several same-frame contacts, such as shotgun pellets, must collapse to one sound from this Surface Effect asset.
Ordinary `Spawn` playback is positioned at the hit point. `SpawnFootprint` plays on the supplied originator when one exists; Character Foot Effects supplies the foot GameObject. The interval and last-clip selection state belong to the shared Surface Effect asset, so every character and collider using that same asset participates in the same throttle and selection history.
See [Audio](https://opsive.com/support/documentation/ultimate-character-controller/audio/) for Audio Config and shared Audio Manager choices.
## Choose the impact consumer
| Source | Configuration choice |
| --- | --- |
| Character footsteps | Assign a Footstep Surface Impact on [Character Foot Effects](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/character-foot-effects/). It uses the footprint direction and alternating flip path. |
| Jump | Assign **Jump Surface Impact** on the Jump ability. It uses the ordinary effect path at the grounded raycast hit. |
| Landing | Assign **Land Surface Impact** and tune **Min Surface Impact Velocity** on Fall. The released Fall ability uses the footprint-aware overload with the character forward direction. |
| Trajectory objects and shells | Assign **Surface Impact** on the Trajectory Object so its collision can call Surface Manager directly. |
| Modular item hits | Add **Spawn Surface Effect** to an Impact Action Group. Enable **Use Context Data** when the impact's damage data should provide the Surface Impact; otherwise assign the action's local **Surface Impact**. The default damage group includes this action. |
| Melee hitbox override | Assign the Surface Impact directly on **Spawn Surface Effect**. In released 3.2.0, the hitbox override is stored in `ImpactCollisionData.SurfaceImpact`, while this action's **Use Context Data** path reads `ImpactDamageData.SurfaceImpact`; the hitbox value alone does not select the effect. |
| Material-independent force, damage, audio, or particles | Use **Add Force**, **Simple Damage**, **Play Audio Clip**, **Spawn Particle**, or another Impact Action instead of duplicating the same Surface Effect on every Surface Type. |
| Material-dependent audio, decals, particles, or state | Put the response in Surface Effect and pair the same Surface Impact with a different Surface Effect on each Surface Type. |
When an impact damage context is present and reports zero damage, the item **Spawn Surface Effect** action does not run on a non-shield collider. A Shield Collider is the explicit exception. If a harmless hit still needs feedback, use an impact configuration whose action actually runs for that case and verify it in Play Mode.
## Understand pairing and fallbacks
Think of Surface Types as a matrix. For example:
| Surface Type | Bullet Hit | Footstep |
| --- | --- | --- |
| Wood | `BulletHitOnWood` | `FootstepOnWood` |
| Metal | `BulletHitOnMetal` | `FootstepOnMetal` |
At runtime Surface Manager resolves the pair in this order:
1. Use the incoming Surface Impact, or **Fallback Surface Impact** when the incoming value is null.
2. Detect the Surface Type, or use **Fallback Surface Type** when no type is detected.
3. Look for that Surface Impact in the resolved Surface Type's **Impact Effects**.
4. If the pair is missing and the detected type was not already the fallback, try the same impact on **Fallback Surface Type**.
5. If it is still missing, try **Fallback Surface Impact** on the current resolved type.
6. Spawn nothing when no Surface Effect is found.
Surface Manager caches Surface Identifier, renderer, texture, decal permission, and Surface Type impact maps. Treat the pair matrix as edit-time configuration: stop Play Mode after changing a mapping or collider hierarchy, then start a fresh test.
## Check the editor setup
Before Play Mode, confirm:
- The scene has the intended Surface Manager, Decal Manager, and Object Pool configuration.
- Every test collider resolves a distinct Surface Type through a Surface Identifier or texture mapping.
- Each Surface Type contains one pair for every Surface Impact being tested.
- The pair points to this Surface Effect and no duplicate Surface Impact precedes it.
- Audio uses either Audio Config or the raw clip route intentionally.
- Every spawned particle or debris prefab has an appropriate pool-return or removal component.
- Every decal prefab has a root Mesh Filter, mesh, Renderer, and material; the receiver allows decals.
- Force and damage are configured through impact actions rather than assumed to come from Surface Effect.
- Fallback assets and fallback decal permission match the desired unknown-surface behavior.
Save everything and start a new Play Mode session so the manager builds its caches from the final setup.
## Verify on multiple surfaces in Play Mode
1. Place adjacent Wood and Metal colliders, each with a Surface Identifier and its matching Surface Type.
2. On both Surface Types, pair one Bullet Hit Surface Impact with deliberately different effects. Give the metal effect a spark particle and ricochet audio; give the wood effect dust and a different clip.
3. Trigger the same Bullet Hit source on Wood. Confirm only the wood objects, audio, decal, and optional state run at the hit.
4. Trigger it on Metal without changing the source. Confirm the manager chooses the metal pair instead.
5. Walk a character across both colliders with one Footstep Surface Impact mapped on both types. Confirm the sound changes at the boundary and footprint orientation alternates correctly where decals are allowed.
6. Disable **Allow Decals** on one receiver, restart Play Mode, and repeat the hit. Audio and spawned objects should remain while the decal is absent.
7. Test an unmapped Surface Impact and an object with no detectable Surface Type. Confirm the configured fallback response, including its decal policy, or confirm that no effect is the intended result.
8. Fire a same-frame burst. Confirm **Min Audio Clip Frame Interval** limits the shared asset as configured, spawned particles return to the pool, and Decal Manager keeps its active/weathered counts bounded.
9. Repeat enough times to observe random entries. Every spawned-object entry should follow its own probability, while a decal trigger should select no more than one decal.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| No response plays | The source Surface Impact, detected Surface Type, or pair is missing | Assign the same Surface Impact at the source and in the Surface Type, then assign a Surface Effect to the pair. |
| The wrong material response plays | A fallback is resolving, the collider has the wrong Surface Identifier, or the manager cached an earlier setup | Verify the collider's type, temporarily clear fallbacks, and restart Play Mode after the correction. |
| Unity warns about a duplicate Surface Impact | The Surface Type contains the same Surface Impact more than once | Keep one pair; only the first duplicate is used. |
| Audio Clips and volume controls disappear | Audio Config is assigned | Configure the Audio Config, or clear it to use the raw AudioClip fields. |
| Audio is missing during a burst | **Min Audio Clip Frame Interval** is throttling a Surface Effect shared by several contacts or characters | Use `-1` for no throttle or reduce the interval, then retest the complete burst. |
| A particle or debris object never leaves the scene | Surface Effect spawns it but does not own its cleanup | Add Particle Pooler, Remover, or another explicit pool-return lifecycle; stop looping particles when appropriate. |
| The target receives no force or damage | Surface Effect has no built-in gameplay force or damage response | Add the matching Impact Action. Use Directional Constant Force only for a spawned prefab's gravity-relative motion. |
| A decal never appears | The effect has no valid prefab, the receiver blocks decals, fallback decals are disabled, or the edge test rejects the hit | Verify the prefab components and permission, test near the center, then adjust overlap only as needed. |
| A decal scale is unexpected | A non-`1` sampled value replaces decal X/Y and sets Z to `1` | Author the prefab for that behavior or keep Min/Max Scale at `1` to preserve its local scale. |
| Footprints spin like impact decals | The source used the ordinary overload, or the resolved Surface Type does not allow footprints | Use Character Foot Effects or another footprint-aware call and verify the Surface Type's serialized footprint setting. |
| The optional state affects the wrong object or never resets | **State Name** is absent on the hit transform's GameObject, or **State Disable Timer** is `-1` | Put the state on the hit object and use a finite timer, or disable the state explicitly from project code. |
| Inspector edits do not affect later hits | Surface Manager already cached the collider or pair | Stop Play Mode, make the edit, and begin a fresh session. |
| Multiplayer shows duplicate or different random feedback | Surface Effect resolution and random selection were invoked independently on several peers | Choose one networking authority and replicate the impact or cosmetic result deliberately; do not assume Surface Manager synchronizes it. |
## Related pages
- [Surface System](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/)
- [Surface Manager](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-manager/)
- [Surface Impacts](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-impacts/)
- [Surface Types](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-types/)
- [Surface Identifiers](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-identifiers/)
- [Decal Manager](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/decal-manager/)
- [Character Foot Effects](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/character-foot-effects/)
- [Advanced Surface System Topics](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/advanced-surface-system-topics/)
- [Impact Actions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/impact-actions/)
- [Object Pool](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/object-pool/)
- [State System](https://opsive.com/support/documentation/ultimate-character-controller/state-system/)
## Developer reference
`SurfaceEffect`, `SurfaceImpact`, `SurfaceType`, `SurfaceIdentifier`, `SurfaceManager`, and `DecalManager` are in `Opsive.UltimateCharacterController.SurfaceSystem`. `SurfaceManager.SpawnEffect` has regular and footprint-aware static overloads, with optional explicit Collider parameters. They accept a `RaycastHit`, Surface Impact, gravity direction, time scale, and originator; footprint overloads also accept direction and flip. The call returns `true` when an effect was resolved and invoked.
`SurfaceEffect.Spawn` and `SpawnFootprint` are virtual extension points. The asset's last decal, last raw AudioClip, audio frame, and sequential index are nonserialized runtime state shared by every caller of that asset. The built-in Surface System raises no dedicated surface-effect event; Character Foot Effects, Jump, Fall, Trajectory Object, and the **Spawn Surface Effect** Impact Action call Surface Manager directly. Add an item **Impact Event** action or a custom wrapper when project code needs a notification.
Surface Effects have no built-in saver. Their selection/throttle state is not persisted, and spawned objects, decals, audio, and temporary states are not automatically restored from a save. Persist the underlying gameplay change separately when it matters.
Surface Manager and Surface Effect do not replicate a result over the network. `ObjectSpawnInfo` uses the shared object pool. Particle Pooler can return through Network Object Pool when the multiplayer define is active, but that cleanup path does not make the original effect invocation authoritative or synchronized. Networked projects must decide where the impact is resolved and prevent local prediction plus replicated execution from spawning the cosmetic response twice.
### Released 3.2.0 source notes
- **Fallback Allow Decals** is applied when the incoming Surface Impact or detected Surface Type is null and the corresponding fallback is substituted. In released 3.2.0, a fallback reached only because a known Surface Type lacks the requested pair is not marked as a fallback for this decal check. Disable decals on sensitive receivers or omit decals from approximate fallback effects when that distinction matters.
- `SurfaceType.AllowFootprints` is serialized with a default of `true`, but the released custom Surface Type Inspector draws only **Impact Effects** and exposes no normal control for it.
- `SurfaceEffect.OnEnable` subscribes `Reset` to the static domain-reset delegate, while released `OnDisable` attempts to unsubscribe `OnEnable` instead. Ordinary project assets generally remain loaded, but custom systems that repeatedly create, enable, and disable Surface Effect instances should not assume the reset subscription is removed.
- Arrays created through custom runtime code must be initialized. Built-in spawn and lookup paths access the spawned-object and decal arrays without consistently guarding against null, whereas editor-created assets serialize them as empty lists.
---
# Surface Identifiers
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-identifiers/)
Use a Surface Identifier when one Collider should always report one deliberate Surface Type, independent of its Renderer, material, or texture.
## Before you begin
1. Open **Tools > Opsive > Ultimate Character Controller > Setup Manager**.
2. Select **Scene > Manager Setup > Add Managers**. Confirm that the scene's **Game** object contains **Surface Manager**, **Decal Manager**, and the shared **Object Pool**.
3. Create a [Surface Impact](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-impacts/), [Surface Type](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-types/), and [Surface Effect](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-effects/).
4. On the Surface Type, add the Surface Impact to **Impact Effects** and assign the Surface Effect. A Surface Identifier chooses the type; it does not create this impact-to-effect mapping.
## Add a Surface Identifier
1. Select the GameObject that owns the Collider receiving the hit. Prefer the exact Collider GameObject when a hierarchy contains more than one surface.
2. Select **Add Component** and add **Surface Identifier**.
3. Assign **Surface Type**.
4. Leave **Allow Decals** enabled if effects may place decals or footprints on this Collider. Disable it when decals would float, clip, stretch, or be inappropriate for that object.
5. Apply the component to the prefab when every instance should use the same identity.
The released Version 3.2.0 component has two fields:
| Field | Released default | Decision |
| --- | --- | --- |
| **Surface Type** | `None` | Assign the type that describes the Collider. When left `None`, the identifier does not force a fallback; Surface Manager continues to texture, material, and terrain detection. |
| **Allow Decals** | Enabled | Disable to veto decals on this Collider. Enabling it permits decals but does not override a Surface Effect with no decal or a fallback route whose decal policy disables them. The value is cached on first lookup. |
## Choose the identifier location
| Object setup | Recommended choice |
| --- | --- |
| One Collider, one logical surface | Put Surface Identifier on the same GameObject as the Collider. This is the fastest and most deterministic lookup. |
| Several child Colliders share one surface | A parent identifier can serve them, but only when no closer child identifier can be discovered first. Exact per-Collider identifiers are clearer in mixed hierarchies. |
| Child Colliders need different surfaces | Put an identifier with the correct type on each Collider GameObject. Do not rely on sibling or child search order. |
| Collider has no Renderer or material | Use Surface Identifier. It works without a Renderer, readable mesh, material, or UV data. |
| One Collider covers several renderer materials | One non-null identifier always returns one type. Split the geometry into separate Colliders and identifiers, or omit the identifier and configure [Surface Manager](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-manager/) material detection. |
| Material or texture changes only the appearance | Keep Surface Identifier authoritative when the logical surface is unchanged. Renderer and material edits do not affect its result. |
| Terrain uses several painted layers | Do not use Surface Identifier on the TerrainCollider; Version 3.2.0 explicitly ignores it. Map every Terrain Layer diffuse texture in Surface Manager **Object Surfaces** so the dominant layer at the hit position selects the type. |
| Object is instantiated at runtime | Include the identifier on the spawned prefab before its Collider is queried. A new Collider is cached correctly on its first hit. |
## Understand resolution and fallback order
For a non-terrain Collider, Surface Manager resolves identity in this order:
1. Search the hit Collider's GameObject for **Surface Identifier**.
2. If none exists there, search its children, then its parents.
3. Cache that component reference, including a `null` result, for the specific Collider. Cache **Allow Decals** separately when an identifier is found.
4. If the identifier has a non-null **Surface Type**, return it immediately.
5. Otherwise try the simple main-texture mapping, then multi-material, UV-region, or supported secondary-texture mapping.
6. If those routes fail, try terrain-layer detection. `TerrainCollider` skips the identifier search and reaches this route directly.
After identity detection, Surface Manager resolves the Surface Effect in this order:
1. Replace a missing incoming Surface Impact with **Fallback Surface Impact**. If neither exists, no effect spawns.
2. Replace a missing detected type with **Fallback Surface Type**. If the resulting type is null or has no **Impact Effects**, no effect spawns.
3. Try the current Surface Impact on the current Surface Type.
4. If that pair is missing and the fallback type was not already selected, try the current impact on **Fallback Surface Type**.
5. If no effect was found, try **Fallback Surface Impact** on the type from the previous step.
6. If no valid pair exists, nothing spawns.
**Fallback Surface Impact** and **Fallback Surface Type** default to `None`; **Fallback Allow Decals** defaults to enabled. The fallback decal setting is applied when the incoming impact or detected type was initially missing. Released Version 3.2.0 does not mark the later "pair missing, switch to fallback type" branch as a fallback for that decal check. If a fallback effect must never place a decal, give every expected type an explicit pair or use a fallback effect with no decal.
An identifier with **Allow Decals** disabled remains a hard veto. With it enabled, the final result can still suppress decals because the selected Surface Effect has none or because **Fallback Allow Decals** is disabled on an initially missing impact or type.
## Follow the runtime lifecycle
1. Surface Manager initializes **Object Surfaces**, the main-texture property ID, and its scene-level lookup state in `Awake`.
2. A projectile, melee hit, footstep, or project call supplies a `RaycastHit`, the hit Collider, and a Surface Impact.
3. The manager detects the Surface Type. On the Collider's first identifier query, it caches the found component or `null` and copies the current **Allow Decals** value when a component exists.
4. The manager resolves the impact-and-type pair, caching that Surface Type's impact-to-effect dictionary on first use.
5. The selected Surface Effect runs its ordinary or footprint response. Audio, spawned objects, decals, and State activation are independent options on that effect.
6. Later hits reuse the manager's caches. A scene reload or a new Surface Manager starts with fresh caches.
### Runtime change boundaries
Author identifiers before the first hit and keep the Collider hierarchy stable.
| Runtime change | Version 3.2.0 behavior |
| --- | --- |
| Change `SurfaceIdentifier.SurfaceType` on the same component | Supported. The cached component reference is read again on each type query. This is the supported route for dry/wet or intact/damaged identity changes. |
| Set that existing `SurfaceType` to `null` | The identifier stops winning and resolution continues through the remaining cached texture, material, or terrain routes. |
| Change `SurfaceIdentifier.AllowDecals` after first lookup | Not reflected. Surface Manager cached the first Boolean for that Collider. |
| Add or move an identifier after first lookup | Not rediscovered. The earlier component or `null` result remains cached. |
| Remove or replace a cached identifier | The manager does not search again for a replacement. Lower resolver caches and the original decal Boolean can remain in effect. |
| Swap a Renderer, mesh, material, main texture, or hierarchy | Existing renderer, mesh, texture, complexity, and detected-type caches are not rebuilt. Keep a pre-existing identifier and change only its `SurfaceType` when identity must change. |
| Edit Surface Manager **Object Surfaces** or **Main Texture Property Name** | Lookup dictionaries and the shader property ID are initialized in `Awake`; restart Play Mode after authored changes. |
| Edit a Surface Type's **Impact Effects** after it has resolved | Its first impact-to-effect dictionary remains cached. Restart Play Mode to rebuild it. |
| Spawn a new Collider with its configured identifier | Supported. Its first query creates new cache entries. |
| Reuse the same Collider instance from a pool for another surface | The old identifier reference and decal permission remain cached. Reassign the existing identifier's `SurfaceType`; do not change its decal policy between uses. |
There is no public cache-clear or rebuild method. Reload the scene or restart Play Mode when authoring changes must rebuild these maps.
## Editor checkpoint
Before entering Play Mode, confirm that:
- every test object has a Collider included by the test impact's physics query and, except for terrain, an identifier on the exact Collider GameObject;
- **Surface Type** is assigned on each direct identifier, and each type maps the test Surface Impact to an intentional Surface Effect;
- **Allow Decals** is final for the lifetime of each Collider instance;
- a collider-only test object has no Renderer, proving that identity does not depend on visuals;
- a multi-material test either uses separate Colliders and identifiers or has no identifier and is deliberately configured through Surface Manager;
- terrain has no identifier dependency and every relevant Terrain Layer diffuse texture appears once in **Object Surfaces**; and
- fallback impact, type, and decal values are either deliberately configured or deliberately left at their defaults.
## Verify multiple surfaces in Play Mode
1. Create a **Wood** Collider and a **Metal** Collider. Give each an exact Surface Identifier, assign different Surface Types, and map the same test Surface Impact to visibly or audibly distinct effects.
2. Trigger the same impact on both objects. Wood must select the Wood mapping and Metal must select the Metal mapping without consulting their Renderer materials.
3. Disable **Allow Decals** on Metal before entering Play Mode. Trigger an effect that contains a decal on both surfaces; Wood may place it, while Metal must still run its non-decal audio, object, or State response without placing the decal.
4. Hit a collider-only object whose identifier uses Wood. Confirm that it resolves the Wood effect even though no Renderer or material exists.
5. On a multi-material object, assign one non-null identifier and hit different rendered materials. Confirm that every hit uses the identifier's one Surface Type. Remove the identifier in Edit Mode, configure the material mappings, restart Play Mode, and verify material-dependent results separately.
6. Paint two large terrain regions with different mapped Terrain Layers. Hit each region and confirm the dominant diffuse texture selects its Surface Type. Adding Surface Identifier to the TerrainCollider must not change that result.
7. On an existing non-terrain identifier, change `SurfaceType` through project code or the Play Mode Inspector. The next hit must use the new type. After the first hit, changing **Allow Decals** is not a valid runtime switch and should demonstrate the cached original policy.
8. Hit an unconfigured Collider and confirm the deliberate fallback effect, or no response when fallback assets remain `None`. This distinguishes missing identity from a missing impact-to-effect pair.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| The wrong Surface Type wins | A Surface Identifier exists on the hit Collider, one of its children, or a parent. The child search runs before the parent search. | Put the intended identifier on the exact Collider GameObject and remove ambiguous nearby identifiers. Restart Play Mode to clear the cached result. |
| A configured material mapping is ignored | The Collider resolves a non-null identifier first. | Keep the identifier as the single authority, or remove it before first lookup and use the Surface Manager material route. |
| An identifier with **Surface Type** `None` uses a texture-mapped type | A null identifier type intentionally allows later resolvers to run. | Assign the intended Surface Type when the component must be authoritative. |
| Surface Identifier on terrain has no effect | `GetSurfaceIdentifier` returns null for `TerrainCollider`. | Map each Terrain Layer diffuse texture in Surface Manager **Object Surfaces**. |
| Adding an identifier at runtime changes nothing | The Collider already cached an identifier or `null`. | Include the identifier on the prefab before its first query, or use a project-owned dynamic resolver. |
| Changing **Allow Decals** at runtime changes nothing | The first identifier lookup cached the Boolean separately from the component reference. | Treat the field as fixed authoring data. Implement a custom response if decal permission must change dynamically. |
| A pooled object keeps its earlier decal policy | The same Collider instance and its cached Boolean were reused. | Keep one decal policy for the pool or use separate prefab pools. Only `SurfaceType` is safe to change on the existing identifier. |
| A Renderer or material swap still reports the old type | Surface Manager cached its renderer, mesh, texture, complexity, or detected type. | Put an identifier on the object before its first hit and change `SurfaceType`, or reload the scene to rebuild manager caches. |
| The correct type is detected but nothing spawns | Its **Impact Effects** has no entry for the incoming Surface Impact, or the chosen fallback type is null/empty. | Add one explicit impact-to-effect pair to the Surface Type and test again after restarting Play Mode. |
| A fallback effect creates an unexpected decal | The primary pair was missing and Version 3.2.0's later fallback-type branch does not apply **Fallback Allow Decals**. | Add the explicit pair or remove the decal from the fallback effect. |
| No decal appears even though **Allow Decals** is enabled | The Surface Effect has no decal, an initially used fallback disables decals, or Decal Manager rejects the placement. | Inspect the resolved effect and fallback policy, then verify the decal prefab and placement with [Decal Manager](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/decal-manager/). |
## Related tasks
- [Surface System](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/) explains the complete impact, type, and effect relationship.
- [Surface Manager](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-manager/) configures texture and terrain identity plus the fallback policy.
- [Surface Impacts](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-impacts/) defines what caused the contact.
- [Surface Types](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-types/) maps that cause to a response for a material identity.
- [Surface Effects](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-effects/) configures objects, decals, audio, and State activation.
- [Advanced Surface System Topics](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/advanced-surface-system-topics/) covers multi-material, UV, terrain, and cache limitations.
- [Character Foot Effects](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/character-foot-effects/) uses the detected ground type for footsteps and footprints.
- [Decal Manager](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/decal-manager/) controls pooled decal placement and lifetime.
- [Object Pool](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/object-pool/) explains reuse of spawned feedback objects.
## Developer reference
`SurfaceIdentifier` is `Opsive.UltimateCharacterController.SurfaceSystem.SurfaceIdentifier`. It exposes writable `SurfaceType` and `AllowDecals` properties. Change only `SurfaceType` after the Collider has been queried:
```csharp
using Opsive.UltimateCharacterController.SurfaceSystem;
using UnityEngine;
public sealed class RuntimeSurfaceIdentity : MonoBehaviour
{
[SerializeField] private SurfaceIdentifier m_SurfaceIdentifier;
[SerializeField] private SurfaceType m_WetSurfaceType;
public void BecomeWet()
{
m_SurfaceIdentifier.SurfaceType = m_WetSurfaceType;
}
}
```
`SurfaceManager.GetSurfaceIdentifier(Collider)` returns the cached hierarchy result for a non-terrain Collider. `GetSurfaceType(RaycastHit, Collider)` returns the detected type. `GetSurfaceEffect(RaycastHit, Collider, SurfaceImpact, ref SurfaceType, ref bool)` also exposes the final fallback-resolved type, effect, and decal decision. The static `SurfaceManager.SpawnEffect` overloads perform the normal response.
Surface Identifier has no `Awake`, enable/disable, update, or destruction lifecycle logic and emits no dedicated events. Built-in projectile, melee, and footstep consumers query Surface Manager; listen to the originating gameplay system or add a project event around the call when other systems need notification.
The component itself does not obtain or return anything from the Object Pool. Surface Effects can spawn pooled objects, and Decal Manager uses the shared pool for decals. Because Surface Manager caches by Collider, disabling and re-enabling the same pooled instance does not create a new identity lookup.
The two fields are ordinary serialized prefab or scene configuration. Runtime property changes are not automatically recorded by a save system or synchronized across a network. To persist or replicate a dynamic surface, save or send a stable project-owned surface key, map it to the local Surface Type asset, and assign the existing identifier's `SurfaceType` before the next impact. Keep `AllowDecals` invariant for that Collider instance.
---
# Decal Manager
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/decal-manager/)
Use Decal Manager to place pooled impact marks and footprints, reject marks that extend beyond an exposed edge, and gradually retire older marks as new ones arrive.
## Before you begin
Create one direct Surface System response before tuning decal capacity:
1. Open **Tools > Opsive > Ultimate Character Controller > Setup Manager**.
2. On **Scene**, under **Manager Setup**, select **Add Managers**.
3. Select the scene's **Game** object and confirm it has exactly one **Surface Manager**, **Decal Manager**, and shared **Object Pool**.
4. Create a [Surface Impact](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-impacts/), [Surface Effect](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-effects/), and [Surface Type](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-types/). Map the impact to the effect in the type's **Impact Effects** list.
5. Add [Surface Identifier](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-identifiers/) to a test collider, assign the Surface Type, and leave **Allow Decals** enabled.
The runtime can create fallback Decal Manager and Object Pool GameObjects when either singleton is missing, but an explicitly configured **Game** object gives the scene deterministic ownership and settings.
## Configure Decal Manager
Select **Game > Decal Manager** and begin with the released defaults:
| Field | Default | Released Version 3.2.0 behavior |
| --- | --- | --- |
| **Decal Limit** | `100` | When the active decal queue reaches this value, its oldest entry moves to the weathered queue. It is not a hard limit on every visible decal. |
| **Weathered Decal Limit** | `20` | Each transfer into the weathered queue reduces every weathered material's alpha by `1 / Weathered Decal Limit`. When that queue reaches the value, its oldest entry moves to the final fade list. |
| **Remove Fadeout Speed** | `10` | Controls the per-frame interpolation of final-fade alpha toward zero. It is a speed, not a lifetime in seconds. |
Keep **Decal Limit** and **Weathered Decal Limit** at least `1`, and keep **Remove Fadeout Speed** positive. The Inspector does not constrain these integer fields; zero or negative values do not provide a useful bounded lifecycle, and a zero Weathered Decal Limit also makes the weathering division invalid.
Because each queue uses a `>=` comparison, the active and weathered queues normally retain at most one fewer entry than their configured values after a transfer. Decals already in the final fade list are additional. Tune the fields against the project's peak impact rate rather than treating **Decal Limit** as a total object budget.
## Build a compatible decal prefab
Decal Manager expects the decal data on the prefab's root GameObject:
1. Use a simple quad-style mesh whose local forward normal is positive Z. Its first four mesh vertices should represent the four placement-test corners.
2. Add **Mesh Filter** on the root and assign a nonempty mesh with at least four vertices.
3. Add a **Renderer** on the same root and assign a non-null material.
4. Use a transparent material whose color alpha changes the visible result. Decal Manager edits `Renderer.material.color.a` while weathering and resets it to `1` when a pooled instance is reused.
5. Keep the prefab at unit scale when Surface Effect will randomize its size. Avoid adding a Collider that could interfere with the placement raycasts.
6. Save the prefab, create or select a Surface Effect, expand **Decals**, and add the prefab under **Prefabs**. Remove every null list entry.
The built-in placement test reads `MeshFilter.mesh`, the root Renderer, its material, and `mesh.vertices[0]` through `[3]`. A child-only mesh or renderer is not found. An invalid prefab is returned to the pool immediately and no decal remains.
## Choose scale and edge behavior
Configure these fields on **Surface Effect > Decals**:
| Field | Default | Decision |
| --- | --- | --- |
| **Prefabs** | Empty | One prefab is selected randomly. With multiple entries, the immediately previous selection is avoided when possible. |
| **Min Scale** | `1` | Lower bound for the selected decal scale; the Inspector slider range is `0.01` to `2`. |
| **Max Scale** | `1` | Upper bound for the selected decal scale; it cannot be lower than Min Scale in the custom Inspector. |
| **Allowed Decal Edge Overlap** | `0.25` | Shrinks the four tested corner positions toward the mesh origin. Its range is `0` to `0.5`. |
Released Version 3.2.0 treats scale `1` specially. When the random result is exactly `1`, the instance uses the prefab's local scale. For every other result, Decal Manager replaces local scale with `(scale, scale, 1)` rather than multiplying the prefab scale. Authoring the prefab at `(1, 1, 1)` keeps that discontinuity from changing the intended proportions. A footprint may then negate local X to mirror the chosen side.
Edge overlap works as follows:
- `0` raycasts from the first four mesh vertices, requiring support beneath the full tested quad;
- `0.25` tests points halfway from those vertices toward the decal origin; and
- `0.5` skips the four placement raycasts entirely.
There is no **Placement Tests** toggle in released Version 3.2.0. Values below `0.5` always run the test. Each corner ray only needs to hit an eligible collider; it does not require all four rays to hit the original impact collider.
## Decide whether a decal follows its receiver
After placing a decal `0.001` units above the hit point, Decal Manager checks the hit Transform's local scale:
- A uniformly scaled receiver becomes the decal's parent, so the mark follows its movement and rotation.
- A non-uniformly scaled receiver is not used as the parent. The mark is parented under Decal Manager to avoid inherited distortion, so it stays at its world placement and does not follow that receiver.
There is no **Allow Non Uniform Decals** control in this release. Use `(1, 1, 1)` receiver scale for the most predictable world size, use uniform scale when a mark must follow a moving receiver, or implement a project-owned moving-decal solution for non-uniform objects. Uniform parent scale still contributes to the decal's final world scale.
## Connect impacts and footsteps
A decal request normally travels through the Surface System:
1. A projectile, item action, ability, or another caller supplies a **RaycastHit** and [Surface Impact](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-impacts/) to Surface Manager.
2. Surface Manager resolves a Surface Type from the hit collider and finds the Surface Effect mapped to that impact.
3. **Surface Identifier > Allow Decals** and the fallback policy determine whether the effect may request a decal. This Boolean is cached per collider on its first lookup, so author it before Play Mode.
4. Surface Effect selects one **Decals > Prefabs** entry and a scale between **Min Scale** and **Max Scale**.
5. A normal impact requests a randomly rotated decal around the hit normal. [Character Foot Effects](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/character-foot-effects/) uses the footprint overload, supplying the character's forward direction and the left/right flip decision.
New Surface Type assets use the footprint path by default. A legacy or custom-authored type whose hidden `Allow Footprints` value is false sends Character Foot Effects through the regular, randomly rotated decal path instead.
**Fallback Allow Decals** gates cases where the Surface Impact or Surface Type was initially missing. Released Version 3.2.0 does not apply that gate reliably when both exist but their pair is missing and Surface Manager later switches to the fallback type. If a fallback must never leave a mark, map it to a Surface Effect with an empty **Decals > Prefabs** list. See [Advanced Surface System Topics](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/advanced-surface-system-topics/) for the full fallback and cache boundaries.
## Tune pooling and lifecycle
Every accepted decal is obtained with the shared Object Pool. A rejected prefab or edge placement is returned immediately. A weathered decal returns to the pool only after its final fade alpha reaches zero; it is disabled and stored beneath Object Pool until the same prefab is requested again.
The limits do not preallocate instances. For a frequently used decal, select **Game > Object Pool**, add a **Preloaded Prefab** row, assign the decal prefab, and set **Count** to a measured warm capacity. Preload only hot prefabs; the pool can still instantiate additional copies when all preloaded instances are active.
Decal lifetime is spawn-driven:
1. New decals remain fully opaque in the active queue.
2. Once **Decal Limit** is reached, each new accepted decal moves the oldest active decal to the weathered queue.
3. Every such transfer reduces the alpha of all weathered decals. If no more decals arrive, their partial weathering stops indefinitely.
4. Once **Weathered Decal Limit** is reached, the oldest weathered decal enters the final fade list.
5. Only final-fade entries update by time. When one reaches zero alpha, Decal Manager returns it to the pool.
Use a separate project component when a mark requires a fixed time-to-live. Decal Manager exposes no per-decal duration and does not retire active or weathered entries merely because time passes.
## Runtime lifecycle
1. The explicit Decal Manager claims the static singleton when enabled. If none exists when a static spawn method is called, the package creates a `DecalManager` GameObject.
2. Surface Effect asks Decal Manager for a regular mark or direction-aware footprint.
3. The manager takes an instance from Object Pool, positions and rotates it at the hit, chooses its parent, applies scale, validates its mesh and material, and restores alpha to `1`.
4. For overlap values below `0.5`, four short raycasts validate the shrunken mesh corners. A failed placement returns to the pool without entering a capacity queue.
5. An accepted decal enters the active queue. New accepted decals drive active-to-weathered and weathered-to-final-fade transitions.
6. Decal Manager enables its per-frame `Update` only while the final fade list has entries, then disables itself again when that list is empty. Static spawn calls still work while the component is disabled.
7. Scene unload resets the static singleton reference. The queues are scene-local and are not carried into another scene.
## Editor checkpoint
Before Play Mode, confirm that:
- the scene has one explicit Decal Manager and Object Pool on **Game**;
- **Decal Limit** and **Weathered Decal Limit** are at least `1`, and **Remove Fadeout Speed** is positive;
- every Surface Effect decal entry references a prefab rather than `None`;
- each prefab root has Mesh Filter, a mesh with at least four meaningful corner vertices, a Renderer, and a transparent alpha-responsive material;
- prefab scale is `(1, 1, 1)` unless the special scale-`1` behavior is intentional;
- every known Surface Type maps the intended Surface Impact to the Surface Effect;
- each receiver has the intended authored **Allow Decals** value before its first lookup;
- moving receivers that must carry marks have uniform scale;
- no-decal fallback effects have an empty **Prefabs** list; and
- optional Object Pool preload counts reflect measured bursts rather than the Decal Manager limits.
## Verify on several surfaces in Play Mode
1. For an observable test, temporarily set **Decal Limit** to `4`, **Weathered Decal Limit** to `2`, and leave **Remove Fadeout Speed** at `10`.
2. Prepare adjacent wood and metal colliders with different Surface Types. Map the same impact to visibly distinct decal prefabs, and add a third collider whose Surface Identifier has **Allow Decals** disabled.
3. Trigger one impact near the center of each collider. Wood and metal should select their mapped marks; the no-decal collider should still run any configured audio or spawned object but leave no mark.
4. Trigger regular impacts several times on one surface. Confirm their rotation varies and the Surface Effect does not immediately repeat the same prefab when alternatives exist.
5. Trigger footsteps with distinct left/right flip settings. Confirm footprints face with the character and only the configured side mirrors.
6. Hit the center and exposed edge of a large plane with overlap below `0.5`. Confirm the center passes and an unsupported corner is rejected. Repeat at `0.5` and confirm the edge test is skipped.
7. Place marks on a uniformly scaled moving receiver and a non-uniformly scaled moving receiver. Confirm only the uniformly scaled target carries its mark.
8. Spawn enough accepted decals to exceed both small queue thresholds. Confirm older marks weather in arrival order, final-fade entries disappear smoothly, and disabled pooled instances accumulate beneath Object Pool for reuse.
9. Stop spawning while a mark is only partly weathered. Confirm it remains at that alpha, demonstrating that weathering is driven by later accepted decals rather than elapsed time.
10. Restore the production limits, repeat the expected peak burst, and inspect the Hierarchy, rendered result, and Profiler for acceptable active, weathered, fading, and pooled counts.
## Troubleshooting and released-Version-3 limitations
| Symptom | Check | Fix |
| --- | --- | --- |
| No decal appears, but audio or particles do. | Check **Allow Decals**, the resolved impact/type/effect pair, **Decals > Prefabs**, fallback policy, prefab validity, and edge rejection. | Correct the authored route, remove null prefab entries, and test a valid quad prefab at the center of a large receiver. |
| A spawn logs a null-reference exception. | A selected **Prefabs** element is `None`; Decal Manager's low-level spawn path assumes a non-null original. | Remove every null entry and keep the list empty when the effect should not request a decal. |
| The decal appears to spawn and immediately disappears. | The prefab lacks a root Mesh Filter, mesh, Renderer, or material, or a corner placement ray missed. | Put all required components on the prefab root and test with a simple four-corner quad away from edges. |
| Edge rejection is inconsistent. | The first four mesh vertices are not the intended corners, another eligible collider satisfies a corner ray, or overlap is `0.5` and skips testing. | Use a predictable quad mesh, isolate the test geometry, and select a value below `0.5`. |
| Old decals never begin weathering. | The active queue has not reached **Decal Limit**, or no accepted decals arrived afterward. | Lower the threshold for the test or generate more accepted marks. Use a custom time-to-live for age-based removal. |
| A partly faded decal remains forever after impacts stop. | It is still in the weathered queue; only new accepted decals change weathered alpha. | Continue spawning until it enters the final fade list, or implement a time-based lifecycle. |
| More decals are visible than **Decal Limit**. | Active, weathered, and final-fade queues coexist; the field is not a total cap. | Budget all three queues, increase fade speed, reduce both queue thresholds, or own a hard-cap policy in project code. |
| Final-fade decals do not disappear. | **Remove Fadeout Speed** is zero/negative, or **Weathered Decal Limit** is invalid. | Restore positive values; the released defaults are `10` and `20`. |
| A decal pops out instead of fading visibly. | The material is opaque or its shader does not use color alpha for transparency. | Use a transparent shader/material whose visible alpha follows `Renderer.material.color.a`. |
| A mark is too large, stretched, or changes size unexpectedly. | The prefab is not unit scale, the chosen scale is exactly `1` versus another value, or a uniformly scaled parent contributes to world scale. | Author the prefab at unit scale, use a controlled Min/Max range, and keep receiver scale at `(1, 1, 1)` where practical. |
| A mark does not follow a moving non-uniform object. | Version 3.2.0 parents it under Decal Manager to avoid inherited distortion. | Use a uniformly scaled receiver or a project-owned moving-decal implementation. |
| Changing **Allow Decals** during Play Mode has no effect. | Surface Manager cached the Boolean for that collider during its first identifier lookup. | Author it before the first hit, reload the scene, or implement the dynamic gate outside the built-in cache. |
| A fallback creates a decal with **Fallback Allow Decals** disabled. | The original impact and type existed but their pair was missing; the later fallback-type route bypasses that gate. | Add the explicit pair or use a fallback Surface Effect whose **Prefabs** list is empty. |
| Footprints rotate randomly instead of facing the character. | A legacy/custom Surface Type has hidden `Allow Footprints` disabled, or the call used the regular decal path. | Use the footprint path and verify Character Foot Effects direction/flip inputs. New Surface Types default to footprints enabled. |
| Pool errors or stale marks appear after project code removes a decal. | The instance was destroyed or disabled outside Decal Manager/Object Pool ownership. | Let Decal Manager retire its marks, or use `ObjectPoolBase.Destroy` only for project-owned instances created by that same pool. |
## Related tasks
- [Surface System](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/) explains the complete impact, type, and effect relationship.
- [Surface Manager](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-manager/) resolves Surface Types and fallback policies.
- [Surface Effects](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-effects/) configures decal prefabs, scale, and edge overlap.
- [Surface Identifiers](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-identifiers/) assigns the receiver's Surface Type and decal permission.
- [Character Foot Effects](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/character-foot-effects/) supplies footprint direction and mirroring.
- [Advanced Surface System Topics](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/advanced-surface-system-topics/) covers caching, fallback, terrain, and multi-material boundaries.
- [Object Pool](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/object-pool/) explains shared pooled-object ownership and preloading.
## Developer reference
`DecalManager` is in `Opsive.UltimateCharacterController.SurfaceSystem`. Its public configuration properties are `DecalLimit`, `WeatheredDecalLimit`, and `RemoveFadeoutSpeed`.
`DecalManager.Spawn(GameObject, RaycastHit, float, float)` places a regular, randomly rotated decal. `DecalManager.SpawnFootprint(GameObject, RaycastHit, float, float, Vector3, bool)` uses a direction and optional X-axis flip. Both methods are static, return `void`, and bypass Surface Manager's impact mapping, identifier permission, and fallback policy when called directly. They do not report whether prefab validation or the edge test rejected the placement.
The active, weathered, final-fade, renderer, and mesh collections are private. There is no public per-decal remove method, count query, placement-result event, fixed-lifetime setting, or queue-reset API. Derive a separate project system when those controls are required rather than editing the manager's internal lists.
Decals are transient visual feedback. Decal Manager does not save them, restore them after a scene load, or send a network message. A multiplayer game must reproduce an impact request on the clients that should see it and provide matching Surface System assets; Decal Manager itself performs no replication. Pool returns and scene-unload cleanup also publish no gameplay event.
---
# Character Foot Effects
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/character-foot-effects/)
Use Character Foot Effects to detect each step, raycast to the ground below it, and let the Surface System choose the audio, decal, particle, or other response for the material under the character.
## Before you begin
Set up one complete footstep response before tuning detection:
1. Open **Tools > Opsive > Ultimate Character Controller > Setup Manager**.
2. On **Scene**, under **Manager Setup**, select **Add Managers**. Confirm the scene's **Game** object has **Surface Manager**, **Decal Manager**, and the shared **Object Pool**.
3. In the Project window, choose **Assets > Create > Opsive > Ultimate Character Controller > Surface Impact**, save the asset as `Footstep`, and review [Surface Impacts](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-impacts/).
4. Choose **Assets > Create > Opsive > Ultimate Character Controller > Surface Effect** for each response, such as wood audio, metal audio, a dust particle, or a footprint decal. See [Surface Effects](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-effects/).
5. Select each [Surface Type](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-types/). Add an **Impact Effects** element, assign `Footstep` to **Surface Impact**, and assign that material's response to **Surface Effect**.
6. Give each test floor collider a [Surface Identifier](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-identifiers/), assign its **Surface Type**, and leave **Allow Decals** enabled only where a footprint decal is appropriate.
7. Confirm the character has Ultimate Character Locomotion, Character Layer Manager, an Animator Monitor, and an Animator before adding foot effects through Character Manager.
The detector and Surface System are separate. A correctly timed step can still be silent when its Surface Impact, detected Surface Type, or mapped Surface Effect is missing.
## Add Character Foot Effects
1. Open **Tools > Opsive > Ultimate Character Controller > Character Manager**.
2. Assign the scene model for a new character, or assign the Ultimate Character Locomotion root to **Character** for an existing character. Verify every **Character Model** row and its Animator Controller.
3. Enable **Foot Effects**. It starts enabled for a new character.
4. Select **Build Character** for a new character or **Update Character** for an existing character.
5. Select each animated model below the character root. Character Manager adds **Character Foot Effects** to the same GameObject as its Animator Monitor.
6. For a Humanoid Animator, verify that **Feet** references the left and right toe bones when available, otherwise the foot bones. The builder flips the generated right-foot entry and, when a foot has no Audio Source, adds one with **Volume** `0.4`, **Spatial Blend** `1`, and **Max Distance** `20`.
7. For a Generic Animator or custom rig, assign the contact transforms manually. Character Manager cannot infer non-humanoid feet.
8. Expand **Character Foot Effects > Footprint**, assign the `Footstep` **Surface Impact**, select **Footstep Mode**, and tune the fields for that mode.
Character Foot Effects starts with **Body Step** as the serialized mode. Its released field defaults are:
| Field | Default | Purpose |
| --- | --- | --- |
| **Surface Impact** | None | Identifies the footstep when Surface Manager chooses a response. |
| **Footstep Mode** | **Body Step** | Chooses how an automatic step is detected. |
| **Feet** | None | Holds the contact Transforms. Character Manager initializes two entries only when it can resolve a Humanoid head and foot or toe bones. |
| **Foot Offset** | `0.11` | Extends the downward ground raycast. It is not the Body Step height threshold. |
| **Move Direction Frame Count** | `7` | Filters brief foot-direction changes in Body Step mode. |
| **Min Trigger Interval** | `0.1` | Prevents Trigger mode from accepting another step too soon. |
| **Require Movement** | Enabled | Makes Trigger mode ignore contact while horizontal local velocity is nearly zero. |
| **Require Alternating Feet** | Enabled | Makes Trigger mode reject the same foot twice in succession. |
| **Fixed Interval** | `0.3` | Sets the time between Fixed Interval step groups while grounded and moving. |
| **Min Bob Interval** | `0.2` | Sets the minimum time between Camera Bob steps. |
## Choose how a step is detected
| Mode | Use it when | How released Version 3.2.0 detects a step |
| --- | --- | --- |
| **Body Step** | Animated feet make dependable contact and exact left/right timing matters. | While the character is grounded and moving, it watches each configured foot's vertical motion. A descending foot can step after its direction has remained stable for **Move Direction Frame Count** and it is not the last accepted foot. |
| **Trigger** | Physical foot contact is more reliable than animation motion. | A **Footstep Trigger** on the contacting foot calls Character Foot Effects from `OnTriggerEnter`. **Min Trigger Interval**, **Require Movement**, and **Require Alternating Feet** filter the call. The **Feet** array is not used. |
| **Fixed Interval** | A steady cadence is more important than exact contact. | While grounded and moving, it cycles the configured foot groups every **Fixed Interval**. The group origin is raycast even when that particular foot is not touching the ground. |
| **Camera Bob** | A first-person view has a reliable vertical bob. | After a look source is attached, it detects the low point where the view changes from descending to ascending, then cycles a foot group. **Min Bob Interval** suppresses close repeats. |
| **None** | Project code or animation events own the timing. | No built-in automatic detector runs. Use a small relay to call `TriggerFootStep` or `FootStep`; an animation-event mode is not exposed in this Inspector. |
All four automatic routes still end with the same ground raycast and Surface System lookup. Body Step does not compare the foot's height with **Foot Offset**. The offset only increases how far the final ray can reach below the selected origin.
### Configure Trigger mode
For each contacting foot:
1. Add a Collider sized around the contact area and enable **Is Trigger**.
2. Add **Footstep Trigger** to the same GameObject.
3. Set **Flip Footprint** on the side that needs a mirrored decal.
4. Ensure Unity can produce `OnTriggerEnter` for the foot and floor collider. A Character Manager build supplies the character root's kinematic Rigidbody; a manually assembled character still needs a valid Unity trigger/Rigidbody arrangement.
5. Put the floor on a layer that is not the character's layer, **Water**, or one of Character Layer Manager's **Invisible Layers**. Both Footstep Trigger and the final ground ray use the derived `IgnoreInvisibleCharacterWaterLayers` mask.
6. Enter Play Mode and confirm each contact passes **Require Movement**, **Require Alternating Feet**, and **Min Trigger Interval**.
Footstep Trigger ignores contacts outside the character's `IgnoreInvisibleCharacterWaterLayers` mask. It also suppresses steps for three fixed-update intervals after an immediate transform change, which prevents a teleport from creating a false contact.
## Map feet, sides, and groups
Each **Feet** entry contains:
- **Object**: the Transform whose position becomes the step raycast origin;
- **Group**: the group used by Fixed Interval and Camera Bob; every Transform in the active group steps together, then the component advances to the next group; and
- **Flipped Footprint**: mirrors the footprint decal on its local X axis, normally for the right side.
Body Step evaluates feet individually and ignores **Group**. Trigger mode receives its Transform and flip setting from Footstep Trigger, so it ignores the **Feet** list entirely.
For a biped with group-driven placement, place the left foot in group `0` and the right foot in group `1`. For a quadruped, group the contacts that should land together. Keep group numbers contiguous from `0`; an unused group produces an interval with no step.
At `Awake`, a null or zero-length **Feet** list creates one fallback group at the Character Foot Effects GameObject. That fallback is useful for a centered Fixed Interval or Camera Bob sound, but not for separate left/right footprints. It does not make Body Step valid: an empty list detects no feet, and a null list on a non-humanoid can fail when Body Step evaluates it.
Released Version 3.2.0 displays **Feet** only while **Body Step** is selected even though Fixed Interval and Camera Bob reuse serialized groups. To configure those origins in the Inspector, select Body Step, edit **Feet**, then switch to the intended group-driven mode before saving.
The released footprint direction is the forward direction of the GameObject that owns Character Foot Effects. A Feet **Object** supplies position, not facing. Align the model/component transform with the character's forward direction, then use **Flipped Footprint** for side mirroring.
## Choose the surface response
Keep one Footstep Surface Impact and vary the Surface Effect by Surface Type:
| Desired result | Configure it on the mapped Surface Effect |
| --- | --- |
| Positional footstep sound | Under **Audio**, assign **Audio Config** or leave it empty and configure **Audio Clips**, **Min/Max Volume**, **Min/Max Pitch**, **Random Clip Selection**, and **Min Audio Clip Frame Interval**. The footprint path plays audio on the foot originator. |
| Dust, splash, or debris | Under **Spawned Objects**, assign a pool-safe **Object** and set **Probability**. The effect spawns at the ground hit. |
| Left/right footprint | Under **Decals**, assign **Prefabs**, set **Min Scale**, **Max Scale**, and **Allowed Decal Edge Overlap**, enable **Allow Decals** on the Surface Identifier, and configure the foot's flip setting. |
| Surface-specific combinations | Map the same Footstep Surface Impact to a different Surface Effect in every Surface Type. |
| A safe response for an unidentified floor | Surface Manager starts with **Fallback Surface Impact** and **Fallback Surface Type** unassigned, while **Fallback Allow Decals** starts enabled. Assign both fallback assets deliberately. If a fallback must never leave a decal, map it to a Surface Effect whose **Prefabs** list is empty; the released later missing-pair fallback path does not always apply **Fallback Allow Decals**. |
New Surface Type assets serialize `Allow Footprints` as enabled, which selects the direction-aware footprint path. Released Version 3.2.0's custom Surface Type inspector does not draw that field. Use the visible **Surface Identifier > Allow Decals** setting and the Surface Effect's **Decals > Prefabs** list for normal editor authoring. A legacy or custom-authored Surface Type with the hidden field disabled uses the regular response path instead; it still plays audio, spawns objects, applies a State, and can request an ordinary decal.
## How it runs
1. At initialization, the component builds its foot groups. Body Step and Fixed Interval run from `FixedUpdate`; Trigger waits for Footstep Trigger; None waits for project code; and Camera Bob begins after an `ILookSource` attaches.
2. For a locally controlled character, Body Step, Fixed Interval, and Camera Bob return unless Ultimate Character Locomotion reports both **Grounded** and **Moving**. Trigger mode is contact-driven and applies its own optional movement filter instead.
3. The selected placement mode accepts a foot or foot group only while its direction, interval, bob, or contact rules pass.
4. `FootStep` casts from `0.2` units above the selected Transform, down along the character model's local down direction. The base distance is `0.21 + Foot Offset`, with additional reach for vertical movement. Trigger colliders are ignored.
5. Surface Manager resolves the hit collider's Surface Type and pairs it with the configured Surface Impact.
6. With the normal new-Surface-Type default, Surface Effect spawns objects, plays audio on the foot originator, applies its optional State, and asks Decal Manager for a direction-aware footprint. A custom type whose hidden `Allow Footprints` value is false uses the regular response path.
7. Spawned feedback objects and decals use the shared object pool. The surface and decal policies decide whether a footprint decal is permitted.
`FootStep` returns `true` when its ground raycast hits. It ignores the Boolean returned by Surface Manager, so an accepted step can update the last-foot and interval state even when no Surface Effect resolves. Diagnose detection and surface mapping as separate checkpoints.
## Editor checkpoint
Before Play Mode, confirm that:
- Character Manager's **Foot Effects** option produced one Character Foot Effects component for each intended animated model;
- Generic and custom rigs have explicit contact Transforms;
- the Footstep **Surface Impact** is assigned and appears once in every relevant Surface Type's **Impact Effects** list;
- every test floor resolves its intended Surface Type directly or through an intentional fallback;
- Body Step feet move vertically and have sensible left/right flip settings;
- Trigger feet have working trigger Colliders and Footstep Trigger components;
- Fixed Interval or Camera Bob groups are contiguous, alternate as intended, and do not fall back accidentally to the model origin;
- **Foot Offset** is only large enough to reach the expected floor below each origin;
- footprint receivers use the intended **Allow Decals** value, their Surface Effects contain the intended decal prefabs, and any no-decal fallback effect has an empty decal list;
- every decal or spawned-effect prefab is configured for pooling and has a bounded lifetime.
## Verify on several surfaces in Play Mode
1. Place adjacent wood and metal floor colliders. Give each a distinct Surface Type and map the same Footstep impact to clearly different audio. Add a third test floor whose Surface Type has no matching Footstep pair so the configured fallback can be tested without editing an asset during Play Mode.
2. Walk entirely on wood. Confirm the chosen mode produces one sensible step per intended contact and only the wood response plays.
3. Cross slowly onto metal. Confirm the response changes according to the surface directly below each accepted foot, not the character root.
4. Add distinct left and right footprint decals. Confirm their positions alternate, face with the character model, and the configured side is mirrored.
5. Test a small step, slope, and descending motion. Increase **Foot Offset** only if the ground ray misses; do not use it to retime Body Step.
6. For Trigger mode, stop moving with one trigger touching the floor, then start again. Confirm **Require Movement**, alternating-foot filtering, and the minimum interval prevent duplicate contacts.
7. For Fixed Interval or Camera Bob, compare walking and running States with different interval presets. Confirm the cadence changes without double-playing a foot group.
8. Walk onto the intentionally unmapped floor. Confirm Surface Manager uses the intended fallback and that a no-decal fallback remains decal-free.
9. Repeat steps rapidly and watch the Hierarchy and audio output. Pooled objects should return correctly, decal limits should hold, and **Min Audio Clip Frame Interval** should suppress any unacceptable same-frame duplicates.
## Troubleshooting and released-Version-3 limitations
| Symptom | Check | Fix |
| --- | --- | --- |
| Character Foot Effects was not added. | The selected model has no Animator Monitor/Animator, or the Character Manager update did not include **Foot Effects**. | Add the required animated-character components, enable **Foot Effects**, and use **Update Character**. For a Generic rig, verify and configure the component manually. |
| Body Step never fires or logs a null-reference exception. | The character is not grounded and moving, **Feet** is empty or null on a non-humanoid, a Feet **Object** is null, or the animation does not produce stable vertical motion. | Assign every real contact Transform, remove null elements, and tune **Move Direction Frame Count** while observing the animated bones. Do not rely on the group fallback for Body Step. |
| Changing **Foot Offset** does not retime Body Step. | The offset controls the final raycast distance, not the Body Step motion threshold. | Tune the animation/mode and **Move Direction Frame Count** for timing; use **Foot Offset** only for ray reach. |
| Trigger mode never fires. | The foot lacks an **Is Trigger** Collider or Footstep Trigger, the Rigidbody arrangement cannot produce `OnTriggerEnter`, the floor is on Water, the character layer, or an **Invisible Layers** entry, or a movement/alternation/interval rule rejects it. | Correct the Collider, Rigidbody, and layer setup, then temporarily relax one Trigger filter at a time. |
| A step is detected but no sound or particle plays. | `FootStep` can succeed from a ray hit even when Surface Manager cannot resolve a valid impact/type/effect pair. | Verify the assigned Surface Impact, detected Surface Type, explicit **Impact Effects** mapping, and fallback separately. |
| Sound plays but no footprint appears. | The receiver disallows decals, **Decals > Prefabs** is empty, the decal prefab lacks the mesh/renderer data Decal Manager needs, the edge test rejects it, or a legacy/custom Surface Type has hidden `Allow Footprints` disabled. | Enable **Allow Decals**, assign a valid decal prefab, and test away from edges. New Surface Types default to the footprint path; use a project editor tool when an older asset's hidden value must be changed. |
| Both footprints appear together or at the model center. | Group assignments are the same, or **Feet** is empty and the component created one fallback group. | Configure separate left/right groups under Body Step, then restore Fixed Interval or Camera Bob. |
| Fixed Interval or Camera Bob skips a cadence with no response. | The serialized group numbers contain a gap, so the active group can be empty. | Edit **Feet** while Body Step is selected and renumber the groups contiguously from `0`, then restore the intended mode. |
| Footprints face sideways. | Released Version 3.2.0 uses the Character Foot Effects GameObject's forward direction, not the foot Transform's forward direction. | Align the model/component transform with character forward and use the flip setting only for mirroring. |
| Camera Bob produces no steps. | No look source is attached, the view has no vertical bob, the character is not grounded/moving, or **Min Bob Interval** is too large. | Attach the camera/look source, enable a visible bob, and verify the locomotion conditions before reducing the interval. |
| Trigger steps repeat or disappear after teleporting. | The minimum interval, alternating-foot filter, or built-in post-teleport suppression rejected the contact. | Test after three fixed updates, verify each Footstep Trigger passes the correct foot Transform, and tune the trigger filters. |
| Footsteps are too loud or effects accumulate. | Several feet share a group, two detectors are active, audio has no frame interval, or spawned feedback does not return to the pool. | Keep one timing route per model, correct the groups, configure **Min Audio Clip Frame Interval**, and use pool-safe finite effects. |
| An animation event cannot select Footstep mode. | Released Version 3.2.0 has no Animator Event entry in **Footstep Mode**. | Select **None** and use a project relay that calls `TriggerFootStep` or `FootStep`. |
| A fallback footprint appears even with **Fallback Allow Decals** disabled. | The detected impact and type existed, but their pair was missing; Version 3.2.0's later fallback-type path does not mark that lookup as a fallback for the decal check. | Add the explicit pair, or use a fallback Surface Effect with an empty **Decals > Prefabs** list. |
## Related tasks
- [Surface System](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/) explains the Surface Impact + Surface Type + Surface Effect relationship.
- [Surface Manager](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-manager/) configures texture detection and fallbacks.
- [Surface Impacts](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-impacts/) creates the shared Footstep identity.
- [Surface Types](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-types/) maps each floor material to its response.
- [Surface Effects](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-effects/) configures audio, particles, decals, and State changes.
- [Surface Identifiers](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-identifiers/) assigns a deterministic Surface Type to a floor collider.
- [Decal Manager](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/decal-manager/) controls footprint placement tests and decal limits.
- [Advanced Surface System Topics](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/advanced-surface-system-topics/) explains caches, terrain, multi-materials, and runtime boundaries.
- [Generic Character](https://opsive.com/support/documentation/ultimate-character-controller/character/generic-character/) covers manual non-humanoid setup.
- [Audio](https://opsive.com/support/documentation/ultimate-character-controller/audio/) explains Audio Config assets and runtime playback.
## Developer reference
`CharacterFootEffects` is in `Opsive.UltimateCharacterController.Character`. Its public configuration includes `FootstepMode`, `SurfaceImpact`, `Feet`, `MoveDirectionFrameCount`, `FootOffset`, `MinTriggerInterval`, `RequireMovement`, `RequireAlternatingFeet`, `FixedInterval`, and `MinBobInterval`.
`TriggerFootStep(Transform, bool)` applies movement, interval, alternating-foot, and teleport filters before calling the virtual `FootStep(Transform, bool)`. `FootStep` bypasses those Trigger filters, performs the ground raycast, and forwards it to the footprint overload of `SurfaceManager.SpawnEffect`. Override `FootStep` only when the project needs a different contact query or additional bookkeeping.
There is no built-in Animator Event mode. For deliberately authored animation timing, select **None** and put a small relay on the Animator GameObject:
```csharp
using Opsive.UltimateCharacterController.Character;
using UnityEngine;
public sealed class FootstepAnimationRelay : MonoBehaviour
{
[SerializeField] private CharacterFootEffects m_FootEffects;
[SerializeField] private Transform m_LeftFoot;
[SerializeField] private Transform m_RightFoot;
public void LeftFootstep()
{
m_FootEffects.FootStep(m_LeftFoot, false);
}
public void RightFootstep()
{
m_FootEffects.FootStep(m_RightFoot, true);
}
}
```
Add `LeftFootstep` and `RightFootstep` Animation Events to the clips at contact. This relay calls `FootStep`, so each event still performs the ground raycast but bypasses the Trigger-only filters. Call `TriggerFootStep` instead when the animation events should obey **Require Movement**, **Require Alternating Feet**, **Min Trigger Interval**, and teleport filtering. Those fields are hidden while **None** is selected; configure them while **Trigger** is selected, then switch back to **None**.
`SurfaceType.AllowFootprints` is public read-only at runtime and its backing `m_AllowFootprints` field defaults to `true`, but the released custom inspector draws only **Impact Effects**. A project that must change an existing asset's hidden value should do so through a controlled editor tool using `SerializedObject`, then verify whether the direction-aware or regular decal path is intended.
The component listens for `OnCharacterAttachLookSource`, `OnCharacterChangePerspectives`, `OnCharacterMoving`, and `OnCharacterImmediateTransformChange` to prepare Camera Bob data, delay the first moving step, and suppress teleport contacts. It does not publish a separate footstep event.
Footstep feedback is transient and is not saved. The component does not send a footstep network message. With the UCC multiplayer define enabled, non-authoritative, non-local remote characters gate the `FixedUpdate`-driven modes on interpolated movement plus a ground raycast; each client still needs matching Surface System assets and pooled feedback. Trigger or project-invoked calls are not sent by Character Foot Effects itself.
---
# Advanced Surface System Topics
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/advanced-surface-system-topics/)
Use these workflows when a basic Surface Identifier is not enough: one renderer contains several materials, a terrain blends textures, a runtime object changes material identity, or frequent impacts need stricter control over decals, pooling, and detection cost.
## Before you begin
Build and verify one simple response first:
1. Add the scene managers with **Tools > Opsive > Ultimate Character Controller > Setup Manager**, **Scene > Manager Setup > Add Managers**.
2. Confirm the scene's **Game** object has **Surface Manager**, **Decal Manager**, and the shared **Object Pool**.
3. Create one Surface Impact, Surface Type, and Surface Effect, then map the impact to the effect in the type's **Impact Effects** list.
4. Add **Surface Identifier** to a test collider, assign the type, and trigger the impact in Play Mode.
5. Continue only after that direct route resolves the expected sound, object, decal, or State.
The advanced resolvers still end at the same Surface Impact + Surface Type mapping. They change how the Surface Type is detected, not what the Surface Effect means.
## Choose the simplest reliable resolver
| Situation | Recommended route |
| --- | --- |
| One collider has one logical material | Add [Surface Identifier](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-identifiers/). It is the first lookup and avoids texture, UV, terrain, and submesh analysis. |
| Many simple objects share one texture | Add one **Object Surfaces** entry on Surface Manager, assign the Surface Type, select **Add Texture**, and keep **UV** at `(0, 0, 1, 1)`. |
| One mesh uses several renderer materials | Use a readable mesh, a MeshCollider that produces a triangle index, and matching renderer/collider triangle and submesh data. Map every material texture once. |
| One texture atlas represents several surfaces | Prefer separate colliders with Surface Identifiers in released Version 3.2.0. Repeating one texture for several UV regions has an initialization defect described below. |
| Terrain blends several layers | Map each Terrain Layer diffuse texture to its Surface Type. The manager chooses the dominant layer at the hit position. |
| A runtime object changes from dry to wet, clean to dirty, or another identity | Put Surface Identifier on the collider before its first hit and change its `SurfaceType` property. Do not rebuild texture or hierarchy mappings at runtime. |
| The project needs a different query or response | Perform the project-owned detection, use the public diagnostic APIs where helpful, or derive a Surface Effect/Character Foot Effects response. There is no pluggable resolver interface in this release. |
## Follow the detection and fallback order
For each `RaycastHit`, Surface Manager checks:
1. a cached **Surface Identifier** on the hit Collider GameObject, then one found in its children, then one found in its parents;
2. a cached simple main texture mapping;
3. multi-material, UV-region, or supported secondary-texture resolution;
4. the dominant mapped Terrain Layer texture, optionally including terrain trees; and
5. Surface Manager **Fallbacks** when the impact, detected type, or resulting pair cannot produce an effect.
Keep one obvious Surface Identifier near each collider when a hierarchy contains several renderers or identifiers. The first child or parent discovered by the component searches is cached; rearranging that hierarchy later does not force a new search.
The fallback chain is pair-based:
- a missing Surface Impact is replaced by **Fallback Surface Impact**;
- a missing Surface Type is replaced by **Fallback Surface Type**;
- when the resolved type has no mapping for the current impact, Version 3 next tries the current impact on **Fallback Surface Type**;
- if that still has no effect, it tries **Fallback Surface Impact** on that fallback type; and
- if no valid pair exists, nothing spawns.
Do not use fallbacks to hide incomplete core mappings. Add an explicit Impact Effect entry to every known Surface Type, then reserve fallbacks for genuinely unknown inputs.
Released Version 3.2.0 applies **Fallback Allow Decals** when the impact or type was initially missing. It does not mark the later “pair missing, switch to fallback type” path as a fallback for that decal check. When a fallback effect must never create decals, omit decals from that effect or provide every expected explicit pair.
## Map textures and multiple materials
### One texture per surface
1. Select **Surface Manager** on the scene's **Game** object.
2. Add an **Object Surfaces** row and select it.
3. Assign its **Surface Type**, select **Add Texture**, and assign the exact texture used by the material.
4. Leave **UV** at `(0, 0, 1, 1)` for the complete texture.
5. Set **Main Texture Property Name** to the shader property that holds the texture. The released default is `_BaseMap`; a shader using `_MainTex` or a custom name must be configured explicitly before Play Mode.
6. Restart Play Mode after changing the list or shader-property name so the manager rebuilds its lookup dictionaries and property ID in `Awake`.
A material with no usable texture cannot participate in texture mapping. Add Surface Identifier to its collider instead.
### Multiple renderer materials
The released resolver can identify the hit submesh, but only when all of these conditions are true:
- the physics hit supplies `triangleIndex`, which requires a MeshCollider;
- Surface Manager can find an enabled, non-skinned Renderer on the collider, a child, or a parent;
- it can find a readable MeshFilter mesh or readable MeshCollider shared mesh with triangle data;
- the hit triangle indexes correspond to the Renderer mesh submeshes; and
- the Renderer has a non-null shared material at the resolved submesh index.
This corrects the legacy claim that a MeshCollider itself prevents multi-material detection. In Version 3.2.0 the MeshCollider hit is required for the triangle/submesh path. Detection still fails when collider and renderer meshes do not share the same logical triangle layout, when Read/Write is disabled, or when static batching changes the mesh relationship. Use separate single-material colliders with Surface Identifiers when that relationship cannot be guaranteed.
### UV regions and secondary textures
The Inspector exposes repeated **UV** rectangles, and the runtime can compare an adjusted `RaycastHit.textureCoord` against a region. However, released Version 3.2.0 also inserts every configured texture into a single texture-to-surface dictionary with `Add`. Registering the same atlas texture more than once can throw a duplicate-key exception during Surface Manager `Awake` before those UV mappings are usable.
For this release, do not build production detection around repeated atlas entries. Split the geometry or colliders and assign Surface Identifiers, use distinct textures, or maintain a bounded project resolver. A UV region also requires a MeshCollider; a Unity primitive Collider does not provide the needed triangle/texture-coordinate route.
The built-in secondary-map path recognizes material properties named `_Mask` and `_MainTex2`. It reads the mask texture pixel at the hit UV and selects the secondary texture when alpha exceeds `0.5`. The mask must be a readable `Texture2D`; otherwise use a Surface Identifier or project-specific material resolver.
## Detect terrain and trees
1. Add each Terrain Layer's **Diffuse Texture** to the appropriate Surface Manager **Object Surfaces** mapping.
2. Trigger impacts on clearly dominant areas first. The manager samples the terrain alphamap cell at the hit position and chooses the layer with the highest weight; it does not blend two Surface Effects.
3. Test painted boundaries repeatedly and decide whether a dominant-layer switch is acceptable for footsteps and impacts.
4. Leave **Detect Terrain Tree Textures** disabled unless trees genuinely need texture resolution. It starts disabled and its tooltip correctly warns that the operation is CPU intensive.
Tree detection iterates terrain tree instances, obtains a prototype object through the pool, positions it, synchronizes physics, and raycasts its Collider until a texture is found. Use direct identifiers on independently instantiated tree prefabs or another project-owned lookup for frequent impacts in a large forest.
Terrain lookup also uses the same texture-to-surface dictionary initialized from **Object Surfaces**. One exact texture should map to one Surface Type.
## Plan runtime surface changes around the caches
Surface Manager caches identifiers, decal permission, renderers, meshes, main textures, simple detected types, terrain components, and impact-to-effect dictionaries. Its Object Surfaces maps and main texture property ID are initialized in `Awake`.
| Runtime change | Released-Version-3 behavior |
| --- | --- |
| Change `SurfaceIdentifier.SurfaceType` on an identifier that existed before detection | Supported for later type queries because the cached identifier reference is read again. |
| Change `SurfaceIdentifier.AllowDecals` after the first lookup | Not reflected; decal permission is cached as a Boolean per Collider. |
| Add or move a Surface Identifier after the Collider was queried | Not rediscovered; the earlier component or null result remains cached. |
| Swap a Renderer, Mesh, material, main texture, or collider hierarchy after detection | Existing cache entries remain; later hits can use the original relationship. |
| Edit Surface Type **Impact Effects** after that type resolved once | The first mapping dictionary remains cached. Duplicate Surface Impact entries also use only the first and log a warning. |
| Edit **Object Surfaces** or **Main Texture Property Name** after `Awake` | The lookup dictionaries or shader property ID are not rebuilt. The public name setter alone does not refresh the ID. |
| Spawn a new, fully configured Collider and identifier | Its first lookup can be cached normally. Keep its hierarchy and identifier stable afterward. |
For a supported wet/dry switch, author both Surface Types, put one Surface Identifier on the collider from the start, and swap only its `SurfaceType`. Keep **Allow Decals** constant. When the renderer itself must change, let Surface Identifier remain the authoritative material identity instead of asking the texture resolver to notice the swap.
There is no public cache-clear or rebuild API. Stop and restart Play Mode for authored changes, reload the scene for a deliberate runtime rebuild, or own the dynamic detection in project code.
## Coordinate impacts, effects, footsteps, and decals
- Give each cause its own [Surface Impact](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-impacts/), such as Footstep, Bullet Hit, or Melee Hit. Do not create a different impact for wood and metal; Surface Type owns that distinction.
- In every [Surface Type](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-types/), keep one **Impact Effects** entry per Surface Impact. The first duplicate wins and later duplicates are ignored with a warning.
- A [Surface Effect](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-effects/) can spawn pooled objects, play an Audio Config or clips, activate a State on the hit GameObject, and request one decal. Keep high-frequency footstep effects lighter than rare explosions or heavy impacts.
- **Allow Decals** on Surface Identifier is cached per collider. **Allow Footprints** on Surface Type selects `SpawnFootprint` when true; when false, the manager calls the regular `Spawn` response instead, so audio, objects, State, and an ordinary decal can still run.
- [Character Foot Effects](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/character-foot-effects/) raycasts below the chosen foot and calls the footprint overload. Its `FootStep` method returns success when the raycast hits even if no Surface Effect pair resolves, so diagnose the type/effect mapping separately from footstep timing.
Decal Manager obtains decals through the shared object pool, needs a MeshFilter, mesh, Renderer, and material on the prefab, and can reject a decal by raycasting its first four mesh vertices near an exposed edge. Use a simple quad-style decal mesh.
Current code avoids non-uniform-parent warping by parenting a decal to the hit transform only when that transform has uniform local scale. On a non-uniform target, it parents the decal under Decal Manager instead. The decal therefore remains unwarped but does not follow a moving or rotating receiver; use uniform receiver scale or a project-owned moving-decal solution.
## Control pooling and cost
1. Keep one explicit Surface Manager, Decal Manager, and Object Pool in the scene rather than relying on runtime fallback objects.
2. Use Surface Identifier for frequently hit geometry. It avoids renderer, readable-mesh, submesh, UV, and terrain work after the identifier lookup.
3. Keep **Detect Terrain Tree Textures** disabled for ordinary terrain footsteps and projectiles.
4. Limit complex multi-material hits on high-triangle meshes. Renderer and mesh references are cached, but the resolver still scans submesh triangle arrays to identify the hit material.
5. Tune Decal Manager **Decal Limit**, **Weathered Decal Limit**, and **Remove Fadeout Speed**; released defaults are `100`, `20`, and `10`.
6. Use Surface Effect **Min Audio Clip Frame Interval** to suppress duplicate high-frequency audio, and use Spawned Object **Probability** deliberately.
7. Ensure spawned-effect and decal prefabs are pool-safe and reset their visible state when reactivated. Durable gameplay objects should have their own lifecycle rather than being treated as disposable feedback.
## Editor checkpoint
Before Play Mode, confirm that:
- one direct Surface Identifier test already resolves the intended Surface Impact + Surface Type pair;
- each known Surface Type has one explicit entry for every impact it should handle;
- **Main Texture Property Name** matches the shader before Surface Manager `Awake`;
- each texture is registered once, and no production atlas depends on duplicate UV entries in released Version 3.2.0;
- multi-material objects use a readable, triangle-compatible MeshCollider and Renderer mesh, or direct identifiers instead;
- every Terrain Layer diffuse texture that matters has one mapping, while tree detection is enabled only with a measured need;
- runtime-changing objects start with a stable Surface Identifier and constant decal policy;
- decal prefabs contain the required quad-style mesh and renderer, and moving decal receivers use uniform scale;
- Decal Manager limits, audio frame interval, and spawned-object probabilities match the expected impact rate; and
- fallback assets are deliberate safety nets rather than substitutes for missing primary mappings.
## Verify advanced cases in Play Mode
1. Hit two Surface Identifier colliders with the same Surface Impact and confirm their distinct Surface Types choose different effects.
2. Hit a simple texture-mapped collider without an identifier. Confirm the exact configured texture resolves, then change **Main Texture Property Name** to an incorrect value in Edit Mode and confirm the test fails after a fresh Play Mode start.
3. Test a two-material readable mesh with a MeshCollider. Hit triangles in each submesh and confirm the resolved effect follows the Renderer material. Repeat with mismatched collider geometry and confirm the diagnostic fails rather than assuming a material.
4. On terrain, paint two large dominant regions and cross the boundary with footsteps. Confirm one dominant type is chosen per hit and tree detection remains off.
5. Change a pre-existing Surface Identifier's `SurfaceType` through project code and confirm the next hit uses the new type. Change **Allow Decals** only after the first hit and confirm why that cached permission is not a supported switch.
6. Remove one primary Impact Effect mapping and test the fallback chain. Confirm the resolved type/effect and decal policy, then restore the explicit mapping.
7. Spawn a decal on a uniform stationary receiver, a uniform moving receiver, and a non-uniform moving receiver. Confirm parenting/following behavior and edge rejection are acceptable.
8. Generate enough repeated effects to reach the configured decal and audio limits. Confirm old decals weather/fade and pooled feedback does not accumulate unbounded active objects.
## Troubleshooting and released-Version-3 limitations
| Symptom | Check | Fix |
| --- | --- | --- |
| Surface Manager throws a duplicate-key error during `Awake` | The same texture appears more than once in **Object Surfaces**, commonly for atlas UV regions. | Register each texture once. Use Surface Identifiers, separate textures, or a bounded custom resolver for multiple regions. |
| A multi-material hit always uses fallback | The hit is not from a MeshCollider, `triangleIndex` is unavailable, the mesh is not readable, or collider triangles do not match Renderer submeshes. | Use a readable matching MeshCollider/Renderer mesh or split the colliders and assign Surface Identifiers. |
| A Unity primitive or non-mesh Collider cannot resolve an atlas region | UV-region resolution requires a MeshCollider hit and texture coordinates. | Use Surface Identifier or author a suitable MeshCollider workflow. |
| A material swap still uses the old type | Renderer, main texture, or simple type was cached for that Collider. | Keep a pre-existing Surface Identifier authoritative and change only its `SurfaceType`, or rebuild through a scene reload. |
| Adding Surface Identifier at runtime has no effect | The Collider's earlier identifier lookup cached `null` or another component. | Add the identifier before the first hit or use project-owned resolution for that dynamic object. |
| Changing **Allow Decals** at runtime has no effect | Decal permission was cached during the first identifier lookup. | Treat it as authored configuration or implement the dynamic decision in a custom response. |
| A detected Surface Type ignores a changed Impact Effect | Its impact/effect dictionary was cached on first use. | Author asset mappings before Play Mode and restart the test after edits. |
| Fallback response creates an unexpected decal | The primary pair was missing and the later fallback-type path does not apply **Fallback Allow Decals** in released Version 3.2.0. | Add the explicit pair or use a fallback effect with no decal. |
| Terrain always chooses one material near a blend | Resolution selects the single highest alphamap weight at the hit cell. | Paint a clearer boundary or accept/project a custom blend policy. |
| Tree impacts cause spikes | **Detect Terrain Tree Textures** performs per-tree pooled instantiation, physics synchronization, and raycasts. | Disable it and use direct identifiers or a project-owned tree lookup. |
| A footstep ray hits but no feedback plays | Character Foot Effects found ground, but the Surface Impact + resolved Surface Type pair has no Surface Effect. | Inspect detection and the type's explicit **Impact Effects** mapping separately from foot timing. |
| A decal does not appear | The identifier/fallback disallows it, the Surface Effect has no valid decal, its prefab lacks required components, or the edge test rejects it. | Verify the resolved route, use a quad-style prefab, and test away from an exposed edge. |
| A decal does not follow a non-uniform moving object | Decal Manager parents it under itself to prevent inherited scale distortion. | Use uniform receiver scale or a moving-decal implementation designed for that object. |
## Related tasks
- [Surface System](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/) covers the core impact, type, and effect workflow.
- [Surface Manager](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-manager/) configures Object Surfaces, terrain detection, and fallbacks.
- [Surface Identifiers](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-identifiers/) provides deterministic collider-based type selection.
- [Surface Impacts](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-impacts/) defines the cause of an effect.
- [Surface Types](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-types/) maps causes to effects and controls footprint handling.
- [Surface Effects](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-effects/) configures spawned objects, decals, audio, and State responses.
- [Character Foot Effects](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/character-foot-effects/) configures step detection and footprint placement.
- [Decal Manager](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/decal-manager/) configures limits, weathering, and edge placement.
- [Object Pool](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/object-pool/) explains reusable feedback object ownership.
- [State System](https://opsive.com/support/documentation/ultimate-character-controller/state-system/) configures the optional State activated by a Surface Effect.
## Developer reference
The released surface types are in `Opsive.UltimateCharacterController.SurfaceSystem`. `SurfaceManager.SpawnEffect` has regular and footprint overloads, each with an optional explicit Collider. It returns `true` when it resolves and invokes a Surface Effect. With a component reference, `GetSurfaceType(RaycastHit, Collider)` returns the detected type, while `GetSurfaceEffect(RaycastHit, Collider, SurfaceImpact, ref SurfaceType, ref bool)` exposes the final resolved type, effect, and decal decision.
Use those query methods for a diagnostic before replacing the resolver:
```csharp
using Opsive.UltimateCharacterController.SurfaceSystem;
using UnityEngine;
public sealed class SurfaceDiagnostic : MonoBehaviour
{
[SerializeField] private SurfaceManager m_SurfaceManager;
[SerializeField] private SurfaceImpact m_SurfaceImpact;
public void LogHit(RaycastHit hit)
{
var detectedType = m_SurfaceManager.GetSurfaceType(hit, hit.collider);
SurfaceType resolvedType = null;
var allowDecals = false;
var effect = m_SurfaceManager.GetSurfaceEffect(
hit, hit.collider, m_SurfaceImpact, ref resolvedType, ref allowDecals);
Debug.Log($"Detected: {detectedType}; Resolved: {resolvedType}; " +
$"Effect: {effect}; Decals: {allowDecals}");
}
}
```
`SurfaceIdentifier.SurfaceType` and `AllowDecals` are writable, with the cache boundaries described above. `SurfaceEffect.Spawn` and `SpawnFootprint` are virtual extension points for a custom response. `CharacterFootEffects.FootStep` is virtual for custom foot detection. `DecalManager.Spawn` and `SpawnFootprint` are lower-level static decal entry points.
Surface Manager's type-resolution methods are public but not virtual, and the package has no resolver interface or cache invalidation API. A project that needs dynamic renderer/material resolution should keep that decision outside the built-in cache, then call a chosen Surface Effect or another project response deliberately.
---
# Spawn System
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/spawn-system/)
Use the Spawn System to return characters and world objects at a controlled location after death, disablement, or a manual reset. A Respawner controls when the object returns; Spawn Points control where it can return.
## Choose your route
- [Respawner](https://opsive.com/support/documentation/ultimate-character-controller/spawn-system/respawner/) covers return timing, positioning modes, audio, and the respawn events. Start there when an object already has a destination or should return where it began.
- [Spawn Points](https://opsive.com/support/documentation/ultimate-character-controller/spawn-system/spawn-points/) covers candidate locations, groups, shapes, ground snapping, and obstruction checks. Add these when a Respawner should choose among scene locations.
Use both pages for a deathmatch spawn, checkpoint group, or random arena placement. A single object that only needs to return to its original transform can use a Respawner with **Positioning Mode** set to **Start Location** and does not need a Spawn Point.
## Set up the scene
1. Open **Tools > Opsive > Ultimate Character Controller > Setup Manager**.
2. Select the **Scene** tab and, under **Manager Setup**, select **Add Managers**.
3. Select the scene's **Game** GameObject and confirm it has **Spawn Point Manager**. Leave **First Spawn Preferred** disabled for random selection among eligible points. The runtime can create a fallback manager, but an explicit scene manager is easier to inspect and test.
4. Create an empty GameObject at each allowed return location and add the **Spawn Point** component.
5. Set **Grouping** to the pool that should use the point. Use one agreed index per team or checkpoint. Keep both the Respawner and its ungrouped Spawn Points at the default `-1` when no separation is needed.
6. Choose **Shape**:
- **Point** uses the GameObject's transform.
- **Sphere** or **Box** defines an area with **Size**. The first candidate is the point's center; when **Check For Obstruction** and **Random Shape Spawn** are enabled, later **Placement Attempts** sample other positions in the area.
7. Set the GameObject's rotation to the required facing direction, or enable **Random Direction**. Use **Ground Snap Height** when placements within an area must be projected onto the ground.
8. For a busy location, enable **Check For Obstruction**, choose **Obstruction Layers**, and leave enough **Placement Attempts** to find a clear candidate. The Version 3 defaults are 20 for **Max Collision Count** and 10 for **Placement Attempts**.
Each enabled Spawn Point registers itself with Spawn Point Manager. Disabled points are removed from selection, so a scene can enable or disable a checkpoint group as the game progresses.
## Configure the respawning object
1. For a UCC character, open **Tools > Opsive > Ultimate Character Controller > Character Manager**, select the character, enable **Health**, and select **Update Character**. This adds **Character Attribute Manager**, **Character Health**, and **Character Respawner**. For an ordinary world object, add **Respawner** to the same GameObject that sends the standard death event or will be disabled and returned.
2. In **Respawner** or **Character Respawner**, choose **Positioning Mode**:
- **None** keeps the current transform. Use this for an in-place revive or a custom system that has already moved the object.
- **Start Location** returns to the position and rotation recorded when the Respawner awakens.
- **Spawn Point** asks Spawn Point Manager for a valid placement.
3. For **Spawn Point**, set **Grouping** to exactly the same value as the eligible points.
4. Set **Min Respawn Time** and **Max Respawn Time**. Version 3 defaults to a random delay from `2` to `3` seconds; use the same value in both fields for a fixed delay.
5. Enable **Schedule Respawn On Death** for the standard UCC death flow. Enable **Schedule Respawn On Disable** for an ordinary object that should return after it is disabled. A Character Respawner cannot restore a character whose root GameObject is inactive, so keep a death-respawn character active and let its health, abilities, and states represent death.
6. On **Character Respawner**, enable **Check For Obstruction** when the complete character collider shape must fit at the selected destination. If blocked, the character waits for another respawn interval and tries again.
7. Optionally configure **Respawn Audio** and **Events > On Respawn Event** for feedback or scene-specific responses.
## Key choices by scenario
| Scenario | Recommended configuration |
| --- | --- |
| Return to the scene start | Use **Start Location**. No Spawn Point is required. |
| Revive where the character fell | Use **None**, disable competing automatic schedules, and let the revive workflow call Respawner when its animation completes. |
| Random arena placement | Give several enabled Spawn Points the same **Grouping**, leave **First Spawn Preferred** disabled, and use obstruction checks for occupied areas. |
| Two teams | Use a separate **Grouping** index for each team's Respawner and Spawn Points, such as `0` and `1`. |
| Checkpoint progression | Give each checkpoint its own group and update the Respawner's **Grouping** when the checkpoint is earned. A group with one enabled point gives a deterministic destination. |
| Preferred fallback location | Enable **First Spawn Preferred** on Spawn Point Manager. It tries the first enabled point registered for that group before shuffling the group; if that point is invalid, other points are still attempted. |
| Respawning pickup or target | Use the ordinary **Respawner** with **Schedule Respawn On Disable** when disabling the object is the intended return trigger. Do not use this pattern for an inactive UCC character root. |
For **Sphere** and **Box**, Spawn Point **Check For Obstruction** evaluates the candidate area and can try another location within the point or another point in the group. A **Point** always supplies its transform, so use Character Respawner **Check For Obstruction** when a character must not return to an occupied point. That character-level check tests whether the character's supported solid colliders fit at the final placement. Use both layers for crowded area-based locations; use only the layer that answers the actual risk in a simpler scene.
## Verify in Play Mode
1. Keep **Spawn Point Manager**, the eligible Spawn Points, and the object's Respawner visible in the Inspector.
2. Trigger the intended death or disable and time the scheduled return. It should occur between **Min Respawn Time** and **Max Respawn Time**. A direct call to `Respawn()` runs immediately unless placement is blocked.
3. Confirm the object returns using the selected **Positioning Mode**. For **Spawn Point**, verify its position belongs to the matching **Grouping** and its rotation follows the point or **Random Direction** setting.
4. With the relevant Spawn Point or Character Respawner obstruction check enabled, occupy one candidate with an object on **Obstruction Layers**. The system should use another valid candidate or wait and retry; it should not place the object in the obstruction.
5. Repeat the cycle several times. Random groups should use more than one valid point, while a single-point checkpoint should remain deterministic.
6. For a character, confirm Health, locomotion, abilities, camera state, and colliders recover after respawn. Check the Console for a missing-group error or repeated placement failure.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| The Console reports that no Spawn Point exists for a grouping index. | The Respawner's **Grouping** does not have an enabled Spawn Point with the same value. | Match the values exactly and enable at least one point in that group. Keep both sides at `-1` for the default ungrouped pool. |
| The character never returns after death. | **Schedule Respawn On Death** is disabled, the character root was deactivated, or every placement is blocked. | Enable death scheduling, keep the UCC character root active, and provide a clear eligible placement. |
| An ordinary object never returns after being disabled. | **Schedule Respawn On Disable** is disabled, or another script destroys the object instead of disabling it. | Enable disable scheduling and use a lifecycle that leaves the Respawner available to the Scheduler. |
| The object returns to the wrong place. | **Positioning Mode**, **Grouping**, or **First Spawn Preferred** does not match the intended scenario. | Select the correct mode, match the group, and disable first-point preference unless that registration-order preference is deliberate. |
| A spawn appears inside geometry. | **Check For Obstruction** is disabled, **Obstruction Layers** omits the blocker, or the point's shape and size do not represent the available space. | Enable the appropriate point or character obstruction check, include the blocking layer, and resize or move the Spawn Point. |
| A Spawn Point area places the object in the air. | **Ground Snap Height** is zero or shorter than the distance to the ground, or the ground layer is excluded. | Increase **Ground Snap Height** and include the ground in **Obstruction Layers**. |
| Respawn happens twice. | More than one system schedules the return, such as death scheduling, disable scheduling, Revive, or custom code. | Choose one owner for the respawn and disable or cancel the competing schedules. |
| A changed Spawn Point is not selected. | The point is disabled, assigned to another group, or a preferred first point always succeeds. | Enable the point, correct **Grouping**, and disable **First Spawn Preferred** when all points should participate randomly. |
## Related tasks
- [Spawn Points](https://opsive.com/support/documentation/ultimate-character-controller/spawn-system/spawn-points/)
- [Respawner](https://opsive.com/support/documentation/ultimate-character-controller/spawn-system/respawner/)
- [Health](https://opsive.com/support/documentation/ultimate-character-controller/attributes/health/)
- [Die](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/die/)
- [Revive](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/revive/)
- [Events](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/)
- [Quick Setup](https://opsive.com/support/documentation/ultimate-character-controller/getting-started/quick-setup/)
## Developer reference
`Opsive.UltimateCharacterController.Game.SpawnPoint` registers with `SpawnPointManager` in `OnEnable` and unregisters in `OnDisable`. Its virtual `GetPlacement(GameObject, ref Vector3, ref Quaternion)` method returns `false` when it cannot find a valid placement. `SpawnPointManager.GetPlacement` selects within the requested group, tries **First Spawn Preferred** when enabled, and otherwise shuffles and tests the available points. The manager also exposes `GetSpawnPoints`, `AddSpawnPoint`, `RemoveSpawnPoint`, and `UpdateSpawnPointGrouping`.
`Opsive.UltimateCharacterController.Traits.Respawner` listens for the object-scoped `OnDeath` event and exposes `Respawn()`, `Respawn(Vector3, Quaternion, bool)`, and `CancelRespawn()`. If a Spawn Point or Character Respawner obstruction check fails, Respawner schedules another attempt using the configured time range.
Immediately before a successful return, Respawner sends the object-scoped `OnWillRespawn` event. It then applies the placement when required, activates the object, plays the configured audio, sends `OnRespawn`, and invokes **On Respawn Event** when the object is active in the hierarchy. `CharacterRespawner` sends `OnCharacterImmediateTransformChange` after `OnRespawn` when it moved the character. Subscribe and unsubscribe through the [UCC event system](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/) using the same target, name, parameter types, and delegate.
---
# Respawner
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/spawn-system/respawner/)
Respawner returns a character or scene object after the standard UCC death event, after disablement, or from a direct call. Use it when the same object should become active again at its current transform, its original transform, or a valid scene Spawn Point.
## Before you begin
- For a UCC character, use **Character Respawner**. Character Manager adds it with Character Health and Character Attribute Manager when **Health** is enabled.
- For an ordinary object, add **Respawner** to the same GameObject that sends `OnDeath` or will be disabled and returned.
- Decide whether Respawner, [Revive](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/revive/), a checkpoint system, an object pool, or multiplayer authority owns the return. Configure one owner for each lifecycle.
- Add [Spawn Points](https://opsive.com/support/documentation/ultimate-character-controller/spawn-system/spawn-points/) only when the destination should come from a scene group. **Start Location** and **None** do not need them.
Respawner reactivates the same GameObject. It does not instantiate a replacement, restore a destroyed object, or remove an object from an Opsive pool before activation.
## Add Respawner to a character or object
### Character death and respawn
1. Open **Tools > Opsive > Ultimate Character Controller > Character Manager**.
2. Select the character, enable **Health**, and select **Update Character**. Confirm the character root has **Character Attribute Manager**, **Character Health**, and **Character Respawner**.
3. Keep the character root active when it dies. Character Respawner does not reactivate an inactive character root; the Die ability, Health, collision layers, renderers, and states represent the dead state while the GameObject remains active.
4. On Character Respawner, leave **Schedule Respawn On Death** enabled and disable any competing automatic Revive or custom return.
5. Choose a **Positioning Mode**, set the respawn delay, then configure optional **Respawn Audio** and **Events > On Respawn Event**.
6. Enable **Check For Obstruction** when the character's supported solid Colliders must fit at the chosen destination. A blocked character waits for another configured respawn interval and tries placement again.
Character Health resets Health and Shield when it receives `OnRespawn`. Ultimate Character Locomotion becomes alive again, the Die ability stops, collision state is restored, and other character systems listening to the same event reset themselves.
### Ordinary world object
1. Add **Respawner** to the same root as the object's Health component or other standard `OnDeath` sender.
2. Enable **Schedule Respawn On Death** when the object sends the UCC death event. Enable **Schedule Respawn On Disable** when `SetActive(false)` or disabling Respawner should start the timer.
3. Keep the object in the scene and disable it for the return interval. Do not destroy it; a destroyed Respawner cancels its scheduled event in `OnDestroy`.
4. If the object was instantiated through `ObjectPoolBase`, let the pool owner respawn it instead of allowing Respawner to activate an object that is still registered as available in the pool.
5. Choose the destination and verify that the object's Health, Collider, renderer, state, and other listeners reset on `OnRespawn`.
## Configure the destination and timing
| Field | Version 3.2.0 default | What it controls |
| --- | --- | --- |
| **Positioning Mode** | **Start Location** | **None** keeps the current transform. **Start Location** uses the position and rotation recorded once during `Awake`. **Spawn Point** asks Spawn Point Manager for a placement. |
| **Grouping** | `-1` | Visible in Spawn Point mode. It selects Spawn Points with exactly the same group value. In released Version 3, `-1` is the default group; it does not mean every group. |
| **Min Respawn Time** | `2` seconds | Lower end of the random automatic delay. |
| **Max Respawn Time** | `3` seconds | Upper end of the random automatic delay. Use the same nonnegative value for Min and Max when the delay should be fixed. |
| **Schedule Respawn On Death** | Enabled | Listens for the object-scoped `OnDeath(Vector3, Vector3, GameObject)` event and schedules one return. |
| **Schedule Respawn On Disable** | Enabled | Schedules a return when Respawner is disabled, unless a return is already pending. Re-enabling while this option is enabled cancels the pending return. |
| **Check For Obstruction** | Disabled | Character Respawner only. Tests the character's enabled, non-trigger Sphere, Capsule, and Box Colliders on solid-object layers at the final placement. |
| **Respawn Audio** | Empty | Plays on the returned GameObject after activation when it is active in the hierarchy. |
| **Events > On Respawn Event** | No listeners | Invokes after activation, alongside the object-scoped `OnRespawn` event, when the object is active in the hierarchy. |
Use **None** for an in-place revive or when another system has already moved the object. Use **Start Location** for a fixed scene prop or character that always returns to its initial transform. Use **Spawn Point** for teams, checkpoints, or random arena locations.
**Start Location** is not updated after a checkpoint move or a pooled reuse. If the destination can change, use a Spawn Point group, call `Respawn(position, rotation, true)`, or maintain a project-specific checkpoint value.
## Set up Spawn Point placement
1. Open **Tools > Opsive > Ultimate Character Controller > Setup Manager**.
2. Select the **Scene** tab and, under **Manager Setup**, select **Add Managers**.
3. Select the scene's **Game** GameObject and confirm it has **Spawn Point Manager**. **First Spawn Preferred** starts disabled, so valid points in the selected group are shuffled.
4. Create an empty GameObject at each allowed destination and add **Spawn Point**.
5. Give every eligible point the exact **Grouping** used by Respawner. Keep both the Respawner and its default points at `-1` for one ungrouped pool, or use deliberate indices such as `0` and `1` for two teams.
6. Configure the point's shape, size, ground snapping, facing, obstruction layers, and placement attempts as described on [Spawn Points](https://opsive.com/support/documentation/ultimate-character-controller/spawn-system/spawn-points/).
7. Keep each point enabled when it should be eligible. Enabled points register with Spawn Point Manager; disabled points are removed.
If no explicit Spawn Point Manager exists, Version 3 creates one at runtime when a Spawn Point first registers or a placement is requested. Add it to the scene deliberately when **First Spawn Preferred** or an inspectable manager is required.
When a group has no valid placement, Respawner does not fall back to its current or start location. It schedules another attempt using the same Min/Max time range.
## Choose the scheduling owner
| Scenario | Recommended configuration |
| --- | --- |
| Standard character deathmatch | Character Respawner, **Schedule Respawn On Death** enabled, active character root, Spawn Point mode, and one exact team group. |
| Fixed-delay test | Set Min and Max to the same value, such as `2`. |
| Scene pickup or destructible target | Ordinary Respawner with death or disable scheduling and a non-pooled scene-object lifecycle. |
| Manual checkpoint return | Disable both automatic triggers, move or choose the destination in project code, then call `Respawn()` or `Respawn(position, rotation, true)`. |
| Animated revive at the death position | Use **None**, disable the automatic Respawner schedule, and let Revive call the return at the intended animation point. |
| Pooled object | Disable Respawner's automatic scheduling and let the pool's spawn owner obtain and initialize the object. |
| Cancel a pending return | Call `CancelRespawn()` before an alternate revive, scene transition, permanent removal, or early manual activation. |
Automatic death and disable triggers do not normally create two Respawner timers: `OnDeath` schedules first, and `OnDisable` schedules only when no event is pending. A Revive ability, custom Scheduler event, save restore, or network callback can still compete, so keep one deliberate owner.
## How it runs
1. During `Awake`, Respawner records the starting position and rotation, detects Ultimate Character Locomotion, and registers for the object-scoped `OnDeath` event.
2. An allowed death cancels an older Respawner event and schedules `Respawn()` at a random time from Min to Max. An allowed disable schedules only when no Respawner event is pending. In a network build, only the authoritative instance schedules.
3. When the timer expires, **None** keeps the current transform, **Start Location** uses the `Awake` snapshot, and **Spawn Point** asks for a valid placement in the exact group.
4. A missing, blocked, or otherwise invalid Spawn Point placement schedules another attempt. Character Respawner performs its own full-character obstruction test after a point is chosen and also retries when blocked.
5. A successful return sends `OnWillRespawn`, changes position and rotation when required, and activates the GameObject. Characters use Ultimate Character Locomotion's position-and-rotation setter.
6. When the object is active in the hierarchy, Respawner plays its audio, sends `OnRespawn`, and invokes **On Respawn Event**. Character Respawner then sends `OnCharacterImmediateTransformChange(true)` when it moved the character.
7. Health, locomotion, Die, Colliders, camera, items, states, and project listeners respond to those events. Multiplayer authority tells the required Network Respawner Monitor to apply the same return remotely.
## Editor checkpoint
Before Play Mode, confirm that:
- the character uses Character Respawner and remains active through death, or the ordinary object uses Respawner and is disabled rather than destroyed;
- exactly one automatic or manual system owns the return;
- **Positioning Mode**, the `Awake` start transform, and any custom checkpoint behavior agree;
- Min and Max are nonnegative, Min is not greater than Max, and the intended fixed or random delay is clear;
- Spawn Point mode has at least one enabled point with an exactly matching **Grouping**, including matching `-1` values for the default group;
- Spawn Point and Character Respawner obstruction checks use the intended shapes and layers;
- audio and event listeners are on the same object and its parent hierarchy will be active at return time;
- a pooled object does not also have automatic Respawner reactivation; and
- a networked object has the installed integration's Network Info and required Network Respawner Monitor.
## Verify a character death and respawn
1. For a repeatable test, set **Min Respawn Time** and **Max Respawn Time** to `2`, choose **Start Location**, and note the character's initial position and rotation.
2. Apply lethal damage. Confirm the Die ability starts, the root remains active, and the character returns after about two seconds at the recorded transform.
3. Confirm Health and Shield reset, the alive collision layer and Colliders return, Die stops, locomotion and camera recover, respawn audio plays, and the Unity event runs once.
4. Change to **None**, move the character before killing it, and confirm the return keeps the death-location transform.
5. Change to **Spawn Point**, create two enabled points in the same group, and repeat several deaths. Confirm every return uses that group and the point's rotation or random direction.
6. Enable Character Respawner **Check For Obstruction** and block one destination with a solid object. Confirm the character uses another valid placement or waits one more interval instead of overlapping the blocker.
7. Disable an ordinary non-pooled test object with **Schedule Respawn On Disable** enabled. Confirm the same instance activates after the delay and restores its configured transform and listener state.
8. Call `CancelRespawn()` during a pending test and confirm no later return occurs.
9. In multiplayer, repeat on the authority and an observer. Confirm the authority schedules one return, the monitor applies one remote transform and activation, and Health/death state agrees on every role.
## Troubleshooting and released-Version-3 limitations
| Symptom | Check | Fix |
| --- | --- | --- |
| The character never returns after death | **Schedule Respawn On Death** is disabled, no standard `OnDeath` event was sent, the character root is inactive, or every placement is blocked. | Enable the standard death path, keep the character root active, and provide a clear destination. |
| An inactive character root stays inactive | Character Respawner returns immediately when `gameObject.activeSelf` is false and does not schedule another attempt. | Represent death with Health, Die, layers, renderers, and states while keeping the root active. Use a project or network spawner when the root must be inactive. |
| An ordinary object never returns | It was destroyed, **Schedule Respawn On Disable** is disabled, or its Respawner was destroyed before the Scheduler callback. | Disable a persistent scene object instead of destroying it, or let a spawner or pool create the replacement. |
| A pooled object reappears without being requested | **Schedule Respawn On Disable** remained enabled when the object was returned to `ObjectPoolBase`. Respawner activates the same GameObject directly and does not remove it from the pool's available set. | Disable automatic Respawner scheduling on pooled prefabs and let the pool owner spawn and initialize them. |
| `-1` selects no points or the Console reports a missing group | The legacy tooltip was read as “ignore grouping.” Released Version 3 performs an exact dictionary lookup, so `-1` selects only points whose Grouping is `-1`. | Match Respawner and Spawn Point group values exactly, or maintain the intended cross-group choice in project code. |
| A missing-group error repeats | Spawn Point placement failure schedules another full Respawner attempt, which logs the same missing grouping again. | Enable at least one point in that exact group or change Positioning Mode before the next attempt. |
| Start Location returns to an old checkpoint | The value was captured once during `Awake`; moving or reusing the object does not update it. | Use a Spawn Point group, call the positioned overload, or store and apply the current checkpoint in project code. |
| A Point Spawn Point ignores its own obstruction setting | Spawn Point's Point shape always accepts its transform in released Version 3. | Enable **Check For Obstruction** on Character Respawner for a character, or use a Sphere/Box point with configured obstruction layers for a general object. |
| The character retries forever in an apparently clear place | Character Respawner cached supported active solid Colliders and its solid-object layers at initialization, or Spawn Point obstruction layers include an unexpected object. | Inspect the character Colliders, Character Layer Manager, point layers, and final placement. Test with one clear Point and add obstruction rules back deliberately. |
| Respawn audio or events do not run | A parent is inactive, so the returned object is not active in the hierarchy, or the listener is registered on another GameObject. | Activate the required parent hierarchy and register against the Respawner's GameObject. Respawner does not retry solely because the parent is inactive. |
| A manually re-enabled object later teleports or resets again | A pending death schedule remained active. `OnEnable` automatically cancels only while **Schedule Respawn On Disable** is enabled. | Call `CancelRespawn()` before an early manual activation or alternate revive. |
| Respawn occurs twice | Revive, custom scheduling, save restore, or network code also returns the object. | Choose one owner and cancel the pending Respawner event before the alternate path. |
| A networked object logs a monitor error or fails during return | Network Info exists without the required Network Respawner Monitor. | Add and configure the integration's monitor on the same object, then test authority and observer roles. |
## Saving, pooling, and multiplayer
Respawner serializes its mode, group, timing, trigger flags, audio, Unity event, and States. The start transform is captured at runtime, while a pending Scheduler event, its remaining delay, chosen placement, obstruction retry, and death/active state are not durable Respawner data. A save system should store the authoritative alive/dead state and intended destination, cancel stale timers, then deliberately call or reschedule the return after loading.
Respawner does not call `ObjectPoolBase.Instantiate` or remove an object from a pool. It calls `SetActive(true)` on the same GameObject. Use Respawner for a scene instance or another lifecycle that owns that instance; use the [Object Pool](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/object-pool/) owner for pooled spawn and return.
With the multiplayer define enabled, an object with Network Info must also provide `INetworkRespawnerMonitor`. Non-authoritative instances do not schedule on death or disable. The authoritative instance performs the local return, then calls the monitor with position, rotation, and whether the transform changed. Prefab registration, ownership transfer, save-state reconciliation, and custom respawn rules remain integration or project responsibilities.
## Related tasks
- [Spawn System](https://opsive.com/support/documentation/ultimate-character-controller/spawn-system/) gives the short route through timing and placement.
- [Spawn Points](https://opsive.com/support/documentation/ultimate-character-controller/spawn-system/spawn-points/) configures groups, shapes, ground snapping, facing, and obstruction checks.
- [Health](https://opsive.com/support/documentation/ultimate-character-controller/attributes/health/) configures death, attribute reset, deactivation, and feedback.
- [Die](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/die/) configures the character's dead-state ability.
- [Revive](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/revive/) configures an animated or manually timed return.
- [Events](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/) explains object-scoped event registration and cleanup.
- [Object Pool](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/object-pool/) explains reusable object ownership.
## Developer reference
`Opsive.UltimateCharacterController.Traits.Respawner` exposes `PositioningMode`, `Grouping`, `MinRespawnTime`, `MaxRespawnTime`, `ScheduleRespawnOnDeath`, `ScheduleRespawnOnDisable`, `RespawnAudioClipSet`, `OnRespawnEvent`, `Respawn()`, `Respawn(Vector3, Quaternion, bool)`, and `CancelRespawn()`. It has no public “schedule after this delay” method; automatic scheduling comes from `OnDeath` or `OnDisable`, while a custom delay belongs to project Scheduler code.
The event order for a successful active-hierarchy return is `OnWillRespawn`, optional transform change, activation, audio, object-scoped `OnRespawn`, and **On Respawn Event**. Character Respawner follows with `OnCharacterImmediateTransformChange(true)` when `transformChange` is true.
Subscribe to the parameterless `OnRespawn` event and unregister with the same object and delegate:
```csharp
using UnityEngine;
using Opsive.Shared.Events;
public class MyObject : MonoBehaviour
{
private void Awake()
{
EventHandler.RegisterEvent(gameObject, "OnRespawn", OnRespawn);
}
private void OnRespawn()
{
Debug.Log(name + " Respawned.");
}
private void OnDestroy()
{
EventHandler.UnregisterEvent(gameObject, "OnRespawn", OnRespawn);
}
}
```
---
# Spawn Points
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/spawn-system/spawn-points/)
Spawn Points give a Respawner one or more scene locations to try. Use them for team starts, checkpoints, arena returns, and other cases where the destination should come from the scene instead of the object's current or original transform.
## Before you begin
- A Spawn Point chooses a position and rotation. It does not create an object, schedule a return, reset Health, or synchronize a player.
- Add a [Respawner](https://opsive.com/support/documentation/ultimate-character-controller/spawn-system/respawner/) to the character or object that should return, then select **Spawn Point** as its **Positioning Mode**.
- Decide which points belong to each team, checkpoint, or other pool. Respawner and Spawn Point must use exactly the same **Grouping** value.
- Use one active **Spawn Point Manager** in the scene. The runtime can create a fallback manager, but an explicit manager exposes the selection setting and gives the scene a clear owner.
## Add the manager and scene points
1. Open **Tools > Opsive > Ultimate Character Controller > Setup Manager**.
2. Select the **Scene** tab and, under **Manager Setup**, select **Add Managers**.
3. Select the scene's **Game** GameObject and confirm it has **Spawn Point Manager**. **First Spawn Preferred** starts disabled.
4. Create an empty GameObject at an allowed destination and add **Spawn Point**.
5. Place the GameObject at the center of the location. Its rotation supplies the normal spawn facing direction. Keep its Transform scale at `(1, 1, 1)` and use **Size** to change the area.
6. Set **Grouping** to the exact pool that should use this point. Keep the default `-1` on both the point and Respawner for one ungrouped pool, or use deliberate values such as `0` and `1` for two teams.
7. Duplicate and place as many points as the group needs. Enabled points register with Spawn Point Manager; disabling a point removes it from selection until it is enabled again.
## Configure the placement area
| Field | Version 3.2.0 default | What it controls |
| --- | --- | --- |
| **Grouping** | `-1` | Selects one exact manager group. In released Version 3, `-1` is a real group value; it does not mean every group. |
| **Shape** | **Point** | **Point** uses the GameObject's position. **Sphere** and **Box** can define a horizontal area for retry candidates. |
| **Size** | `0` | For **Sphere**, this is the maximum horizontal sample radius and the gizmo radius. For **Box**, it is the full local X/Z width and depth; samples range from `-Size / 2` to `Size / 2`. |
| **Random Shape Spawn** | Enabled | Allows later obstruction retries to sample another position. The first candidate is still the center, and this setting has no effect unless the center fails an obstruction test. |
| **Ground Snap Height** | `0` | When positive, casts downward from above the accepted candidate and moves it to a hit on **Obstruction Layers**. No hit leaves the candidate unchanged. For **Box**, this value is also the obstruction volume's height. |
| **Random Direction** | Disabled | Disabled uses the Spawn Point Transform rotation. Enabled gives an upright point a random yaw. |
| **Check For Obstruction** | Disabled | Tests the candidate with the point's configured volume before accepting it. **Point** bypasses this test and succeeds when at least one placement attempt is allowed. |
| **Max Collision Count** | `20` | Sets the fixed Collider result-buffer capacity used by the Spawn Point obstruction query. |
| **Obstruction Layers** | Most project layers | Supplies both the obstruction query and ground-snap ray. The default excludes Default, Ignore Raycast, Transparent FX, Water, UI, SubCharacter, Overlay, and Visual Effect. Review the mask for the scene. |
| **Placement Attempts** | `10` | Sets the maximum candidates tested within this point. Keep it at least `1`; the center is the first attempt. |
| **Gizmo Color** | Red at 30% opacity | Controls the Scene view area visualization only. |
The Spawn Point obstruction volume is not derived from the spawning object's Colliders. A Sphere point checks a sphere of `Size / 2` around the candidate; a Box point checks `Size / 2` in local X/Z and `Ground Snap Height / 2` vertically. For a UCC character, enable **Check For Obstruction** on Character Respawner as well when the complete character collider shape must fit at the final position.
Ground snapping happens after the Spawn Point obstruction test. Place the Spawn Point near the intended surface, give **Ground Snap Height** enough reach, and include the ground layer in **Obstruction Layers**. A failed ray does not make the placement fail.
## Choose grouping and selection behavior
| Goal | Configuration |
| --- | --- |
| One shared pool | Leave Respawner and all eligible points at **Grouping** `-1`. This is an exact default group, not a wildcard. |
| Team starts | Give each team a distinct value, such as `0` and `1`, and apply the matching group to its Respawner. |
| Fixed checkpoint | Keep one enabled point in the current checkpoint group, or change the Respawner group when the next checkpoint is earned. |
| Several eligible locations | Keep **First Spawn Preferred** disabled. Spawn Point Manager shuffles the group's registered list, then uses the first point that returns a valid placement. |
| Preferred location with fallbacks | Enable **First Spawn Preferred**. The first registered point in the group is tried before the group is shuffled; if it fails, it may be tried again as part of the shuffled fallback list. |
| Sequential or round-robin locations | Version 3 has no sequential selection mode. Enable one checkpoint point at a time or implement a project-owned selection policy. |
“First” means the first point currently registered for that group, not the first alphabetically named point. Disabling that point promotes the first remaining list entry; re-enabling it appends it again. When preference order matters, establish the registration order deliberately and verify it in Play Mode.
The released-Version-3 shuffle is not a statistically uniform picker. With two always-valid points, its in-place shuffle swaps their order on every request, so the selected location alternates. Use the built-in behavior for variety, not for weighted probability or a guaranteed random distribution.
## Connect a character or object
1. On **Respawner** or **Character Respawner**, set **Positioning Mode** to **Spawn Point**.
2. Set **Grouping** to the exact value used by the eligible points.
3. Configure **Min Respawn Time**, **Max Respawn Time**, and the intended death, disable, or manual scheduling owner on [Respawner](https://opsive.com/support/documentation/ultimate-character-controller/spawn-system/respawner/).
4. For a character, keep the character root active through death and enable Character Respawner **Check For Obstruction** when the final character shape must fit.
5. For an ordinary object, decide whether the Spawn Point's Size-based test is enough. Supply a project-specific final-volume test when the object shape is materially different.
6. Keep scene points enabled only while they should participate. Enabling or disabling a checkpoint point updates the manager automatically.
## How placement runs
1. Each enabled Spawn Point registers itself in the manager dictionary under its exact **Grouping** value.
2. A Respawner requests a placement for its group. A missing group logs an error and fails the request.
3. With **First Spawn Preferred** enabled, the group's first registered point is tried first. The manager then shuffles the group and tries points until one succeeds.
4. A Spawn Point starts at its Transform center. With obstruction checking enabled, **Point** accepts that center; **Sphere** and **Box** test their configured volume.
5. After a blocked Sphere or Box candidate, **Random Shape Spawn** can choose another horizontal position. The point repeats until it succeeds or reaches **Placement Attempts**.
6. A positive **Ground Snap Height** then tries to move the accepted candidate onto a surface, and **Random Direction** or the Transform supplies its rotation.
7. If every point fails, Spawn Point Manager returns `false`. Respawner waits for another configured respawn interval and requests placement again.
8. On success, Respawner moves and activates the object and sends its normal respawn events. Character Respawner can perform its separate full-character obstruction check before completing the return.
## Editor checkpoint
Before Play Mode, confirm that:
- the scene has one active Spawn Point Manager and **First Spawn Preferred** matches the intended policy;
- every Respawner group has at least one enabled point with the exact same value, including matching `-1` values for the default pool;
- each point's center, Transform rotation, unit scale, **Shape**, and **Size** represent the visible safe area;
- **Placement Attempts** is at least `1` and **Max Collision Count** can hold the expected nearby results;
- **Obstruction Layers** includes blockers and, when used, the ground surface;
- **Ground Snap Height** reaches from the candidate to the intended surface;
- Point locations that must fit a character also use Character Respawner **Check For Obstruction**; and
- the project has one clear owner for respawn scheduling, checkpoint state, pooling, and network authority.
## Verify several points in Play Mode
1. Create three visibly separated Point Spawn Points with distinct rotations and set all three to **Grouping** `7`.
2. Configure a test character's Character Respawner for **Spawn Point**, group `7`, and a fixed two-second delay.
3. Leave **First Spawn Preferred** disabled. Trigger several deaths and confirm every successful return uses a point in group `7`, applies that point's rotation, and eventually uses more than one eligible point.
4. Disable one point and repeat. Confirm it is no longer selected; re-enable it and confirm it becomes eligible again.
5. Add one point in group `8` and confirm the group-`7` character never uses it. Change the Respawner to group `8` and confirm only that point is used.
6. Change one group-`7` point to **Box**, set a visible **Size**, enable **Check For Obstruction** and **Random Shape Spawn**, then block its center with an object on **Obstruction Layers**. Confirm a clear retry position is used or the manager moves to another point.
7. Give the Box a positive **Ground Snap Height** and verify the accepted candidate reaches the intended ground. Remove the ground layer from **Obstruction Layers** and confirm the missing ray leaves the candidate unsnapped.
8. Block every eligible area and enable Character Respawner **Check For Obstruction**. Confirm the character waits and retries instead of overlapping a blocker.
9. Enable **First Spawn Preferred** and establish a known registration-first point. Confirm it wins while valid and a fallback is used when it cannot place the character.
## Troubleshooting and released-Version-3 limitations
| Symptom | Check | Fix |
| --- | --- | --- |
| The Console reports no Spawn Point for the group | Respawner and enabled points do not share an exact group key. `-1` was treated as a wildcard. | Match the values exactly. Keep both sides at `-1` for the default pool. |
| Respawner waits and retries without a missing-group error | The group was registered previously but now contains no enabled points, or every point returns `false`. | Enable a valid point in the group and clear its placement area. |
| Sphere or Box always returns the center | The center is clear, **Check For Obstruction** is disabled, or **Random Shape Spawn** is disabled. Version 3 randomizes only retries after the center fails. | Use several Point locations for ordinary variety, or implement a custom Spawn Point when every request must sample the full area. |
| A Point accepts an occupied location | Point shape bypasses the Spawn Point obstruction query in released Version 3. | Enable Character Respawner **Check For Obstruction** for a character, use an area shape, or add a project-specific final-volume test. |
| The object appears in the air | **Ground Snap Height** is zero or too short, the ground is absent from **Obstruction Layers**, or the ray misses. A miss still returns success. | Increase the height, include the ground layer, and place the point close enough to the surface. |
| The final snapped object overlaps geometry | Spawn Point obstruction runs before ground snapping and uses the point volume rather than the object's Collider shape. | Use Character Respawner's final character check or validate the final object volume in project code. |
| A scaled area does not match its obstruction test | The Transform has non-unit scale. Sampling and gizmo transforms use it, while the overlap extents use unscaled field values. | Keep Spawn Point scale at `(1, 1, 1)` and adjust **Size** and **Ground Snap Height**. |
| A point always fails when obstruction checking is enabled | **Placement Attempts** is `0`, every candidate is blocked, or the layer mask includes an unintended Collider. | Set attempts to at least `1`, inspect the mask, and test from a clear center. |
| Preferred-first chooses an unexpected point | Registration order changed after a point was disabled, re-enabled, or moved between groups. | Establish enable order deliberately or use one enabled point when the destination must be deterministic. |
| Two points alternate instead of looking random | The Version 3 shuffle swaps a two-entry list on every request. | Treat this as built-in variety or implement the required random, weighted, or sequential policy. |
| A Grouping edit during Play Mode is ignored | Directly editing the serialized Inspector field does not call the runtime `Grouping` property that updates the manager map. | Change `SpawnPoint.Grouping` through project code, or disable and re-enable the point after an Inspector-only test change. |
| There are inconsistent results with multiple managers | More than one Spawn Point Manager exists and only the initialized singleton owns registration and selection. | Keep one active manager in the scene and remove duplicates. |
## Saving, networking, and scene ownership
Spawn Point Manager and Spawn Point are scene configuration. They do not save the current checkpoint, persist which points are enabled, schedule an object, or send spawn events. A save system should store the authoritative checkpoint or group and restore the relevant Respawner value and enabled-point state after loading.
Spawn Point selection itself has no network synchronization. In the UCC multiplayer path, the authoritative Respawner chooses a placement and its required Network Respawner Monitor applies the chosen position and rotation remotely. Do not let each client choose independently. Dynamic point registration, checkpoint ownership, team assignment, late joining, and scene transitions remain integration or project responsibilities.
## Related tasks
- [Spawn System](https://opsive.com/support/documentation/ultimate-character-controller/spawn-system/) explains how placement and return timing work together.
- [Respawner](https://opsive.com/support/documentation/ultimate-character-controller/spawn-system/respawner/) configures timing, positioning mode, scheduling, audio, and return events.
- [Health](https://opsive.com/support/documentation/ultimate-character-controller/attributes/health/) configures character death and attribute reset.
- [Die](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/die/) controls the character's dead-state ability.
- [Events](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/) explains the events sent by Respawner after placement succeeds.
- [Quick Setup](https://opsive.com/support/documentation/ultimate-character-controller/getting-started/quick-setup/) creates a working character and scene foundation.
## Developer reference
`Opsive.UltimateCharacterController.Game.SpawnPoint` registers in `OnEnable` and unregisters in `OnDisable`. Its virtual `GetPlacement(GameObject, ref Vector3, ref Quaternion)` method supplies one position and rotation or returns `false`. Public properties expose `Grouping`, `Shape`, `Size`, `GroundSnapHeight`, `RandomDirection`, `CheckForObstruction`, `ObstructionLayers`, and `PlacementAttempts`. **Random Shape Spawn** and **Max Collision Count** are serialized fields without public properties in released Version 3.
Change a live point's group through its `Grouping` property so `SpawnPointManager.UpdateSpawnPointGrouping` removes it from the old list and adds it to the new one. `SpawnPointManager` also exposes static `GetPlacement`, `GetSpawnPoints`, `AddSpawnPoint`, and `RemoveSpawnPoint` methods. **First Spawn Preferred** is serialized on the manager and has no public property in this release.
Spawn Point has no gameplay event of its own. Respawner sends `OnWillRespawn`, moves and activates the object after placement succeeds, then sends `OnRespawn` and invokes its Unity event when the object is active in the hierarchy. Follow [Respawner](https://opsive.com/support/documentation/ultimate-character-controller/spawn-system/respawner/) for exact event order and cancellation behavior.
---
# Audio
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/audio/)
Use the Opsive audio system to add varied, spatial sounds to character abilities, health, items, footsteps, impacts, and other gameplay without managing a separate Audio Source for every playback.
The **Audio Manager** finds or creates an available Audio Source on the object that plays the sound. This lets multiple clips overlap when needed and gives built-in UCC features a common way to play audio.
## Add audio to a UCC feature
Most audio-enabled UCC features expose an **Audio Clip Set**. Examples include **Start** and **Stop** on an ability, **Take Damage**, **Heal**, and **Death** on the Health component, and **Audio Clip Set** on character or item effects.
1. Select the character, item, or scene object that owns the behavior.
2. In the relevant component, ability, effect, or action module, expand its audio field.
3. For a quick, local setup, leave **Audio Config** empty and add one or more clips under **Audio Clips**. Each playback chooses a clip at random.
4. Enter Play Mode and trigger the behavior. UCC plays the sound from the object associated with that behavior.
Use inline **Audio Clips** when the clips belong to one feature only. Use an Audio Config when several features should share the same clips and playback rules.
## Create a reusable Audio Config
1. In the Project window, choose **Assets > Create > Opsive > Audio > Audio Config**.
2. Add the available sounds to **Audio Clips**.
3. Set **Clip Selection** to match the intended behavior.
4. If the default source is not suitable, assign an **Audio Source Prefab** that contains a configured Unity Audio Source.
5. Set only the required values in **Audio Modifier**. Leave a value at **No Override** to inherit it from the selected Audio Source.
6. Assign the asset to **Audio Config** in the feature's Audio Clip Set. When a config is assigned, its clips replace the inline **Audio Clips** list.
You can also select AudioClip assets in the Project window and use **Assets > Create > Opsive > Audio > One Audio Config From Selected Clips**. Use **Multi Audio Configs From Clips** when each selected clip should receive its own config.
## Key choices
### Choose a clip
- **Random** chooses a random entry for each playback and is the default.
- **Sequence** advances from the first clip to the last, then repeats.
- **Index** uses `AudioClipIndex`, which starts at 0 and can be changed from code. Use it when gameplay chooses a specific variation.
An inline Audio Clip Set chooses randomly when a built-in feature plays it without an explicit index. Create an Audio Config when you need Sequence behavior or an Inspector-configured Index mode.
### Control overlap and Audio Sources
- **Share Audio Source** is enabled by default. The manager reuses any available shared source on the same GameObject and creates another when all shared sources are busy.
- **Replace Previous Audio Source** is disabled by default. Enable it when a new clip should replace an active clip instead of overlapping it.
- **Copy Existing Audio Source Properties** is enabled by default. When the manager creates another source, it copies the Unity Audio Source settings already on the originating GameObject.
- **Audio Source Prefab** provides the source settings when no suitable source exists. The prefab must contain an Audio Source component.
For a local 3D sound, play it on the character, visible item, or impact position. For non-spatial UI or narration, use a 2D Audio Source prefab or set **Spatial Blend Override** to a constant value of 0.
### Vary or override playback
The Audio Config's **Audio Modifier** can override **Output**, **Loop**, **Volume**, **Pitch**, **Stereo Pan**, **Spatial Blend**, **Reverb Zone**, and **Delay**. Float overrides can use a constant or a random range; **Loop Override** can use a constant or random Boolean. Small random pitch or volume ranges can make repeated footsteps or impacts sound less repetitive.
## Configure the scene Audio Manager
The normal UCC setup adds an **Audio Manager** to the scene's **Game** object and assigns the included 3D Audio Manager Module. If no Audio Manager exists, the runtime creates one with a 3D Audio Source, so a basic Audio Clip Set still works.
To add the normal scene managers explicitly:
1. Open **Tools > Opsive > Ultimate Character Controller > Setup Manager**.
2. In **Manager Setup**, select **Add Managers**.
3. Select the **Game** object and confirm that its **Audio Manager** component has **Audio Manager Module** assigned.
For project-wide custom defaults, create an **Audio Manager Module** from **Assets > Create > Opsive > Audio > Audio Manager Module**, assign its **Default Audio Config**, and then assign the module to the scene's **Audio Manager**. Use **Output Override** on an Audio Config when a sound needs a particular Audio Mixer Group.
## Verify in Play Mode
Trigger each configured behavior several times and confirm that:
- the sound begins at the expected ability, health, item, surface, or impact event;
- Random or Sequence selection changes clips as configured;
- simultaneous sounds overlap unless **Replace Previous Audio Source** is enabled;
- 3D sounds follow or originate from the intended object or world position; and
- volume, pitch, delay, looping, and mixer routing match the Audio Source plus any Audio Modifier overrides.
During playback, expand the source GameObject in the Hierarchy. The manager names generated children `SharedAudioSource` or `ReservedAudioSource: `, which helps confirm which source is being used.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| No sound plays | The Audio Clip Set may have neither an assigned Audio Config nor an inline clip. | Assign a config containing clips or add clips under **Audio Clips**. Also confirm that the source and mixer are not muted. |
| Inline clips never play | An **Audio Config** is assigned. | Remove the config to use the inline list, or move the intended clips into the config. |
| The same clip always plays | **Clip Selection** is set to **Index**; its runtime index starts at 0. | Use **Random** or **Sequence**, or set `AudioClipIndex` from code. |
| A new sound cuts off the previous one | **Replace Previous Audio Source** is enabled. | Disable it when the sounds should overlap. |
| A sound is unexpectedly 2D or 3D | The Audio Source prefab, an existing Audio Source, or **Spatial Blend Override** is supplying the spatial setting. | Set the intended spatial blend on the source or use an explicit constant override. |
| New sources use unexpected volume, pitch, or routing | **Copy Existing Audio Source Properties** is copying a source on the playback GameObject, or an Audio Modifier is overriding it. | Correct the existing source, disable the copy option, or reset the modifier to **No Override**. |
| A warning reports a missing default Audio Source prefab | The module's **Default Audio Config** has no **Audio Source Prefab**. | Assign the included 3D or 2D default module/config, or provide a prefab containing an Audio Source. |
## Related pages
- [Quick setup](https://opsive.com/support/documentation/ultimate-character-controller/getting-started/quick-setup/) adds the standard scene managers.
- [Health](https://opsive.com/support/documentation/ultimate-character-controller/attributes/health/) uses Audio Clip Sets for damage, healing, and death feedback.
- [Jump](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/jump/) shows ability-specific audio alongside the common ability Start and Stop sets.
- [Character Foot Effects](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/character-foot-effects/) connects footsteps to Surface Effects and Audio Config assets.
- [Item actions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/) explains the action and module system that item audio effects participate in.
- [Events](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/) explains how to react to UCC gameplay events before playing custom audio.
- [FMOD](https://opsive.com/support/documentation/ultimate-character-controller/integrations/fmod/) and [Master Audio](https://opsive.com/support/documentation/ultimate-character-controller/integrations/master-audio/) replace the default playback module while retaining the Opsive audio data workflow.
## Developer reference
The released audio types are in the `Opsive.Shared.Audio` namespace. Built-in UCC integrations call Audio Clip Sets from their own lifecycle: abilities play their Start and Stop sets, Health plays its Take Damage, Heal, and Death sets, item effects and modules play from the item or visible object, and surface or impact effects can play at a world position. These integrations do not require a separate audio-specific event subscription. For custom behavior, respond to the relevant UCC event and call the audio API from that handler.
Keep the returned `PlayResult` when you need to stop the exact source started by a call:
```csharp
using Opsive.Shared.Audio;
using UnityEngine;
public class AlertAudio : MonoBehaviour
{
[SerializeField] private AudioConfig m_AlertAudioConfig;
private PlayResult m_PlayResult;
public void PlayAlert()
{
m_PlayResult = AudioManager.Play(gameObject, m_AlertAudioConfig);
}
public void StopAlert()
{
AudioManager.Stop(gameObject, m_PlayResult);
}
public void PlayAlertAt(Vector3 position)
{
AudioManager.PlayAtPosition(m_AlertAudioConfig, position);
}
}
```
`AudioManager` also provides overloads for an AudioClip, volume, pitch, delay, looping, AudioConfig, and AudioClipInfo. `AudioClipSet` provides `PlayAudioClip`, `PlayAtPosition`, and `Stop` when a component should expose the same Inspector workflow used by UCC.
---
# Programming Concepts
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/)
Extend the Ultimate Character Controller without editing package source: start with the gameplay or Inspector result you need, then use the smallest supported extension point that owns that result.
## Start with the visible result
Describe the change in terms that can be checked in the editor or in Play Mode before choosing an API. For example, decide whether the character should gain a new action, movement input should be interpreted differently, the camera should frame the character differently, an item should gain another behavior, or an existing event should update a separate system.
Prefer configuration before code. An existing component, ability, action module, or [State System](https://opsive.com/support/documentation/ultimate-character-controller/state-system/) preset is easier to inspect and maintain than a new subclass. Create a custom type only when the existing choices cannot produce the required result.
## Choose the smallest extension point
| Goal | Recommended extension point | Editor-visible result |
| --- | --- | --- |
| Add a character action with its own start, update, and stop rules | Derive from `Ability`, or from the nearest included ability base. | The compiled type appears in the **Abilities** add menu on **Ultimate Character Locomotion**. See [New Ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/new-ability/). |
| Change how input and look direction become character movement | Derive from `MovementType`. | The compiled type appears in the **Movement Types** add menu on **Ultimate Character Locomotion**. See [Movement Types](https://opsive.com/support/documentation/ultimate-character-controller/character/movement-types/). |
| Change camera position, rotation, or perspective behavior | Derive from `ViewType`. | The compiled type appears in the **View Types** add menu on **Camera Controller**. See [View Types](https://opsive.com/support/documentation/ultimate-character-controller/camera/view-types/). |
| Add one responsibility to a usable item | Derive from the module base accepted by the relevant action-module group. | The compiled type appears in that group's **Modules** add menu. See [Action Modules and Groups](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/). |
| Add or gate a response when an item impacts something | Create an `ImpactAction` or `ImpactActionCondition` for the appropriate impact group. | The response or condition can be selected in the item's impact configuration. See [Impact Actions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/impact-actions/). |
| Change how damage data is applied to a target | Derive from `DamageProcessor` and use a project-owned processor asset. | Assign it to **Default Damage Processor** on a Damage Processor Module or to **Damage Processor** in item impact data. See [Damage Processor](https://opsive.com/support/documentation/ultimate-character-controller/objects/damage-processor/). |
| React to an existing character, item, camera, or state change | Subscribe through `EventHandler` instead of modifying the sender. | The receiving component updates when the documented event occurs. See [Events](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/). |
Keep the extension focused on one responsibility. If a feature needs several independent outcomes, combine a small ability, module, component, state, or event listener instead of creating one class that replaces multiple controller systems.
## Use the programming utilities
These are the direct programming topics in this section:
- [Events](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/) connects systems without requiring the sender to know about every receiver. Events can be scoped to an object or sent globally; use the [Event Names](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/event-names/) catalog to match an existing Version 3 event before defining another one.
- [Scheduler](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/scheduler/) runs a callback later in `Update` or `FixedUpdate` and returns a handle that can be cancelled. Use it for controller work that should follow UCC's timing rather than starting a coroutine solely for a delay.
- [Object Pool](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/object-pool/) reuses spawned Unity objects and regular C# objects. Use it for frequently created projectiles, effects, temporary data, and similar short-lived objects.
## Build an upgrade-safe extension
1. Create the script under `Assets//Scripts/Runtime`, not inside `Packages/com.opsive.*` or an imported demo folder.
2. If the project uses an Assembly Definition, add **Opsive.UltimateCharacterController** under **Assembly Definition References**. Also reference **Opsive.Shared.Runtime** when the script directly uses `Opsive.Shared` APIs such as events, scheduling, or pooling.
3. Derive from the extension point that owns the result. Start with the nearest existing base type so built-in lifecycle and validation behavior remains available.
4. Expose only the settings a designer needs to change. Give serialized fields clear names and useful tooltips.
5. Let Unity compile and clear every Console error. The Version 3 add menus only offer compatible, concrete types from successfully loaded assemblies.
6. Select the owning character, camera, item action, or processor field. Use the appropriate **Abilities**, **Movement Types**, **View Types**, or **Modules** plus menu, or assign the project-owned asset described by that feature's page.
7. Configure the new entry, save the owning scene or prefab deliberately, and record the expected Play Mode result before adding more behavior.
Keep custom runtime and editor code in separate assemblies or folders. If a custom Inspector is useful, place its code in an Editor assembly; the runtime type should not depend on UnityEditor APIs.
## Verify in Play Mode
1. Enter Play Mode with one controlled scenario that triggers the extension.
2. Confirm the expected visible result occurs once: the ability starts, movement or framing changes, the item response runs, or the listening component updates.
3. End the scenario and confirm the result stops or resets. Trigger it a second time to catch stale state or duplicate subscriptions.
4. Disable and re-enable the owning object. If the object can be pooled, respawn it through the same pool path used by the game.
5. Stop Play Mode, reopen the scene or prefab, and confirm the custom type and its configured values remain assigned.
6. Check the Console. A successful extension produces the intended result without missing-reference, serialization, duplicate-registration, or uncancelled-callback errors.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| A custom type does not appear in an add menu. | The Console has compile errors, the class is abstract or generic, it derives from the wrong base, or its Assembly Definition lacks the required reference. | Clear compile errors, use a concrete compatible subclass, and add the required UCC or Shared assembly reference. Then let Unity reload the scripts and reopen the Inspector. |
| A callback runs more than once after an object is re-enabled. | The component registers repeatedly without unregistering the same target, event name, parameter types, and delegate. | Pair registration and unregistration in matching lifecycle methods. Test two enable/disable cycles. |
| Delayed work runs after the owner is disabled, destroyed, or reused. | The returned `ScheduledEventBase` is still active. | Store the handle and call `Scheduler.Cancel` when the owner no longer needs the callback. Reset the handle before reuse. |
| A pooled object retains data from its previous use. | Initialization and cleanup do not reset every mutable value, or spawn and return use different systems. | Reinitialize the object when it is obtained and return it through the matching pool. For regular pooled classes, implement `IPoolable.Reset` when references or state must be cleared on return. |
| Inspector values disappear after a compile or reload. | A field is not serialized, or the type, namespace, assembly, or field name changed after data was saved. | Serialize designer-facing fields and plan migrations before renaming serialized types or fields. Reassign the asset only after checking the version-control diff. |
| A package update removes the customization. | The custom file was saved under an Opsive package, demo, or integration-owned folder. | Restore it from version control, move it under the project's `Assets` folder, and reconnect the project-owned type or asset. |
## Related tasks
- [Organization](https://opsive.com/support/documentation/ultimate-character-controller/organization/)
- [State System](https://opsive.com/support/documentation/ultimate-character-controller/state-system/)
- [New Ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/new-ability/)
- [Movement Types](https://opsive.com/support/documentation/ultimate-character-controller/character/movement-types/)
- [View Types](https://opsive.com/support/documentation/ultimate-character-controller/camera/view-types/)
- [Action Modules and Groups](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/)
- [Damage Processor](https://opsive.com/support/documentation/ultimate-character-controller/objects/damage-processor/)
## Developer reference
The released Version 3 runtime exposes these primary extension families:
| Responsibility | Base type and namespace |
| --- | --- |
| Character action | `Opsive.UltimateCharacterController.Character.Abilities.Ability` |
| Movement interpretation | `Opsive.UltimateCharacterController.Character.MovementTypes.MovementType` |
| Camera behavior | `Opsive.UltimateCharacterController.Camera.ViewTypes.ViewType` |
| Item action module | `Opsive.UltimateCharacterController.Items.Actions.Modules.ActionModule` and the compatible group-specific base |
| Item impact response | `Opsive.UltimateCharacterController.Items.Actions.Impact.ImpactAction` or `ImpactActionCondition` |
| Damage application | `Opsive.UltimateCharacterController.Traits.Damage.DamageProcessor` |
Abilities, Movement Types, View Types, and Action Modules are serialized objects owned by their controller or item component rather than standalone `MonoBehaviour` components. The Version 3 editor scans loaded assemblies for nonabstract assignable types when it builds their add menus. Put component references and other initialization in the lifecycle methods provided by the selected base class instead of assuming a `MonoBehaviour` lifecycle.
`EventHandler` is in `Opsive.Shared.Events`. `Scheduler`, `ScheduledEventBase`, and the Unity-object `ObjectPool` are in `Opsive.Shared.Game`; `GenericObjectPool` and `IPoolable` are in `Opsive.Shared.Utility`. Keep the handle returned by `Scheduler.Schedule` or `Scheduler.ScheduleFixed` when the operation may need to be cancelled, and pair `ObjectPool.Instantiate` with `ObjectPool.Destroy` for objects managed by that pool.
---
# Events
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/)
Use Opsive's `EventHandler` when one gameplay system must react to a UCC character, item, or object change without holding a direct reference to the component that caused it. It is best for notifications with a stable name, target, and typed parameter contract; use a normal method call when the sender already owns the receiver and needs an immediate result.
## Choose an event scope
`EventHandler` stores subscriptions in static tables and exposes static methods. You do not need to add an EventHandler component to every publisher.
| Scope | Call shape | Use it when |
| --- | --- | --- |
| Object-scoped | Pass a target object first | The event belongs to one character, item, camera, or impacted object. This is the normal UCC pattern. |
| Global | Omit the target object | Every listener should receive one project-wide signal regardless of scene object. |
For an object-scoped event, the target is the publisher's key, not necessarily the listener's GameObject. UCC commonly uses the character GameObject for ability and inventory events, the Health GameObject for death events, and the impacted GameObject for impact events. Register, execute, and unregister with the same target instance.
Global events are easier to reach but harder to own. They remain registered across scene changes until explicitly unregistered or until the event tables are reset at Play Mode subsystem registration. Prefer an object-scoped event unless the signal is genuinely global.
## Use one typed contract
The event name, target, parameter count, parameter types, and parameter order form one contract. Registration, execution, and unregistration must use that same contract.
These UCC 3.2.0 events illustrate the pattern:
| Scenario | Target | Typed signature |
| --- | --- | --- |
| A Health component dies | The Health GameObject | `OnDeath(Vector3 position, Vector3 force, GameObject attacker)` |
| A character Ability starts or stops | The character GameObject | `OnCharacterAbilityActive(Ability ability, bool active)` |
| A Character Item is equipped | The character GameObject | `OnInventoryEquipItem(CharacterItem item, int slotID)` |
| An item impact reaches an object | The impacted GameObject | `OnObjectImpact(ImpactCallbackContext context)` |
Use the [event names reference](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/event-names/) to find the target concept and expected parameters for built-in events. When an integration defines an additional event, verify its exact signature against the installed integration source.
Do not reuse one event name with unrelated signatures. Opsive Shared can optionally allow multiple signature types for some one-, two-, and three-parameter registrations, but the normal and clearer design is one name per typed contract.
## Follow the listener lifecycle
Every subscription has three parts:
1. Register when the listener becomes interested.
2. Let the publisher execute the event on the agreed target.
3. Unregister with the same target, name, generic types, and delegate before the listener stops being interested.
Use `Awake` and `OnDestroy` for a listener that should remain subscribed for its complete component lifetime. Use `OnEnable` and `OnDisable` when disabling or pooling the listener should pause the subscription. Do not combine both patterns for the same callback.
This pooled-friendly component listens for the Health event on its own GameObject:
```csharp
using UnityEngine;
using EventHandler = Opsive.Shared.Events.EventHandler;
public sealed class DeathReporter : MonoBehaviour
{
private void OnEnable()
{
EventHandler.RegisterEvent(
gameObject, "OnDeath", OnDeath);
}
private void OnDisable()
{
EventHandler.UnregisterEvent(
gameObject, "OnDeath", OnDeath);
}
private void OnDeath(
Vector3 position,
Vector3 force,
GameObject attacker)
{
Debug.Log($"{name} died at {position}.", this);
}
}
```
A listener does not need to be attached to the target. For example, a HUD can register against its assigned character GameObject and unregister from that same character before switching players.
Use a named method or cache the delegate. Creating a new lambda during unregistration does not reproduce the delegate that was registered, so the old callback remains.
## Practical UCC subscriptions
The following registrations use source-verified Version 3 signatures:
```csharp
using Opsive.UltimateCharacterController.Character.Abilities;
using Opsive.UltimateCharacterController.Items;
using Opsive.UltimateCharacterController.Items.Actions.Impact;
using EventHandler = Opsive.Shared.Events.EventHandler;
// Character lifecycle: target is the character GameObject.
EventHandler.RegisterEvent(
character, "OnCharacterAbilityActive", OnAbilityActive);
// Inventory lifecycle: target is also the character GameObject.
EventHandler.RegisterEvent(
character, "OnInventoryEquipItem", OnItemEquipped);
// Impact lifecycle: target is the GameObject that received the impact.
EventHandler.RegisterEvent(
impactTarget, "OnObjectImpact", OnObjectImpact);
```
The matching callbacks are:
```csharp
private void OnAbilityActive(Ability ability, bool active)
{
// React only to the Ability types relevant to this listener.
}
private void OnItemEquipped(CharacterItem item, int slotID)
{
// Refresh the UI or another dependent system for this slot.
}
private void OnObjectImpact(ImpactCallbackContext context)
{
// Read the source-verified impact context needed by this object.
}
```
Mirror all three calls with `UnregisterEvent` when their owner is disabled, destroyed, or assigned a different character or target.
## Runtime and ownership cautions
- **Main thread:** the Shared 2.0.0 implementation mutates ordinary static `Dictionary` and `List` instances without synchronization and invokes Unity-facing callbacks. Register, execute, and unregister on Unity's main thread.
- **Duplicate registration:** in the Editor, registering the same delegate twice logs a warning but still adds the second subscription. One unregistration removes one matching entry, so an unmatched duplicate can continue firing.
- **Pooling:** a pooled listener should normally pair `OnEnable` with `OnDisable`. A pooled publisher does not automatically remove callbacks registered against its GameObject.
- **Destroyed targets:** the table does not infer subscription ownership from Unity object destruction. Explicitly unregister listeners rather than relying on a scene unload or destroyed target.
- **Global listeners:** a global registration has no object key to constrain it. Always give it an explicit owner and matching cleanup path.
- **Play Mode/domain reload:** `EventHandler.DomainReset()` is marked for `SubsystemRegistration` and clears both object and global event tables. This also protects a new Play Mode session when domain reload is disabled, but it is not a replacement for normal scene and pooling cleanup.
- **Execution changes:** the implementation accounts for listeners being removed while an event is executing. Avoid adding broader lifecycle work inside a callback unless the order is intentional.
The internal invokable wrappers are pooled, so EventHandler avoids creating a new wrapper for every execution. Treat this as a notification mechanism, not as permission to broadcast high-frequency data when a direct update path would be simpler.
## Verify the event flow
1. Add a temporary, uniquely worded `Debug.Log` to the callback.
2. Trigger the gameplay action once, such as starting one Ability, equipping one Character Item, or applying one impact.
3. Confirm the callback runs exactly once and that its parameters describe the expected object and state.
4. Disable or unassign the listener and repeat the action. The callback should not run.
5. Re-enable or reassign the listener and repeat once more. The callback should again run exactly once, not once per previous enable cycle.
For a custom event, first test the object-scoped form on one known GameObject before considering a global version.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| The callback never runs | Compare the target object, event name, generic types, type order, and registration timing with the publisher | Use the publisher's exact target and typed contract, and register before the gameplay action occurs |
| The Console reports an unexpected event type | Check whether another listener registered the same target and name with a different generic signature | Correct the signature or give the different contract a distinct event name |
| The callback runs twice | Check repeated `OnEnable`, initialization, or character-assignment paths | Pair every registration with one matching unregistration and remove the duplicate path |
| Unregistration has no effect | Compare the target, name, generic arguments, and delegate instance | Use the same named method or cached delegate and the same target that was registered |
| A callback fires after a scene change or reassignment | Check global registrations and listeners that retained the old character or target | Unregister before unloading, disabling, returning to a pool, or replacing the target |
| A pooled object stops receiving events | Check whether it unregisters on disable but never re-registers on enable | Pair `OnEnable` with `OnDisable` and verify both are reached once per pool cycle |
| A background task causes inconsistent behavior | Check whether it calls EventHandler or Unity APIs off the main thread | Marshal the result back to Unity's main thread before registering, executing, or unregistering |
## Related workflows
- [Event names](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/event-names/)
- [Programming concepts](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/)
- [Health](https://opsive.com/support/documentation/ultimate-character-controller/attributes/health/)
- [Create a custom Ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/new-ability/)
- [Inventory](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/inventory/)
- [Object pool](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/object-pool/)
## API reference
### Register, execute, and unregister
String literals are accepted because they convert to the Shared `StringHash` value used by the API. Object-scoped and global forms support zero through six typed parameters:
```csharp
using EventHandler = Opsive.Shared.Events.EventHandler;
// Object-scoped, no parameters.
EventHandler.RegisterEvent(target, "OnProjectReady", OnProjectReady);
EventHandler.ExecuteEvent(target, "OnProjectReady");
EventHandler.UnregisterEvent(target, "OnProjectReady", OnProjectReady);
// Object-scoped, two parameters.
EventHandler.RegisterEvent(
target, "OnProjectValueChanged", OnProjectValueChanged);
EventHandler.ExecuteEvent(
target, "OnProjectValueChanged", 12, true);
EventHandler.UnregisterEvent(
target, "OnProjectValueChanged", OnProjectValueChanged);
// Global, one parameter: omit the target from all three calls.
EventHandler.RegisterEvent(
"OnProjectAnnouncement", OnProjectAnnouncement);
EventHandler.ExecuteEvent(
"OnProjectAnnouncement", "Round started");
EventHandler.UnregisterEvent(
"OnProjectAnnouncement", OnProjectAnnouncement);
```
`RegisterUnregisterEvent` is a convenience method when one lifecycle method already receives a boolean registration state:
```csharp
private void SetEventRegistration(bool register)
{
EventHandler.RegisterUnregisterEvent(
register,
character,
"OnCharacterAbilityActive",
OnAbilityActive);
}
```
### Cache a custom event name
For a project event used frequently, cache its `StringHash` and keep the parameter contract beside it:
```csharp
using Opsive.Shared.Runtime.Utility;
using EventHandler = Opsive.Shared.Events.EventHandler;
private static readonly StringHash s_OnAlertLevelChanged =
new StringHash("OnAlertLevelChanged");
private void PublishAlertLevel(int level)
{
EventHandler.ExecuteEvent(
gameObject, s_OnAlertLevelChanged, level);
}
```
The listener must register and unregister with `RegisterEvent` and `UnregisterEvent` using that same target and event name.
---
# Event Names
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/event-names/)
Use this reference to match an Ultimate Character Controller event name with the exact callback signature used by the released 3.2.0 runtime. The target object, event name, parameter types, and parameter order must all match the publisher.
## Find the correct event and signature
Before registering a callback:
1. Find the relevant `EventHandler.ExecuteEvent` call in the Ultimate Character Controller or Opsive Shared source. Animator and input callbacks may instead be created by an animation event or an `ActiveInputEvent`.
2. Note whether the call is object-scoped, such as `ExecuteEvent(character, ...)`, or global, such as `ExecuteEvent("OnStateChange", ...)`.
3. Copy the event name exactly, including capitalization and any dynamic suffix such as the item slot ID.
4. Match the generic parameter types and their order. A fully qualified type and its imported short name are the same type.
5. Register and unregister the same delegate on the same target object.
The tables below inventory the string event contracts found in the UCC 3.2.0 and Opsive Shared runtime source. Optional integrations can add their own events.
## Register and unregister safely
Register while the listener is active and always unregister before the listener is destroyed or pooled. This component listens on the character that owns the `UltimateCharacterLocomotion` component:
```csharp
using Opsive.Shared.Events;
using Opsive.UltimateCharacterController.Character.Abilities;
using UnityEngine;
public class AbilityStateListener : MonoBehaviour
{
[SerializeField] private GameObject m_Character;
private void OnEnable()
{
EventHandler.RegisterEvent(
m_Character, "OnCharacterAbilityActive", OnAbilityActive);
}
private void OnDisable()
{
EventHandler.UnregisterEvent(
m_Character, "OnCharacterAbilityActive", OnAbilityActive);
}
private void OnAbilityActive(Ability ability, bool active)
{
Debug.Log($"{ability.GetType().Name}: {active}");
}
}
```
Do not replace `OnAbilityActive` with a new lambda in `UnregisterEvent`; it would be a different delegate and would leave the original callback registered.
## Character and locomotion events
### Character lifecycle and movement
| Event | Parameters | Runtime use |
| --- | --- | --- |
| `OnCharacterAbilityActive` | `Ability, bool` | A non-item ability started or stopped. |
| `OnCharacterActivate` | `bool` | The character became active or inactive. |
| `OnCharacterAttachCamera` | `CameraController` | A camera controller was attached to the character. |
| `OnCharacterAttachLookSource` | `ILookSource` | The character's look source changed. |
| `OnCharacterChangeMovementType` | `MovementType, bool` | A movement type was deactivated or activated. The Boolean is the active state. |
| `OnCharacterChangeMovingPlatforms` | `Transform` | The active moving platform changed; the transform can be `null`. |
| `OnCharacterChangePerspectives` | `bool` | The character changed to first person (`true`) or third person (`false`). |
| `OnCharacterChangeTimeScale` | `float` | The character time scale changed. |
| `OnCharacterDestroyed` | `()` | Consumer contract used when character-owned helper objects should be destroyed. |
| `OnCharacterForceIndependentLook` | `bool` | An ability requested or released independent look control. |
| `OnCharacterGrounded` | `bool` | The grounded state changed. |
| `OnCharacterImmediateTransformChange` | `bool` | Position or rotation changed immediately; the Boolean requests an Animator snap. |
| `OnCharacterIndependentFade` | `bool, bool` | Another system took or released control of character fading, with the requested revert behavior. |
| `OnCharacterItemAbilityActive` | `ItemAbility, bool` | An item ability started or stopped. |
| `OnCharacterLand` | `float` | The character landed after falling the supplied height. |
| `OnCharacterLean` | `float, float, float` | Lean distance, tilt, and item-tilt multiplier changed. |
| `OnCharacterMoving` | `bool` | The character started or stopped moving. |
| `OnCharacterSnapAnimator` | `bool` | Consumers should snap Animator state; the Boolean controls whether `OnAnimatorSnapped` is then executed. |
| `OnCharacterSwitchModels` | `GameObject` | `ModelManager` changed the active character model. |
| `OnCharacterUpdateAbilityParameters` | `bool` | Ability Animator parameters should update; the Boolean requests an immediate update. |
| `OnCharacterUpdateItemAbilityParameters` | `bool` | Item-ability Animator parameters should update; the Boolean forces changed values to be applied. |
| `OnEnableGameplayInput` | `bool` | Character gameplay input was enabled or disabled. |
| `OnHeightChangeAdjustHeight` | `float` | The Height Change ability applied a collider-height adjustment. |
| `OnStoredInputAbilityResetStoredInputs` | `()` | Stored movement input should be cleared. |
### Input and movement-type callbacks
| Event | Parameters | Runtime use |
| --- | --- | --- |
| `OnAssistAimSwitchInput` | `float` | Axis input used to switch Assist Aim targets. |
| `OnAssistAimUpdateBreakForce` | `float` | Axis input used to update Assist Aim break force. |
| `OnInputControllerConnected` | `bool` | A controller connected or disconnected. |
| `OnJumpAbilityAirborneJump` | `()` | Button-down input requests an airborne jump. |
| `OnJumpAbilityReleaseHold` | `()` | Button-up input releases a held jump. |
| `OnLeanInputUpdate` | `float` | Axis input updates the active Lean ability. |
| `OnRPGMovementTypeAutoMove` | `()` | Input toggles RPG automatic movement. |
| `OnRPGMovementTypeStartRotate` | `()` | Input begins RPG rotation. |
| `OnRPGMovementTypeStopRotate` | `()` | Input ends RPG rotation. |
| `OnRPGMovementTypeTurn` | `float` | Axis input supplies the RPG turn amount. |
| `OnUnityInputSystemTypeChanged` | `bool` | Unity Input System on-screen-control mode changed. |
| `OnUnityInputTypeChanged` | `UnityInput, bool` | Legacy `UnityInput` virtual-input mode changed. |
### Ability animation callbacks
These zero-parameter names are received through the character Animator Monitor. The animation clip must contain the corresponding animation event when an ability is configured to wait for it.
| Event | Parameters | Runtime use |
| --- | --- | --- |
| `OnAnimatorDamageVisualizationComplete` | `()` | Damage Visualization animation completed. |
| `OnAnimatorDropItem` | `()` | The Drop ability reached its drop point. |
| `OnAnimatorEnteredVehicle` | `()` | The vehicle-entry animation reached its completion point. |
| `OnAnimatorExitedVehicle` | `()` | The vehicle-exit animation reached its completion point. |
| `OnAnimatorFallComplete` | `()` | The Fall ability's landing animation completed. |
| `OnAnimatorGenericAbilityComplete` | `()` | A Generic ability animation completed. |
| `OnAnimatorImpactKnockBackComplete` | `()` | Impact Knock Back animation completed. |
| `OnAnimatorInteract` | `()` | The Interact ability reached its interaction point. |
| `OnAnimatorInteractComplete` | `()` | The Interact ability animation completed. |
| `OnAnimatorJump` | `()` | The Jump ability reached its force-application point. |
| `OnAnimatorPickup` | `()` | The Pickup ability reached its pickup point. |
| `OnAnimatorPickupComplete` | `()` | The Pickup ability animation completed. |
| `OnAnimatorQuickTurnComplete` | `()` | Quick Turn animation completed. |
| `OnAnimatorReviveComplete` | `()` | Revive animation completed. |
| `OnAnimatorRideDismount` | `()` | The Ride ability reached its dismount point. |
| `OnAnimatorRideMount` | `()` | The Ride ability reached its mount point. |
| `OnAnimatorRideMountComplete` | `()` | The Ride mount animation completed. |
| `OnAnimatorSnapped` | `()` | The Animator Monitor finished snapping. |
| `OnAnimatorStartMovementComplete` | `()` | Quick Start animation completed. |
| `OnAnimatorStopMovementComplete` | `()` | Quick Stop animation completed. |
| `OnAnimatorWillSnap` | `()` | The Animator Monitor is about to snap. |
### Item animation callbacks
An `AnimationSlotEventTrigger` registers both the base name and a zero-parameter name ending in `Slot{slotID}`. For example, slot 1 can invoke either `OnAnimatorItemUse` or `OnAnimatorItemUseSlot1`. Rows shown as "base or slot" use that behavior; the remaining rows use only the displayed name.
| Event | Parameters | Runtime use |
| --- | --- | --- |
| `OnAnimatorActivateThrowableObject` | `()` | A throwable module activates its throwable object. |
| `OnAnimatorActiveAttackStart` or `OnAnimatorActiveAttackStartSlot{slotID}` | `()` | A melee attack enters its active hit period. |
| `OnAnimatorAllowChainAttack` or `OnAnimatorAllowChainAttackSlot{slotID}` | `()` | A melee attack allows the next chained attack. |
| `OnAnimatorEndCast` or `OnAnimatorEndCastSlot{slotID}` | `()` | A magic caster reaches its end-cast point. |
| `OnAnimatorItemDepleteChargeComplete` or `OnAnimatorItemDepleteChargeCompleteSlot{slotID}` | `()` | An item trigger finishes depleting its charge. |
| `OnAnimatorItemEquip` or `OnAnimatorItemEquipSlot{slotID}` | `()` | A Character Item reaches its equip point. |
| `OnAnimatorItemEquipComplete` or `OnAnimatorItemEquipCompleteSlot{slotID}` | `()` | A Character Item's equip animation completes. |
| `OnAnimatorItemImpactComplete` | `()` | An item-impact animation completes. |
| `OnAnimatorItemImpactCompleteSlot{slotID}` | `()` | A Block item-impact animation completes for the appended slot ID. |
| `OnAnimatorItemMaxChargeComplete` or `OnAnimatorItemMaxChargeCompleteSlot{slotID}` | `()` | An item trigger reaches maximum charge. |
| `OnAnimatorItemMinChargeComplete` or `OnAnimatorItemMinChargeCompleteSlot{slotID}` | `()` | An item trigger reaches minimum charge. |
| `OnAnimatorItemReactivateClip` | `()` | A shootable reloader reactivates its clip. |
| `OnAnimatorItemReload` or `OnAnimatorItemReloadSlot{slotID}` | `()` | A shootable reloader reaches its reload point. |
| `OnAnimatorItemReloadAttachClip` | `()` | A shootable reloader attaches its clip. |
| `OnAnimatorItemReloadAttachProjectile` | `()` | A projectile module attaches the reload projectile. |
| `OnAnimatorItemReloadComplete` or `OnAnimatorItemReloadCompleteSlot{slotID}` | `()` | A shootable reload animation completes. |
| `OnAnimatorItemReloadDetachClip` | `()` | A shootable reloader detaches its clip. |
| `OnAnimatorItemReloadDropClip` | `()` | A shootable reloader drops its detached clip. |
| `OnAnimatorItemReloadShowProjectile` | `()` | A projectile module shows its reload projectile. |
| `OnAnimatorItemRemovePin` | `()` | A throwable module removes its pin. |
| `OnAnimatorItemUnequip` or `OnAnimatorItemUnequipSlot{slotID}` | `()` | A Character Item reaches its unequip point. |
| `OnAnimatorItemUnequipComplete` or `OnAnimatorItemUnequipCompleteSlot{slotID}` | `()` | A Character Item's unequip animation completes. |
| `OnAnimatorItemUse` or `OnAnimatorItemUseSlot{slotID}` | `()` | A usable item reaches its use point. |
| `OnAnimatorItemUseComplete` or `OnAnimatorItemUseCompleteSlot{slotID}` | `()` | A usable item's animation completes. |
| `OnAnimatorMeleeAttackComplete` or `OnAnimatorMeleeAttackCompleteSlot{slotID}` | `()` | A melee attack animation completes. |
| `OnAnimatorReequipThrowableItem` or `OnAnimatorReequipThrowableItemSlot{slotID}` | `()` | A throwable item reaches its re-equip point. |
| `OnAnimatorRepeatCast` or `OnAnimatorRepeatCastSlot{slotID}` | `()` | A magic caster reaches its repeat-cast point. |
| `OnAnimatorStartCast` or `OnAnimatorStartCastSlot{slotID}` | `()` | A magic caster reaches its start-cast point. |
| `OnAnimatorStartVisibleProjectile` | `()` | A projectile module begins showing its visible projectile. |
| `OnAnimatorStopTrail` | `()` | A melee extra module stops its trail. |
### State System
| Event | Parameters | Runtime use |
| --- | --- | --- |
| `OnStateChange` | `GameObject, string, bool` | Global event sent when a state changes, but only when the scene `StateManager` has **Send State Change Event** enabled. |
`OnStateChange` is global. Register it without a target object; do not register it on the changed GameObject.
## Abilities, items, and inventory events
### Ability and aiming events
| Event | Parameters | Runtime use |
| --- | --- | --- |
| `OnAbilityMessageCanStart` | `Ability, bool` | An ability's message-based start permission changed. |
| `OnAbilityUnequipItemComplete` | `CharacterItem, int` | Unequipping a Character Item from a slot completed. |
| `OnAbilityWillEquipItem` | `CharacterItem, int` | An ability is about to equip a Character Item in a slot. |
| `OnAimAbilityAim` | `bool` | The Aim ability's aiming state changed. |
| `OnAimAbilityStart` | `bool, bool` | Aim started or stopped; the second value identifies an input-driven change. |
| `OnAimTargetChange` | `int, Transform, bool` | An Assist Aim target ID, target transform, or lock state changed. |
| `OnEquipUnequipItemSetIndexChange` | `int` | Equip Unequip changed its item-set index. |
| `OnEquipUnequipVerifyUnequipItem` | `int, int` | Equip Unequip requests verification for an item-set group and slot before completing unequip. |
| `OnUseAbilityStart` | `bool, Use` | A Use ability started or stopped. |
| `OnUseAbilityUsedItem` | `IUsableItem` | The Use ability used an item. |
### Inventory and item-set events
| Event | Parameters | Runtime use |
| --- | --- | --- |
| `OnActiveItemSetChange` | `int, ItemSet, ItemSet` | An item-set group changed from its previous set to a new set. |
| `OnInventoryAddItem` | `CharacterItem` | A Character Item was added to the inventory. |
| `OnInventoryAdjustItemIdentifierAmount` | `IItemIdentifier, int, int` | An Item Identifier amount changed from the previous amount to the new amount. |
| `OnInventoryDestroyItem` | `CharacterItem` | A Character Item is being destroyed by the inventory. |
| `OnInventoryDropItem` | `GameObject` | Removing an Item Identifier with dropping enabled produced a drop instance. |
| `OnInventoryDropItem` | `CharacterItem, int, GameObject` | A Character Item drop reports the item, amount, and spawned object. |
| `OnInventoryEquipItem` | `CharacterItem, int` | A Character Item was equipped in a slot. |
| `OnInventoryLoadDefaultLoadoutComplete` | `()` | The inventory finished loading its default loadout. |
| `OnInventoryPickupItem` | `CharacterItem, int, bool, bool` | A Character Item pickup reports amount, immediate-pickup, and force-equip choices. |
| `OnInventoryPickupItemIdentifier` | `IItemIdentifier, int, bool, bool` | An Item Identifier pickup reports amount, immediate-pickup, and force-equip choices. |
| `OnInventoryRemoveItem` | `CharacterItem, int` | A Character Item was removed from a slot. |
| `OnInventoryRespawned` | `()` | Inventory respawn processing completed. |
| `OnInventoryUnequipItem` | `CharacterItem, int` | A Character Item was unequipped from a slot. |
| `OnInventoryWillAddItem` | `CharacterItem` | A Character Item is about to be added. |
| `OnItemSetGroupUpdated` | `ItemSetGroup` | An item-set group finished updating. |
| `OnItemSetGroupWillUpdate` | `ItemSetGroup, List` | An item-set group is about to update and exposes its state list. |
| `OnItemSetIndexChange` | `int, int` | An item-set group index and active item-set index changed. |
| `OnItemSetManagerUpdateItemSet` | `int, int` | The Item Set Manager should update a group's active item set. |
| `OnItemSetManagerUpdateNextItemSet` | `int, int, int` | The Item Set Manager reports the group, previous set, and next set indices. |
| `OnNextItemSet` | `CharacterItem, bool` | A Character Item requests the next item set and states whether failure should unequip it. |
`OnInventoryDropItem` deliberately has two parameter shapes in 3.2.0. If one listener registers both shapes on the same character, use the `allowMultipleTypes` overload for both registrations.
### Item actions, perspective items, and UI
| Event | Parameters | Runtime use |
| --- | --- | --- |
| `OnAddCrosshairsSpread` | `bool, bool` | Starts or stops crosshair spread and identifies recoil-driven spread. |
| `OnAddSecondaryCameraForce` | `Vector3, Vector3, float` | Adds positional and rotational camera force with a rest-accumulation value. |
| `OnAddSecondaryForce` | `int, Vector3, Vector3, bool` | Adds positional and rotational item force for a slot, optionally in global space. |
| `OnFirstPersonPerspectiveActivate` | `FirstPersonPerspectiveItem, bool` | A first-person perspective item activated or deactivated. |
| `OnFirstPersonPerspectiveItemStartEquip` | `CharacterItem` | A first-person Character Item began equipping. |
| `OnFirstPersonPerspectiveItemUnequip` | `CharacterItem` | A first-person Character Item was unequipped. |
| `OnItemActionTriggerStoppedEarly` | `TriggerModule` | A trigger module stopped before it triggered, such as when its character died. |
| `OnItemPickupStartPickup` | `()` | An Item Pickup began its pickup sequence. |
| `OnItemPickupStopPickup` | `()` | An Item Pickup ended its pickup sequence. |
| `OnItemReload` | `IReloadableItem` | Reloading began for a reloadable item. |
| `OnItemReloadComplete` | `IReloadableItem` | Reloading completed for a reloadable item. |
| `OnItemShowFullScreenUI` | `int, bool` | A Character Item requests that its full-screen UI ID be shown or hidden. |
| `OnItemStartUse` | `IUsableItem, bool` | A usable item began or ended use. |
| `OnItemTryReload` | `int, IItemIdentifier, IItemIdentifier, bool, bool` | A slot requests reload with the item and consumable identifiers plus immediate-reload and equip-check choices. |
| `OnItemUpdateDominantItem` | `CharacterItem, bool` | A Character Item's dominant-item state changed. |
| `OnItemUse` | `IUsableItem` | A usable item performed its use action. |
| `OnItemUseComplete` | `IUsableItem` | A usable item's use action completed. |
| `OnMagicItemCast` | `CharacterItem` | A magic Character Item cast. |
| `OnMagicItemStartStopBeginEndActions` | `CharacterItem, bool, bool` | A magic item started or stopped its begin/end actions. |
| `OnMeleeRecoil` | `MeleeRecoilModule` | A melee recoil module applied recoil. |
| `OnMonitoredCharacterItemChanged` | `CharacterItem, CharacterItem` | An item monitor changed from its previous Character Item to a new one. |
| `OnRefreshSlotItemMonitor` | `CharacterItem` | A Character Item requests a slot monitor refresh. |
| `OnShieldImpact` | `ShieldAction, ImpactCallbackContext` | A Shield Action received an impact context. |
| `OnShootableItemAmmoChange` | `CharacterItem, ShootableAmmoModule` | A shootable item's active ammo module or amount changed. |
| `OnShootableItemClipChange` | `CharacterItem, ShootableClipModule` | A shootable item's active clip module or amount changed. |
| `OnShootableWeaponShowProjectile` | `GameObject, bool` | A shootable item requests that a projectile object be shown or hidden. |
| `OnStartReload` | `ShootableReloaderModule` | A shootable reloader module began reloading. |
| `OnThrowableItemAmmoChange` | `CharacterItem, ThrowableAmmoModule` | A throwable item's active ammo module or amount changed. |
## Health and attribute events
| Event | Parameters | Runtime use |
| --- | --- | --- |
| `OnAttributeModifierAutoUpdateEnabled` | `AttributeModifier, bool` | An Attribute Modifier's automatic update was enabled or disabled. See the 3.2.0 source note below before relying on the built-in impact listener. |
| `OnAttributeReachedDestinationValue` | `()` | An Attribute reached its configured destination value. This event is scoped to the `Attribute` object. |
| `OnAttributeUpdateValue` | `Attribute` | An Attribute value changed. This event is scoped to the Attribute Manager's GameObject. |
| `OnDeath` | `Vector3, Vector3, GameObject` | Health reached zero and reports impact position, force, and attacker. |
| `OnHealthDamage` | `float, Vector3, Vector3, GameObject, Collider` | Health received damage with amount, position, force, attacker, and hit collider. |
| `OnHealthDamageWithData` | `DamageData` | Health received the complete damage payload. |
| `OnHealthHeal` | `float` | Health was healed by the supplied amount. |
| `OnRespawn` | `()` | An object completed its respawn or pooled reset. |
| `OnWillRespawn` | `()` | A Respawner is about to respawn the object. |
## Camera, objects, and impact events
### Camera and view types
| Event | Parameters | Runtime use |
| --- | --- | --- |
| `OnAnchorOffsetUpdated` | `()` | The Camera Controller anchor offset changed during Play Mode. |
| `OnCameraAttachCharacter` | `GameObject` | The Camera Controller attached a character. |
| `OnCameraChangePerspectives` | `bool` | The camera changed to first person (`true`) or third person (`false`). |
| `OnCameraChangeViewTypes` | `ViewType, bool` | A View Type was deactivated or activated. |
| `OnCameraImmediatePosition` | `()` | The camera should move to its target position immediately. |
| `OnCameraPositionalForce` | `Vector3` | Adds positional force to the attached Camera Controller. |
| `OnCameraRotationalForce` | `Vector3` | Adds rotational force to the attached Camera Controller. |
| `OnCameraWillChangePerspectives` | `bool` | The camera is about to change perspective. |
| `OnCameraZoom` | `bool` | Camera zoom activated or deactivated. |
| `OnRPGViewTypeStartForcedRotation` | `()` | RPG view forced rotation began. |
| `OnRPGViewTypeStartFreeMovement` | `()` | RPG view free movement began. |
| `OnRPGViewTypeStopForcedRotation` | `()` | RPG view forced rotation ended. |
| `OnRPGViewTypeStopFreeMovement` | `()` | RPG view free movement ended. |
| `OnThirdPersonViewTypeStepZoom` | `float` | A third-person view requests a zoom step. |
| `OnTryRecenterTracking` | `()` | A global event requests tracking recentering after a view rotation change. |
### Objects, impacts, and monitors
| Event | Parameters | Runtime use |
| --- | --- | --- |
| `OnObjectDetected` | `GameObject, bool` | A detected object receives the interacting character and selected state. |
| `OnObjectImpact` | `ImpactCallbackContext` | The impacted object receives the impact context. |
| `OnObjectImpactSourceCallback` | `ImpactCallbackContext` | The impact originator receives its source callback context. |
| `OnObjectPickedUp` | `ObjectPickup` | A character picked up an Object Pickup. |
| `OnShowUI` | `bool` | Character monitors should show or hide their UI. |
## Verify a callback
1. Add a temporary log or breakpoint inside the callback.
2. Enter Play Mode and trigger the smallest action that publishes the event.
3. Confirm the callback fires once and that its values match the observed action.
4. Disable or despawn the listener, repeat the action, and confirm it no longer fires.
5. Re-enable or respawn the listener and confirm it still fires only once.
For an Animator callback, inspect the animation clip and confirm the animation event name matches exactly. For an input callback, confirm the owning ability or movement type registered its `ActiveInputEvent` before testing.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| Callback never runs | Compare the object passed to `RegisterEvent` with the publisher's first `ExecuteEvent` argument. | Register on the same character, camera, Attribute, impacted object, or other owner. Use the targetless overload only for a global event. |
| Callback reports a type mismatch | Compare every generic type and its order with the publisher. | Update both `RegisterEvent` and `UnregisterEvent` to the exact signature. |
| Callback runs more than once | Look for repeated registration during enable, pooling, or initialization. | Pair one registration with one unregistration and reuse the same delegate instance. |
| Callback remains after despawn | Check whether the pooled object unregisters before returning to the pool. | Unregister in the listener's disable or teardown path. |
| Animator callback never runs | Inspect the active animation clip and whether the ability is waiting for an event rather than a duration. | Add or correct the clip event, or configure the supported duration path. |
| `OnStateChange` never runs | Inspect the scene `StateManager`. | Enable **Send State Change Event** and use a global registration. |
| One `OnInventoryDropItem` signature conflicts with the other | Check whether both signatures were registered under the same target and name. | Register both with the `allowMultipleTypes` overload, or listen only to the path you need. |
## UCC 3.2.0 source notes
The released 3.2.0 source contains a few cleanup or spelling mismatches. They are not additional event contracts:
- `AttributeModifier` publishes `OnAttributeModifierAutoUpdateEnabled`, but the built-in impact action registers `OnAttributeModifierAutoUpdateEnable`. That listener does not match the publisher.
- Equip Unequip registers `OnEquipUnequipVerifyUnequipItem` but unregisters `OnEquipUnequipVerifyUnequip`. The valid runtime event includes `Item`.
- Lean registers `OnCharacterChangePerspectives` with a `bool` callback but its final cleanup uses `OnLeanInputUpdate`. The valid `OnLeanInputUpdate` runtime signature is `float`.
- Shield Action contains cleanup for `OnBlockAbilityStart`, but the released runtime has no matching registration or execution for that literal.
Do not build new listeners around the mismatched spellings. If these defects affect a project, keep any local source correction isolated so it can be reviewed when updating UCC.
## EventHandler API reference
`Opsive.Shared.Events.EventHandler` provides object-scoped and global overloads for zero through six parameters:
```csharp
// Object-scoped.
EventHandler.RegisterEvent(target, eventName, callback);
EventHandler.ExecuteEvent(target, eventName, value);
EventHandler.UnregisterEvent(target, eventName, callback);
// Global.
EventHandler.RegisterEvent(eventName, callback);
EventHandler.ExecuteEvent(eventName, value);
EventHandler.UnregisterEvent(eventName, callback);
```
The event name parameter is a `StringHash`; string literals convert to it implicitly. The handler stores registrations in static tables and clears them during Unity's subsystem registration. Use events on Unity's main thread and unregister normal object and pooled-object listeners explicitly rather than relying on a later domain or subsystem reset.
The one-, two-, and three-parameter registration overloads also accept `allowMultipleTypes`. Use that option only when the same target and event name intentionally carry more than one signature, such as `OnInventoryDropItem`.
## Related pages
- [Events overview](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/)
- [Programming concepts](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/)
- [Create a custom ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/new-ability/)
- [Inventory](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/inventory/)
- [Health](https://opsive.com/support/documentation/ultimate-character-controller/attributes/health/)
- [Object pool](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/object-pool/)
- [Objects](https://opsive.com/support/documentation/ultimate-character-controller/objects/)
---
# Scheduler
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/scheduler/)
Run a callback later in UCC's shared Update or FixedUpdate loop, and keep a cancellable handle when the work must stop with its owner. Use the Scheduler for small game-time delays and repeating controller work, not as an ownerless replacement for every coroutine or update method.
## When to use the Scheduler
The Scheduler is a good fit when code needs to:
- finish a projectile, effect, state, or animation fallback after a short game-time delay;
- defer physics or locomotion work to a later FixedUpdate;
- repeat a small callback every Update or FixedUpdate without adding another `MonoBehaviour` update method; or
- cancel pending work when an ability, item, pooled object, or scene owner stops.
Keep an ordinary `Update`, `FixedUpdate`, coroutine, or purpose-built UCC lifecycle when the operation needs complex sequencing, yields, unscaled time, per-character time, or several independently visible states.
## Set up the Scheduler
No scene component is required for a basic call. The first `Scheduler.Schedule` or `Scheduler.ScheduleFixed` finds an existing `SchedulerBase`; if none exists, it creates a GameObject named `Scheduler` with a `SchedulerBase` component.
Add one **Scheduler** component deliberately when capacity and scene ownership matter. Its **Max Event Count** defaults to `200` and allocates separate arrays of that size for Update and FixedUpdate callbacks during `Awake`. Change the value before Play Mode. In Play Mode, its Inspector shows the scheduled callback target and method for diagnosis.
Keep that Scheduler in a scene that remains loaded for as long as its callbacks are expected to run. It is a global queue, not a queue owned by the component that scheduled each callback.
## Choose when the callback runs
Both scheduling methods calculate their end time from `TimeUtility.Time`. Without a project `TimeManagerBase`, that is Unity's scaled `Time.time`.
| Requirement | Choice | Observable behavior |
| --- | --- | --- |
| General gameplay, presentation, respawn, or UI-adjacent work | `Scheduler.Schedule` | The callback runs from the Scheduler's next eligible `Update` after the global end time. |
| Physics, locomotion, or item work that must align with a physics step | `Scheduler.ScheduleFixed` | The callback runs from the next eligible `FixedUpdate` after the same global end time. |
| Run synchronously | A delay of `0` | On an enabled Scheduler, the action runs inside the `Schedule` call and the method returns `null`; nothing enters the queue. |
| Repeat every rendered frame | `Scheduler.Schedule(-1, action)` | The action runs every `Update` until explicitly cancelled. |
| Repeat every physics step | `Scheduler.ScheduleFixed(-1, action)` | The action runs every `FixedUpdate` until explicitly cancelled. |
A positive delay is a minimum, not an exact timestamp: the callback waits until its selected loop next checks the queue. Do not use negative delays other than the documented `-1` repeating value.
The released Shared Scheduler has no unscaled-time overload. At the default clock, a positive delay pauses when `Time.timeScale` is `0`; `FixedUpdate` also stops running. Use an owner-managed timer based on `Time.unscaledTime` or `Time.unscaledDeltaTime` when a pause menu, connection timeout, or other real-time operation must continue.
The `-1` sentinel is loop-driven rather than elapsed-time-driven. An Update repeater continues while global time is paused because Unity still calls `Update`; a FixedUpdate repeater waits because Unity stops physics steps at a zero time scale.
The Scheduler also does not read an individual `UltimateCharacterLocomotion.TimeScale`. A slowed or paused character's scheduled callback still follows the global `TimeUtility.Time`. Keep character-time work in the owning UCC lifecycle, or accumulate time explicitly from that character's scale when it must adapt to changes during the delay. A project `TimeManagerBase` changes the Scheduler's clock globally, not per character.
## Own the handle lifecycle
Every nonzero call returns a `ScheduledEventBase` handle. Store it when the callback might need to be cancelled.
1. Cancel the previous handle before replacing it.
2. Assign the new handle returned by `Schedule` or `ScheduleFixed`.
3. At the start of a one-shot callback, set the owning field to `null`.
4. On early completion, disable, destruction, or pool return, call `Scheduler.Cancel(handle)` and immediately set the field to `null`.
5. Explicitly cancel every `-1` repeating event; it never removes itself.
Scheduled event objects are internally obtained from `GenericObjectPool`. A one-shot handle is removed from the active queue before its callback and returned to that pool after the callback finishes. Cancellation also returns it. The same object can then become another system's event, so a completed or cancelled handle is no longer yours: do not retain it, poll its `Active` property later, or cancel it again.
`Active` is useful only while the owner still controls a pending handle. A stale reference may become active again when the internal object is reused for an unrelated callback.
## Clean up with the owner
The Scheduler does not inspect the callback target's lifetime and does not automatically cancel by GameObject, component, ability, item, or scene. A disabled component's callback still runs unless it is cancelled, and a delegate can retain captured objects until the event is reused.
- Cancel owner-bound work in `OnDisable` when disabling means the operation has ended.
- Use `OnDestroy` as a final cleanup path for work that intentionally survives a temporary disable.
- For a pooled GameObject, cancel in `OnDisable`, clear the handle, and schedule a fresh event after each checkout.
- For an ability or item module, cancel when the action stops or the module is no longer active, not only when the character is destroyed.
- Avoid lambdas that capture a large object graph when a method plus one of the Scheduler's typed parameter overloads can pass the required values directly.
Some lifecycles intentionally outlive a disabled target. The built-in **Respawner**, for example, can schedule a respawn while its GameObject is inactive because the independent Scheduler remains active. Decide that ownership explicitly rather than applying `OnDisable` cancellation to every use case.
The Scheduler singleton reference resets at subsystem registration and after its scene unloads. Active callbacks do not migrate to a replacement Scheduler. Stop or transfer the owning operation before unloading the Scheduler's scene.
## Verify in Play Mode
1. Schedule one visible one-shot result with a positive delay. Confirm it does not run immediately and runs once from the intended Update or FixedUpdate phase.
2. Schedule it again, cancel the handle before the end time, set the field to `null`, and confirm the result never occurs.
3. Disable or return the owner to its pool before the delay completes. Confirm no callback changes the inactive or reused object.
4. Re-enable or reuse the owner and trigger it twice. Confirm one current handle exists and the callback occurs only once for the latest use.
5. Pause global time. Confirm ordinary Scheduler delays wait until global time resumes; separately test an owner-managed unscaled timer if the feature requires one.
6. If the feature uses a character-specific time scale, slow only that character and confirm whether the intended behavior should follow the character or the global Scheduler clock.
7. Select the scene Scheduler in Play Mode. Confirm its active count returns to the baseline after completion or cancellation and the Console has no capacity or missing-reference error.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| The callback runs immediately and the saved handle is `null`. | The supplied delay is `0`. | Call the method directly when synchronous execution is intended, or use a positive delay when a queued, cancellable callback is required. |
| A callback runs after an ability, component, or pooled object has stopped. | Its handle was not cancelled in the owner's stop, disable, destroy, or return path. | Cancel the current handle and set the field to `null` before the owner can be reused. |
| Cancelling one operation stops an unrelated callback. | Code retained a handle after its callback or cancellation, and that pooled handle was reused. | Clear the field during both completion and cancellation. Never reuse or inspect an expired handle. |
| A delay does not progress while the game is paused. | Scheduler uses scaled `TimeUtility.Time`, and `ScheduleFixed` also needs FixedUpdate to run. | Use an explicit unscaled timer for real-time work; do not expect a Scheduler overload to change clocks. |
| A slowed character's callback fires at normal game speed. | Scheduler has no per-character time-scale parameter. | Keep the timer in the character-owned lifecycle and advance it using the intended character-scale rule. |
| The Console reports that the `ActiveEvents` array is full. | Concurrent Update or FixedUpdate events reached **Max Event Count**, commonly because `-1` events or ownerless callbacks were not cancelled. | Cancel leaked work, reduce repeating callbacks, then raise **Max Event Count** before Play Mode only if the measured workload requires it. |
| No callback runs after a scene transition. | The scene that owned the Scheduler unloaded, or the explicit Scheduler component was disabled. | Keep the Scheduler in the required long-lived scene and reschedule work under the new scene owner. Do not schedule against a disabled Scheduler. |
## Related pages
- [Programming Concepts](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/)
- [Object Pool](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/object-pool/)
- [Events](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/)
- [Respawner](https://opsive.com/support/documentation/ultimate-character-controller/spawn-system/respawner/)
- [Animation Event Trigger](https://opsive.com/support/documentation/ultimate-character-controller/animation/animation-event-trigger/)
- [Projectile](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/projectile/)
## API examples
### Cancel a one-shot event safely
This component assumes its root was checked out through the [Object Pool](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/object-pool/). It schedules a fresh return on every activation, clears the field before the callback returns the GameObject, and cancels an early disable.
```csharp
using Opsive.Shared.Game;
using UnityEngine;
public sealed class TimedPooledEffect : MonoBehaviour
{
[Min(0.001f)]
[SerializeField] private float m_Lifetime = 1.5f;
private ScheduledEventBase m_ReturnEvent;
private void OnEnable()
{
CancelReturn();
m_ReturnEvent = Scheduler.Schedule(m_Lifetime, ReturnToPool);
}
private void ReturnToPool()
{
m_ReturnEvent = null;
ObjectPool.Destroy(gameObject);
}
private void OnDisable()
{
CancelReturn();
}
private void CancelReturn()
{
if (m_ReturnEvent == null) {
return;
}
Scheduler.Cancel(m_ReturnEvent);
m_ReturnEvent = null;
}
}
```
For an object that is not pool-owned, replace `ObjectPool.Destroy` with the completion behavior owned by that object.
### Pass values without a capturing lambda
The released API provides zero-, one-, two-, and three-parameter overloads for both loops. Each public overload returns `ScheduledEventBase`.
```csharp
using Opsive.Shared.Game;
using UnityEngine;
public sealed class DelayedMarker : MonoBehaviour
{
private ScheduledEventBase m_MarkerEvent;
public void ShowLater(GameObject marker, Vector3 position, float delay)
{
CancelMarker();
m_MarkerEvent = Scheduler.Schedule(
delay, ShowMarker, marker, position);
}
private void ShowMarker(GameObject marker, Vector3 position)
{
m_MarkerEvent = null;
marker.transform.position = position;
marker.SetActive(true);
}
private void OnDisable()
{
CancelMarker();
}
private void CancelMarker()
{
if (m_MarkerEvent == null) {
return;
}
Scheduler.Cancel(m_MarkerEvent);
m_MarkerEvent = null;
}
}
```
The principal signatures are `Schedule(float, Action)`, `Schedule(float, Action, T)`, and the matching two- and three-parameter forms. `ScheduleFixed` provides the same shapes for FixedUpdate. `Cancel(ScheduledEventBase)` removes a still-active handle. `ScheduledEventBase.EndTime`, `Location`, and `Active` are readable, but only while the caller still owns that pending handle.
---
# Object Pool
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/object-pool/)
Reuse frequently spawned projectiles, impact effects, and temporary data instead of repeatedly allocating and destroying them. Pool an object only when its complete checkout, initialization, and return lifecycle has one clear owner.
## Choose the correct pool
The released Version 3 packages provide two separate pools:
| Object being reused | Pool | Lifecycle |
| --- | --- | --- |
| A `GameObject` or a `Component` on its root | `Opsive.Shared.Game.ObjectPool` | `Instantiate` -> initialize -> `Destroy` |
| An ordinary managed C# object | `Opsive.Shared.Utility.GenericObjectPool` | `Get` -> initialize -> `Return` |
`ObjectPool` is the public wrapper around `ObjectPoolBase`. UCC runtime code often calls `ObjectPoolBase` directly, but both names use the same Unity-object pool. Contrary to older versions of this page, `ObjectPool` does not pool an arbitrary `System.Object`; use `GenericObjectPool` for that case.
Do not add pooling only because an object exists briefly. Pooling is most useful for objects created often enough that instantiation, destruction, or garbage collection is measurable. Long-lived scene objects and objects with expensive, error-prone reset logic are usually clearer without a pool.
## Set up the GameObject pool
No registration call is required. The first `ObjectPool.Instantiate` for an original prefab creates its pool key and either reuses an available instance or lets Unity create the first clone.
For a predictable warm-up instead of a first-use allocation:
1. Create one scene GameObject for the pool and add the **Object Pool** component.
2. Add an entry to its preload list.
3. Assign the project prefab under **Preloaded Prefab** and set **Count** to the largest number that the controlled scenario normally needs at once.
4. Keep the source prefab active, save the scene, and enter Play Mode. At `Start`, the component creates that many instances and immediately returns them to the pool.
If the scene has no pool component, the first pool call finds an existing `ObjectPoolBase` or creates a GameObject named `ObjectPool`. Add the component deliberately when preload count, scene ownership, or teardown order matters.
Prefer a prefab asset as the original. A temporary scene object can technically be cloned, but its instance ID and lifetime become part of the pool key; unloading that scene can invalidate both the original and entries derived from it.
## Understand checkout and return
When a previously returned GameObject is checked out, the pool sets its world position and rotation, assigns the requested parent, activates it, and records the original that owns it. When it is returned, the pool deactivates it, reparents it under the pool component, and queues it for reuse.
Treat the root GameObject handed out by the pool as the unit of ownership:
- Return that same root, not one of its children.
- Do not call `UnityEngine.Object.Destroy` on a checked-out or inactive pooled instance.
- Do not return the object twice. Once returned, it is no longer recorded as checked out.
- Do not use `ObjectPool.Destroy` for an object created with Unity's `Instantiate`; Version 3 logs an error and leaves that object active.
- Let the system that checked out the object decide when it is finished. A projectile, an impact effect, and the effect's caller should not all try to return the same root.
The pool changes position, rotation, parent, and active state. It does not restore local scale, Rigidbody values, particles, trails, collider state, ignored collisions, event subscriptions, scheduled callbacks, or custom fields.
## Reset every reused instance
Design a pooled component as if its second use were the main test:
1. Put one-time reference lookup in `Awake`.
2. Put per-use values in an explicit method such as `Initialize`, `Launch`, or `Play` and call it after every checkout.
3. Clear transient visual and physics state before starting the new use. Reset local scale explicitly when gameplay can change it.
4. Cancel scheduled work and unregister external listeners before return. `OnDisable` is a useful final safeguard because `ObjectPool.Destroy` deactivates the root.
5. Make the return path idempotent in project code so two completion signals cannot return the same instance twice.
For managed objects, implement `IPoolable.Reset` when the object holds lists, delegates, Unity object references, or other mutable data. `GenericObjectPool.Return` calls `Reset` before storing an `IPoolable`; `Get` does not initialize the next use for you.
## Follow the built-in projectile lifecycle
The included UCC Projectile is already designed for pooling. A Shootable or Magic **Spawn Projectile** module checks the prefab out through `ObjectPoolBase`, positions it, and calls its initialization path. Initialization assigns a new ID, velocity, owner, and impact data; cancels an old destruction callback; restores the collider; clears the Trail Renderer; restarts the Particle System; and removes ignored-collider state left by the prior use.
On impact or at the configured **Lifespan**, `ProjectileBase` stops the current use and returns its root through `ObjectPoolBase.Destroy`. Configure the projectile and its owning module through the [Projectile workflow](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/projectile/). Do not add a second `Destroy` call to that built-in path.
Use the same ownership model for a custom impact effect: check out its root, clear and play the effect, then let its completion callback return that root. The API example below shows this pattern. An [Explosion](https://opsive.com/support/documentation/ultimate-character-controller/objects/explosions/) or [Magic Particle](https://opsive.com/support/documentation/ultimate-character-controller/objects/magic-particle/) may have additional damage, timing, or networking ownership; follow that component's documented lifecycle rather than returning it independently from the caller.
## Plan scene and teardown ownership
Inactive GameObject instances become children of the pool component, so they belong to the pool's scene. Keep the pool in the same long-lived scene as the systems that use it, or use a deliberately persistent owner for cross-scene effects. Before unloading an additive scene, stop its spawners, return its checked-out objects, and make sure the unload will not destroy originals or inactive entries owned by another scene's pool.
`ObjectPoolBase` resets its singleton reference during subsystem registration and after its scene unloads. `GenericObjectPool` has no public clear operation or subsystem-registration reset in the released Shared package. When **Enter Play Mode Options** disables domain reload, managed entries can therefore survive a Play Mode boundary. `IPoolable.Reset` must remove Unity references and prior-use state instead of assuming a fresh static pool.
The Shared runtime shipped with UCC 3.2.0 also expects every queued GameObject entry to remain valid: its queue reader retries a null first entry without removing that entry. Avoid allowing an additive-scene unload to destroy an inactive entry that belongs to a surviving pool.
For a supported multiplayer integration, use its `NetworkObjectPool` path for network-owned projectiles and destruction. Local `ObjectPool.Destroy` does not establish spawn authority, replication, save persistence, or ownership.
## Verify in Play Mode
1. Preload one instance and trigger the feature once. Confirm the object appears at the intended position and under the intended runtime parent.
2. Let it finish. Confirm it becomes inactive beneath the Object Pool and produces no pool, missing-reference, or uncancelled-callback error.
3. Trigger it again. In the Hierarchy, confirm the same instance is reactivated rather than another clone being created.
4. Change state during the first use, such as scale, particle playback, velocity, or a target reference. Confirm the second use begins from the expected clean state.
5. Trigger the maximum expected burst. Confirm the pool grows only to the number of simultaneously active instances and then reuses them.
6. If additive scenes or disabled domain reload are supported, repeat the test across that exact unload or Play Mode boundary.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| `Unable to pool ... the GameObject was not instantiated with ObjectPoolBase.Instantiate` appears. | The object came from Unity's `Instantiate`, the returned object is a child, or it was already returned. | Pair one Opsive checkout with one return and retain the checked-out root reference. Let the original owner use Unity's `Destroy` for a nonpooled object. |
| The second use retains velocity, particles, a trail, scale, a target, or a callback. | The component relies only on activation to reset state. | Reset every per-use value in an initialization method and clear scheduled work, listeners, and mutable state before return. |
| The first spawn causes a frame spike. | The scene has no explicit Object Pool preload, or **Count** is below the normal simultaneous demand. | Add the prefab under **Preloaded Prefab**, raise **Count** to the measured burst size, and profile again. |
| More clones appear on every use. | The completion path never calls `ObjectPool.Destroy`, uses Unity `Destroy`, or creates from a different original/secondary key. | Keep one original prefab reference and one Opsive return path. Verify the object becomes inactive below the pool after each use. |
| A managed object refers to data from its previous owner. | Its fields are not initialized after `Get`, or it does not clear references on `Return`. | Initialize after every `Get` and implement `IPoolable.Reset` to clear references and collections. Never return `null`. |
| Pooling stalls during or after additive-scene unload. | A surviving pool contains an inactive entry that Unity destroyed with another scene. | Keep pool and entries under one scene owner, return active instances before unload, and do not unload the scene that owns the source or inactive entry first. |
## Related pages
- [Programming Concepts](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/)
- [Projectile](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/projectile/)
- [Trajectory Object](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/)
- [Explosion](https://opsive.com/support/documentation/ultimate-character-controller/objects/explosions/)
- [Scheduler](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/scheduler/)
## API examples
### Reuse an impact effect
Set the Particle System's **Play On Awake** off and **Stop Action** to **Callback**. Keep this component on the prefab root so the object returned is the same root that was checked out.
```csharp
using Opsive.Shared.Game;
using UnityEngine;
public sealed class PooledImpactEffect : MonoBehaviour
{
[SerializeField] private ParticleSystem m_Particles;
public void Play()
{
m_Particles.Clear(true);
m_Particles.Play(true);
}
private void OnParticleSystemStopped()
{
ObjectPool.Destroy(gameObject);
}
}
```
Check out and initialize the effect at the impact point:
```csharp
using Opsive.Shared.Game;
using UnityEngine;
public sealed class ImpactEffectSpawner : MonoBehaviour
{
[SerializeField] private PooledImpactEffect m_EffectPrefab;
public void Spawn(RaycastHit hit)
{
var rotation = Quaternion.LookRotation(hit.normal);
var effect = ObjectPool.Instantiate(
m_EffectPrefab, hit.point, rotation);
effect.Play();
}
}
```
The generic `Component` overload returns the matching component from the checked-out root. The explicit position and rotation overload avoids the parent-only overloads' different transform rules.
### Reuse managed scratch data
`GenericObjectPool.Get()` creates a value with `Activator.CreateInstance()` when its stack is empty, so the type needs a usable parameterless constructor. Return the exact concrete type that was obtained.
```csharp
using System.Collections.Generic;
using Opsive.Shared.Utility;
using UnityEngine;
public sealed class HitScratchData : IPoolable
{
public Collider Target;
public readonly List Points = new List();
public void Reset()
{
Target = null;
Points.Clear();
}
}
public static class HitCollector
{
public static void Collect(Collider target, Vector3 point)
{
var data = GenericObjectPool.Get();
try {
data.Target = target;
data.Points.Add(point);
// Consume the data during this checkout.
} finally {
GenericObjectPool.Return(data);
}
}
}
```
The primary Version 3 GameObject overloads are `ObjectPool.Instantiate(GameObject, Vector3, Quaternion, Transform)`, `ObjectPool.Instantiate(T, Vector3, Quaternion, Transform)` for a `Component`, and `ObjectPool.Destroy(GameObject)`. `Destroy(UnityEngine.Object)` accepts a `Component` and returns its GameObject; it is not a managed-object return API. Its delayed overload schedules that same component-only path, so do not pass a `GameObject` to `Destroy(UnityEngine.Object, float)`. Use a stored [Scheduler](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/scheduler/) handle that eventually calls the `GameObject` overload when delayed return must be cancellable. `InstantiatedWithPool` and `GetOriginalObject` inspect only an instance that is currently checked out, not one that has already been returned.
---
# Artificial Intelligence (AI)
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/artificial-intelligence/)
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
1. Place the character model in the scene. Character Manager updates scene objects rather than editing a prefab asset directly.
2. Open **Tools > Opsive > Ultimate Character Controller > Character Manager**.
3. 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.
4. Enable **AI Agent**. This adds **Local Look Source** and removes **Ultimate Character Locomotion Handler**, **Item Handler**, and the Unity input component.
5. Enable **NavMeshAgent** only when this character will use Unity navigation. Character Manager adds **NavMeshAgent Movement** and its required Unity **NavMeshAgent** component.
6. 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.
7. Select **Build Character** for a new character or **Update Character** for an existing UCC character.
8. 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](https://opsive.com/support/documentation/behavior-designer/integrations/opsive-character-controllers/). 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.
## Configure Unity navigation
1. Build a NavMesh that contains the agent's starting position and every intended destination.
2. Select the character and expand **Abilities** in **Ultimate Character Locomotion**.
3. Select **NavMeshAgent Movement** and configure **Auto Enable**, **Rotation Override**, **Arrived Distance**, **Allow Movement In Air**, and any off-mesh link choices.
4. Have the behavior system assign a reachable destination.
5. 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](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/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](https://opsive.com/support/documentation/ultimate-character-controller/integrations/astar-pathfinding-project/). For another system, implement a Pathfinding Movement ability that exposes its desired input, rotation, destination, arrival, and teleport behavior.
## Verify in Play Mode
1. Start the scene without providing player input. Keyboard or controller input should not move the AI character.
2. 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.
3. Confirm the character stops within **Arrived Distance** and the controlling behavior advances only after arrival.
4. 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.
5. 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.
6. 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.
7. 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. |
## Related tasks
- [Create or update a character](https://opsive.com/support/documentation/ultimate-character-controller/character/character-creation/)
- [Configure NavMeshAgent Movement](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/navmeshagent-movement/)
- [Understand abilities and update order](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/)
- [Configure the Use item ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/use/)
- [Equip an item set](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/item-set/equip-unequip/)
- [Configure Health](https://opsive.com/support/documentation/ultimate-character-controller/attributes/health/)
- [Listen for UCC events](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/)
- [Configure the Animator](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/)
## 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.
```csharp
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();
var movement = locomotion.GetAbility();
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()`, 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` when the configured impact action invokes that event. Unregister the same callback when the receiving component is destroyed.
---
# Integrations
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/integrations/)
Integrations connect Ultimate Character Controller to input, camera, pathfinding, audio, vehicle, quest, inventory, and other Unity systems.
## Install an integration
Download the matching Version 3 bridge from [Opsive Downloads](https://opsive.com/downloads/), then import it after the third-party asset. Bridges are separate downloads and appear in the project only after import. Partner-maintained and legacy exceptions are identified on their integration pages.
Open **Tools > Opsive > Ultimate Character Controller > Integrations Manager** to review an installed entry and any version notice.
## Available integrations
| Integration | What it adds or changes |
| --- | --- |
| [A* Pathfinding Project](https://opsive.com/support/documentation/ultimate-character-controller/integrations/astar-pathfinding-project/)
[Asset Store](https://assetstore.unity.com/packages/tools/behavior-ai/a-pathfinding-project-pro-87744?aid=1100lGdc) | AI movement that follows paths produced by an A* agent. |
| [Adventure Creator](https://opsive.com/support/documentation/ultimate-character-controller/integrations/adventure-creator/)
[Asset Store](https://assetstore.unity.com/packages/tools/game-toolkits/adventure-creator-11896?aid=1100lGdc) | Adventure Creator character, motion, item, and interaction handoffs through its provider-maintained bridge. |
| [Atlas](https://opsive.com/support/documentation/ultimate-character-controller/integrations/atlas/)
[Atlas page](https://opsive.com/atlas/) | Ask, plan, generate, correct, review, and apply validated ability source inside Unity. |
| [Behavior Designer Pro](https://opsive.com/support/documentation/ultimate-character-controller/integrations/behavior-designer/)
[Asset Store](https://assetstore.unity.com/packages/tools/visual-scripting/behavior-designer-pro-dots-powered-behavior-trees-298743?aid=1100lGdc) | Behavior-tree tasks for abilities, effects, items, health, attributes, aim, State System state, and events. |
| [Cinemachine](https://opsive.com/support/documentation/ultimate-character-controller/integrations/cinemachine/)
[Package documentation](https://docs.unity3d.com/Packages/com.unity.cinemachine@latest) | Cinemachine-backed first-person and third-person View Types. |
| [Control Freak](https://opsive.com/support/documentation/ultimate-character-controller/integrations/control-freak/)
[Asset Store](https://assetstore.unity.com/packages/tools/input-management/control-freak-2-touch-input-made-easy-11562?aid=1100lGdc) | A Control Freak player-input provider and touch-control rig workflow. |
| [DestroyIt](https://opsive.com/support/documentation/ultimate-character-controller/integrations/destroyit/)
[Asset Store](https://assetstore.unity.com/packages/tools/physics/destroyit-destruction-system-18811?aid=1100lGdc) | A legacy compatibility note for existing owners; no current bridge is supplied. |
| [Dialogue System](https://opsive.com/support/documentation/ultimate-character-controller/integrations/dialogue-system/)
[Asset Store](https://assetstore.unity.com/packages/tools/behavior-ai/dialogue-system-for-unity-11672?aid=1100lGdc) | Pixel Crushers dialogue, quest, saver, and interaction handoffs. |
| [Easy Build System](https://opsive.com/support/documentation/ultimate-character-controller/integrations/easy-build-system/)
[Asset Store](https://assetstore.unity.com/packages/slug/45394?aid=1100lGdc) | A Building Ability that participates in the normal ability lifecycle. |
| [Easy Touch](https://opsive.com/support/documentation/ultimate-character-controller/integrations/easy-touch/)
[Asset Store](https://assetstore.unity.com/packages/tools/input-management/easy-touch-5-touchscreen-virtual-controls-3322?aid=1100lGdc) | A legacy input-replacement workflow for a deprecated asset. |
| [Edy's Vehicle Physics](https://opsive.com/support/documentation/ultimate-character-controller/integrations/edys-vehicle-physics/)
[Asset Store](https://assetstore.unity.com/packages/tools/physics/edy-s-vehicle-physics-403?aid=1100lGdc) | An EVP Drive Source for the Drive ability. |
| [Feel](https://opsive.com/support/documentation/ultimate-character-controller/integrations/feel/)
[Asset Store](https://assetstore.unity.com/packages/tools/particles-effects/feel-183370?aid=1100lGdc) | Feedback modules for character Effects and modular item actions. |
| [Final IK](https://opsive.com/support/documentation/ultimate-character-controller/integrations/final-ik/)
[Asset Store](https://assetstore.unity.com/packages/tools/animation/final-ik-14290?aid=1100lGdc) | A Final IK Bridge and selected RootMotion IK components. |
| [FMOD](https://opsive.com/support/documentation/ultimate-character-controller/integrations/fmod/)
[Asset Store](https://assetstore.unity.com/packages/tools/audio/fmod-for-unity-2-03-311497?aid=1100lGdc) | An FMOD Audio Manager module that preserves Audio Config workflows. |
| [FPS Mesh Tool](https://opsive.com/support/documentation/ultimate-character-controller/integrations/fps-mesh-tool/)
[Asset Store](https://assetstore.unity.com/packages/tools/modeling/fps-mesh-tool-28006?aid=1100lGdc) | A first-person-compatible mesh preparation workflow. |
| [High Definition Render Pipeline](https://opsive.com/support/documentation/ultimate-character-controller/integrations/high-definition-render-pipeline/)
[Package documentation](https://docs.unity3d.com/Packages/com.unity.render-pipelines.high-definition@latest) | Overlay Pass, material, shadow, and Object Fader support. |
| [Horse Animset Pro](https://opsive.com/support/documentation/ultimate-character-controller/integrations/horse-animset-pro/)
[Asset Store](https://assetstore.unity.com/packages/3d/characters/animals/horse-animset-pro-riding-system-79902?aid=1100lGdc) | A Malbers-maintained riding and camera handoff. |
| [InControl](https://opsive.com/support/documentation/ultimate-character-controller/integrations/incontrol/)
[Asset Store](https://assetstore.unity.com/packages/tools/input-management/incontrol-14695?aid=1100lGdc) | An InControl player-input provider. |
| [Input System](https://opsive.com/support/documentation/ultimate-character-controller/integrations/input-system/)
[Package documentation](https://docs.unity3d.com/Packages/com.unity.inputsystem@latest) | A legacy child page; use the current [Input](https://opsive.com/support/documentation/ultimate-character-controller/input/) workflow. |
| [Juicy Actions](https://opsive.com/support/documentation/ultimate-character-controller/integrations/juicy-actions/)
[Asset Store](https://assetstore.unity.com/packages/slug/269711?aid=1100lGdc) | Character Actions, event triggers, Blackboard helpers, Conditions, and extension points. |
| [Love/Hate](https://opsive.com/support/documentation/ultimate-character-controller/integrations/love-hate/)
[Asset Store](https://assetstore.unity.com/packages/tools/ai/love-hate-33063?aid=1100lGdc) | A Pixel Crushers combat-deed compatibility route. |
| [Master Audio](https://opsive.com/support/documentation/ultimate-character-controller/integrations/master-audio/)
[Asset Store](https://assetstore.unity.com/packages/tools/audio/master-audio-2022-aaa-sound-212962?aid=1100lGdc) | Master Audio Sound Groups and Variations for character audio. |
| [NWH Vehicle Physics](https://opsive.com/support/documentation/ultimate-character-controller/integrations/nwh-vehicle-physics/)
[Asset Store](https://assetstore.unity.com/packages/tools/physics/nwh-vehicle-physics-2-166252?aid=1100lGdc) | An NWH Drive Source and camera handoff. |
| [Omni Animation Packs](https://opsive.com/support/documentation/ultimate-character-controller/integrations/omni-animation-packs/) | [Core Locomotion](https://assetstore.unity.com/packages/3d/animations/omni-animation-core-locomotion-pack-286945?aid=1100lGdc), [Knife](https://assetstore.unity.com/packages/3d/animations/omni-animation-knife-pack-277864?aid=1100lGdc), or [Pistol](https://assetstore.unity.com/packages/3d/animations/omni-animation-pistol-pack-276060?aid=1100lGdc). Animation Replacer templates rather than a runtime bridge. |
| [PlayMaker](https://opsive.com/support/documentation/ultimate-character-controller/integrations/playmaker/)
[Asset Store](https://assetstore.unity.com/packages/tools/visual-scripting/playmaker-368?aid=1100lGdc) | PlayMaker 1 actions for supported character operations. |
| [PuppetMaster](https://opsive.com/support/documentation/ultimate-character-controller/integrations/puppetmaster/)
[Asset Store](https://assetstore.unity.com/packages/tools/physics/puppetmaster-48977?aid=1100lGdc) | A historical physical-animation bridge with a pinned compatibility boundary. |
| [Quest Machine](https://opsive.com/support/documentation/ultimate-character-controller/integrations/quest-machine/)
[Asset Store](https://assetstore.unity.com/packages/tools/game-toolkits/quest-machine-39834?aid=1100lGdc) | Pixel Crushers quest, interaction, inventory, and attribute handoffs. |
| [RayFire](https://opsive.com/support/documentation/ultimate-character-controller/integrations/rayfire/)
[Asset Store](https://assetstore.unity.com/packages/tools/game-toolkits/rayfire-2-342492?aid=1100lGdc) | A legacy-bridge evaluation route for destructible objects. |
| [Realistic Car Controller](https://opsive.com/support/documentation/ultimate-character-controller/integrations/realistic-car-controller/)
[Asset Store](https://assetstore.unity.com/packages/tools/physics/realistic-car-controller-16296?aid=1100lGdc) | An RCC Drive Source with a version-specific compile boundary. |
| [Realistic Car Controller Pro](https://opsive.com/support/documentation/ultimate-character-controller/integrations/realistic-car-controller-pro/)
[Asset Store](https://assetstore.unity.com/packages/tools/physics/realistic-car-controller-pro-178967?aid=1100lGdc) | An RCC Pro Drive Source with a version-specific compile boundary. |
| [Rewired](https://opsive.com/support/documentation/ultimate-character-controller/integrations/rewired/)
[Asset Store](https://assetstore.unity.com/packages/tools/utilities/rewired-21676?aid=1100lGdc) | A Rewired player-input provider and player assignment. |
| [State Designer](https://opsive.com/support/documentation/ultimate-character-controller/integrations/state-designer/)
[Asset Store](https://assetstore.unity.com/packages/tools/visual-scripting/state-designer-dots-powered-finite-state-machines-369152?aid=1100lGdc) | State Actions and Conditions for supported character operations. |
| [Ultimate Inventory System](https://opsive.com/support/documentation/ultimate-character-controller/integrations/ultimate-inventory-system/)
[Asset Store](https://assetstore.unity.com/packages/tools/game-toolkits/ultimate-inventory-system-166053?aid=1100lGdc) | Inventory, item-definition, item-collection, item-set, interface, and save integration. |
| [UMA](https://opsive.com/support/documentation/ultimate-character-controller/integrations/uma/)
[Asset Store](https://assetstore.unity.com/packages/tools/uma-2-unity-multipurpose-avatar-35611?aid=1100lGdc) | Editor-built or runtime-generated avatar construction. |
| [Universal Render Pipeline](https://opsive.com/support/documentation/ultimate-character-controller/integrations/universal-render-pipeline/)
[Package documentation](https://docs.unity3d.com/Packages/com.unity.render-pipelines.universal@latest) | Overlay rendering, camera, material, post-processing, and build support. |
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| The integration is not listed under **Integration Inspectors**. | The integration may not implement a custom inspector, or compilation may have failed. | Check **Available Integrations**, the expected bridge component, and the Console. Do not use the inspector tab alone as the installation test. |
| One input controls two characters or an action fires twice. | More than one input implementation is active, or two Player Input Proxies reference the same provider. | Give each player one provider and point each **Player Input Proxy** to its own component. Remove the competing input route from the test. |
| A vehicle can be entered but does not move. | The vehicle's own setup, matching Drive Source, or Drive ability references are incomplete. | Verify the vehicle without Ultimate Character Controller, add the exact Drive Source named by its page, then repeat the Drive ability setup. |
| First-person objects clip or render pink in URP or HDRP. | The active render pipeline and imported Ultimate Character Controller support package do not match, or **Overlay Render Type** is not configured. | Import the matching support package from **Setup Manager > Project**, complete its overlay setup, and select **Render Pipeline** on the first-person View Type. |
## Related pages
- [Input](https://opsive.com/support/documentation/ultimate-character-controller/input/)
- [Artificial Intelligence](https://opsive.com/support/documentation/ultimate-character-controller/artificial-intelligence/)
- [Camera](https://opsive.com/support/documentation/ultimate-character-controller/camera/)
- [Animation](https://opsive.com/support/documentation/ultimate-character-controller/animation/)
- [Drive](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/detect-object-ability-base/drive/)
- [Item Actions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/)
- [Quick Setup](https://opsive.com/support/documentation/ultimate-character-controller/getting-started/quick-setup/)
## Developer reference
The Version 3 Integrations Manager discovers loaded `IntegrationInspector` implementations separately from its online **Available Integrations** list. A downloaded bridge is not required to provide a custom inspector.
Prefer the extension point owned by the subsystem instead of calling a third-party singleton throughout gameplay code. Current integrations demonstrate the intended boundaries: input providers implement `Opsive.Shared.Input.IPlayerInput` and are assigned through `PlayerInputProxy`; vehicle adapters implement `IDriveSource`; external cameras use Ultimate Character Controller View Types; audio backends use an Audio Manager module; and item, effect, ability, or behavior integrations add modules and abilities at the existing Ultimate Character Controller extension points.
---
# A* Pathfinding Project
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/integrations/astar-pathfinding-project/)
Use the [A* Pathfinding Project](https://assetstore.unity.com/packages/tools/behavior-ai/a-pathfinding-project-pro-87744?aid=1100lGdc) 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](https://opsive.com/downloads/). 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](https://arongranberg.com/astar/documentation/stable/getstarted.html) 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. |
## Related pages
- [Integrations](https://opsive.com/support/documentation/ultimate-character-controller/integrations/)
- [Artificial Intelligence](https://opsive.com/support/documentation/ultimate-character-controller/artificial-intelligence/)
- [Create or update a character](https://opsive.com/support/documentation/ultimate-character-controller/character/character-creation/)
- [NavMeshAgent Movement](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/navmeshagent-movement/)
- [Move Towards](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/move-towards/)
- [Abilities](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/)
## 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.
---
# Adventure Creator
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/integrations/adventure-creator/)
Use the [Adventure Creator](https://assetstore.unity.com/packages/tools/game-toolkits/adventure-creator-11896?aid=1100lGdc) integration when Ultimate Character Controller should handle character movement and items while Adventure Creator coordinates cutscenes, cameras, interactions, and its inventory interface.
## Before you begin
- Install Adventure Creator and Ultimate Character Controller Version 3.
- Confirm that the Ultimate Character Controller character and camera work in Play Mode before adding the bridge.
- Download **Integration: UCC** from the official Adventure Creator [downloads page](https://adventurecreator.org/downloads), then import the package. Adventure Creator maintains and distributes this bridge separately from Ultimate Character Controller.
- Keep the Ultimate Character Controller player in the scene. The supplied setup does not support spawning that player through Adventure Creator's Settings Manager.
When upgrading Adventure Creator or Ultimate Character Controller, test the integration in a copy of the project before updating production scenes.
## Try the supplied demo
The package includes a small scene that confirms the two products can communicate before you change your own character.
1. In the Project window, double-click the `AC_UCC_ManagerPackage` asset to assign the demo's Adventure Creator Managers.
2. Open the `AC_UCC_Demo` scene.
3. Enter Play Mode and try its triggers, cutscenes, cameras, and inventory interactions.
Use your own Managers again before returning to a production scene.
## Connect the player
1. Set up the scene with a working Ultimate Character Controller player and Ultimate Character Controller main camera.
2. Select the player and add Adventure Creator's **Player** component.
3. On **Player**, set **Animation engine** to **Mecanim**, then clear every Mecanim parameter text field. Ultimate Character Controller continues to drive the Animator.
4. Add **AC_UCC_Character** to the same GameObject.
5. Drag the character's Ultimate Character Controller **Player Input** component into **Player Input** on **AC_UCC_Character**.
6. On **Ultimate Character Locomotion**, add **AC Motion** to the **Abilities** list and set its **Start Type** to **Manual**.
7. In Adventure Creator's Settings Manager, set **Movement method** to **First Person** or **Direct**.
8. On the Ultimate Character Controller **Camera Controller**, assign the scene player to **Character**.
In normal gameplay, Ultimate Character Controller accepts player input. During an Adventure Creator cutscene or another non-gameplay state, the bridge starts **AC Motion** so the character follows Adventure Creator's target position and rotation.
## Choose how the camera is controlled
### Use the Ultimate Character Controller camera for the whole scene
Add Adventure Creator's **MainCamera** component to the Ultimate Character Controller main camera. This is the simplest setup when no Adventure Creator camera should replace it.
### Switch between Ultimate Character Controller and Adventure Creator cameras
1. Rename the Ultimate Character Controller camera GameObject to `UCC MainCamera`.
2. Remove its **MainCamera** tag and add Adventure Creator's **Basic Camera** component.
3. Create a separate GameObject with a Unity **Camera** and Adventure Creator **MainCamera** component.
4. Remove the **Overlay** layer from that Camera's **Culling Mask**, then tag the GameObject **MainCamera**.
5. In Adventure Creator's Scene Manager, assign `UCC MainCamera` to **Default camera**.
6. If **Movement method** is **First Person**, use a **Camera: Switch** Action in the scene's **OnStart** cutscene to select the starting camera.
On **AC_UCC_Character**, leave **Sync Camera And Cursor Lock** enabled when Adventure Creator should suspend Ultimate Character Controller look input while a cursor, free-aim lock, or camera drag is active. Enable **Control Camera During Cutscenes** only when the player should still be able to look around during a cutscene.
## Synchronize inventory items
Use this setup when an item picked up or equipped through Ultimate Character Controller should also appear or become selected in Adventure Creator's inventory.
1. In Adventure Creator's Inventory Manager, create the corresponding inventory item and note the ID shown to the left of its name.
2. Select the Ultimate Character Controller item prefab and add **AC_UCC_Item**.
3. Enter the Adventure Creator item ID in **Linked AC Item ID**.
4. Repeat the mapping for each item that the two systems should share.
The supplied component synchronizes in one direction: Ultimate Character Controller pickup, equip, unequip, and drop events add, select, clear, or remove the linked Adventure Creator item. Changing the Adventure Creator inventory directly does not create, equip, or drop the Ultimate Character Controller item.
## Run an ActionList from an Ultimate Character Controller interaction
1. Create the Adventure Creator Cutscene or ActionList asset that should run.
2. Add an Ultimate Character Controller **Interactable** to the scene object, then create an empty child GameObject.
3. Add **AC_UCC_Button** to the child.
4. Assign either **Action List On Interact** for a scene ActionList or **Action List Asset On Interact** for an ActionList asset. Assign both only when both lists should run.
5. On the parent **Interactable**, add the **AC_UCC_Button** component to **Targets**.
6. Leave **Is Interactive** enabled while the interaction should be available.
The button accepts interaction only during Adventure Creator gameplay and while its assigned ActionList is not already running.
To use Adventure Creator's **Inventory: Check selected** Action with an equipped Ultimate Character Controller item, first map that item with **AC_UCC_Item**. On the player's **Ultimate Character Locomotion** component, expand **General** and **Allow Equipped Items**, then enable every **Slot** that the Interact ability may keep equipped.
## Verify in Play Mode
1. During normal gameplay, move and look with the usual Ultimate Character Controller input. The character should respond normally.
2. Start an Adventure Creator cutscene that moves the player. Direct Ultimate Character Controller movement should pause and **AC Motion** should follow the Adventure Creator target.
3. End the cutscene. Ultimate Character Controller movement and camera input should return.
4. If the scene switches cameras, confirm that Adventure Creator shows its camera and returns cleanly to `UCC MainCamera`.
5. Pick up, equip, unequip, and drop a mapped Ultimate Character Controller item. Adventure Creator's runtime inventory should add, select, clear, and remove the matching item.
6. Use the Ultimate Character Controller Interact ability on the configured object. The assigned Adventure Creator ActionList should run once.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| The player does not move during a cutscene | **AC Motion** is missing or its **Start Type** is not **Manual** | Add **AC Motion** to **Ultimate Character Locomotion** and select **Manual**. |
| Input remains disabled after a cutscene | **Player Input** is unassigned, or the Adventure Creator player is not the active player | Assign the Ultimate Character Controller **Player Input** component on **AC_UCC_Character** and confirm the correct Adventure Creator **Player** is active. |
| The wrong camera renders, or camera switching fails | More than one camera has the **MainCamera** tag, or **Default camera** points to the wrong object | Keep the tag on the separate Adventure Creator MainCamera only and assign `UCC MainCamera` as the Scene Manager's **Default camera**. |
| An Ultimate Character Controller item does not appear in Adventure Creator | **Linked AC Item ID** does not match the ID in the Inventory Manager | Correct the ID on the item's **AC_UCC_Item** component and test a new pickup. |
| The interaction never starts | **AC_UCC_Button** is absent from **Targets**, **Is Interactive** is disabled, or the ActionList is already running | Add the button to **Targets**, enable it, and wait for the existing ActionList to finish. |
| Scene changes produce `MultiSceneChecker` warnings | Adventure Creator and Ultimate Character Controller scene checks run in the wrong order | In Unity's **Script Execution Order**, give `AC.MultiSceneChecker` a higher value than Ultimate Character Controller's checker. |
## Related pages
- [Integrations](https://opsive.com/support/documentation/ultimate-character-controller/integrations/)
- [Input](https://opsive.com/support/documentation/ultimate-character-controller/input/)
- [Camera](https://opsive.com/support/documentation/ultimate-character-controller/camera/)
- [Abilities](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/)
- [Interact ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/detect-object-ability-base/interact/)
- [Items and Inventory](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/)
## Developer reference
The partner package adds four bridge types:
- `AC_UCC_Character` coordinates Adventure Creator game-state changes with Ultimate Character Controller locomotion, camera input, cursor locking, and the `AC_Motion` ability.
- `AC_Motion` derives from Ultimate Character Controller's `PathfindingMovement` and reads Adventure Creator's target position, target rotation, and running state.
- `AC_UCC_Item` listens to the Ultimate Character Controller `CharacterItem` pickup, equip, unequip, and drop events and updates Adventure Creator's runtime inventory.
- `AC_UCC_Button` implements Ultimate Character Controller's `IInteractableTarget`. It can run a scene ActionList, an ActionList asset, or both, and exposes `IsInteractive` for runtime control.
Because these scripts depend on both products' runtime APIs, keep local changes to the bridge isolated and recheck them whenever either product is upgraded.
---
# Atlas
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/integrations/atlas/)
Atlas is the Opsive assistant for asking Ultimate Character Controller questions, planning an ability, and generating validated Version 3 Ability, Item Ability, Ability Starter, or Ability Stopper source inside Unity. Generated files remain previews until you explicitly apply them.
## Install and connect Atlas
Atlas requires **Ultimate Character Controller 3.3.7 or newer**.
1. Confirm the installed Ultimate Character Controller version is 3.3.7 or newer.
2. Download Atlas from the [Atlas page](https://opsive.com/atlas/) and import it into the released Ultimate Character Controller Version 3 project. Atlas is not available from the Opsive Downloads page.
3. Install the Codex desktop app or standalone Codex CLI on Windows or macOS and sign in with the subscription Atlas should use.
4. Open **Tools > Opsive > Ultimate Character Controller > Atlas**.
5. Select **Sign in**. The one-time browser page checks the current Opsive account for Ultimate Character Controller. Enter the Unity invoice only if the purchase is not already linked.
6. Return to Unity and select **Ultimate Character Controller** as the active Opsive asset.
No Atlas token or Codex credential is copied into Unity. Codex authentication remains on the local machine.
## Choose the generated type
- **Ability** is a character-wide behavior managed by Ultimate Character Locomotion.
- **Item Ability** coordinates equipped Character Items and their actions through the item-ability lifecycle.
- **Ability Starter** encapsulates a custom rule that requests an ability start.
- **Ability Stopper** encapsulates a custom rule that requests an ability stop.
- **Ask** and **Plan** can explain or design a solution without generating a file. Prefer a built-in ability or existing component when it already provides the complete behavior.
Atlas validates Ultimate Character Controller base classes, field structure, and lifecycle shape, but the project still owns gameplay correctness, animation, networking authority, save behavior, and compatibility with other active abilities.
## Generate a first ability
1. Create a source-control checkpoint and a duplicate test character.
2. Describe one observable responsibility and its start/stop rules. Include whether it is concurrent, whether it needs input, and which active abilities should block or stop it.
3. Ask Atlas to plan first when the behavior requires movement, Animator parameters, items, States, or several files.
4. Review the generated base type, serialized fields, `CanStartAbility`, `AbilityStarted`, update method, `AbilityStopped`, and destruction cleanup.
5. Select **Apply _FileName_.cs**, **Save as...**, **Copy**, or **Discard**. Use **Apply all** only after reviewing every file in a completed package build.
6. Let Unity compile. Send the exact compiler diagnostic through Atlas correction when required.
7. Add the ability to the duplicate character and configure its Start Type, Stop Type, State, Animator index, and other inherited settings through the normal Ultimate Character Controller Inspector.
Atlas does not add the new ability to every prefab automatically. Apply reviewed source first, then use the normal Character Manager or Ultimate Character Locomotion workflow to configure each intended character.
## Understand the visible controls
- **Active Opsive asset** selects Ultimate Character Controller when several supported Opsive products are installed.
- **Model** and **Effort** show the current provider choices.
- **New chat**, tabs, and **All chats** keep unrelated abilities separate.
- **Show work** expands request progress without changing project files.
- **Apply**, **Save as...**, **Copy**, **Discard**, and **Apply all** control generated files.
- **Retry request** and **Resume package build** recover supported interrupted work.
- The **Atlas** menu under **Tools > Opsive > Ultimate Character Controller** contains **Verbose Diagnostics**, which is intended for support investigation.
Atlas sends a bounded relevant API summary and explicitly included project files, not the entire project. Review the current provider and privacy explanation on the [Atlas page](https://opsive.com/atlas/).
## Verify the generated ability
1. Enter Play Mode with the duplicate character and confirm the ability starts only under its documented conditions.
2. Verify position, rotation, Animator parameters, States, camera, items, and input have one intended owner.
3. Start a higher-priority or blocking ability and confirm the new ability obeys the intended concurrency rules.
4. Stop, interrupt, disable, die, respawn, and switch perspective where those flows apply. Confirm callbacks, events, scheduled actions, and temporary States are cleaned up.
5. Test a network-authoritative build separately when the ability changes shared gameplay state; generated local behavior does not create replication automatically.
6. Commit the reviewed source and character configuration normally.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| Ultimate Character Controller is unavailable in the asset selector. | Confirm the released Ultimate Character Controller Version 3 package and ability base types compiled. | Resolve the first Console error and reopen Atlas. Do not use a Version 4 development checkout for this documentation. |
| The browser cannot verify Ultimate Character Controller ownership. | Check the signed-in Opsive account and linked Unity invoice. | Use the owning account or enter the matching invoice on the connection page. |
| The ability compiles but never starts. | Check Start Type, input, `CanStartAbility`, ability order, blocking abilities, and required components. | Configure the inherited ability settings and inspect active abilities before changing generated code. |
| The character keeps a State or motion after stopping. | Check every resource acquired in start/update and the matching cleanup in stop/destruction. | Return the reproducible case for correction or repair the reviewed source before using it in a project. |
| The ability fights movement, camera, or an item action. | Check ownership and concurrency. | Let one system own each output and use Ultimate Character Controller's ability coordination methods rather than writing competing Transform or Animator values. |
| The ability works locally but not over the network. | Check authority and integration-specific replication. | Add explicit authoritative execution and synchronization through the chosen networking integration. |
## Related pages
- [Integrations](https://opsive.com/support/documentation/ultimate-character-controller/integrations/)
- [Abilities](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/)
- [Item Abilities](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/)
- [Ability Starter](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/ability-starter/)
- [Creating a New Ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/new-ability/)
- [States](https://opsive.com/support/documentation/ultimate-character-controller/state-system/)
- [Events](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/)
---
# Behavior Designer Pro
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/integrations/behavior-designer/)
Use the [Behavior Designer Pro](https://assetstore.unity.com/packages/tools/visual-scripting/behavior-designer-pro-dots-powered-behavior-trees-298743?aid=1100lGdc) 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](https://opsive.com/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](https://opsive.com/support/documentation/behavior-designer-pro/concepts/common-behaviors/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. |
## Related pages
- [Behavior Designer Pro](https://opsive.com/support/documentation/behavior-designer-pro/)
- [Choose and configure Behavior Designer tasks](https://opsive.com/support/documentation/behavior-designer-pro/concepts/tasks/)
- [Patrol and chase an enemy](https://opsive.com/support/documentation/behavior-designer-pro/concepts/common-behaviors/patrol-and-chase-an-enemy/)
- [Artificial Intelligence](https://opsive.com/support/documentation/ultimate-character-controller/artificial-intelligence/)
- [Create or update a character](https://opsive.com/support/documentation/ultimate-character-controller/character/character-creation/)
- [NavMeshAgent Movement](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/navmeshagent-movement/)
- [Abilities](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/)
- [Configure the Use item ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/use/)
- [Health](https://opsive.com/support/documentation/ultimate-character-controller/attributes/health/)
- [Events](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/)
- [Integrations](https://opsive.com/support/documentation/ultimate-character-controller/integrations/)
## 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.
---
# Cinemachine
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/integrations/cinemachine/)
Use the Cinemachine integration when Cinemachine should frame and compose the shot while Ultimate Character Controller continues to assign the character, select the gameplay View Type, provide the look direction, and coordinate character and item states.
## Before you begin
- Start with a working Ultimate Character Controller Version 3 character and **Camera Controller**. Verify the ordinary Ultimate Character Controller camera before replacing its active View Type.
- Install Cinemachine 3.1 or later from Unity's Package Manager, not the legacy Asset Store package. The released bridge uses the Cinemachine 3 `Unity.Cinemachine` API and names such as **Cinemachine Camera**, **Orbital Follow**, **Pan Tilt**, and **Rotation Composer**. See Unity's [Cinemachine 3.1 installation guide](https://docs.unity.cn/Packages/com.unity.cinemachine@3.1/manual/InstallationAndUpgrade.html).
- Decide whether the game needs first person, third person, or both. A dual-perspective camera needs a separate Cinemachine Camera and Ultimate Character Controller Cinemachine View Type for each perspective.
- Keep one owner for each job: Cinemachine composes the shot, the Ultimate Character Controller Camera Controller owns the active gameplay View Type, and Ultimate Character Locomotion owns the character.
## Install the integration
1. Open **Window > Package Manager**, install **Cinemachine**, and confirm that its installed version is 3.1 or later.
2. Open **Tools > Opsive > Ultimate Character Controller > Integrations Manager**, select **Available Integrations**, and use the **Integration** action for Cinemachine to obtain the current Ultimate Character Controller Version 3 package.
3. Import the Cinemachine integration package and allow Unity to compile. Keep its scripts in the supplied location unless the project deliberately organizes integrations under a custom assembly definition.
4. Select the camera with **Camera Controller**, expand **View Types**, and confirm that **First Person Cinemachine** and/or **Third Person Cinemachine** is available from the add menu.
Resolve compilation errors before configuring the scene. A missing `Unity.Cinemachine` namespace normally means Cinemachine is absent, is an incompatible major version, or is not referenced by a custom assembly definition that contains the integration scripts.
## Connect a Cinemachine Camera
1. Select the Unity Camera GameObject that contains **Camera Controller**. Add **Cinemachine Brain** to this same GameObject. Creating the first Cinemachine Camera may add the Brain automatically, but the bridge specifically looks for it beside Camera Controller.
2. Select **GameObject > Cinemachine > Cinemachine Camera** to create a separate Cinemachine Camera GameObject.
3. On its **Cinemachine Camera** component, assign the **Tracking Target** and choose the perspective-specific **Position Control** and **Rotation Control** described below.
4. From **Add Extension**, add **Cinemachine Camera Offset**. On the resulting component, set **Apply After** to **Noise**. The bridge uses this extension for its configured camera offset, positional springs, and first-person height adjustment.
5. Return to **Camera Controller > View Types**, use the add control, and select **First Person Cinemachine** or **Third Person Cinemachine**.
6. Select the new View Type and assign the Cinemachine Camera GameObject's **Cinemachine Camera** component to **Cinemachine Camera**.
7. In the **Active** column, select the Cinemachine View Type that should start active.
8. For a camera that can change perspective, repeat the process with a second Cinemachine Camera and the other Cinemachine View Type. Set **First Person View Type**, **Third Person View Type**, and **Can Change Perspectives** on Camera Controller.
Do not assign one Cinemachine Camera to both View Types. The integration changes its priority and activates or deactivates its GameObject when the Ultimate Character Controller View Type changes.
## Configure first person
Use a stable head or eye-level Transform as the tracking target:
1. On **Cinemachine Camera**, set **Tracking Target** to the character's head.
2. Set **Position Control** to **Orbital Follow** and **Rotation Control** to **Pan Tilt**.
3. On **Cinemachine Orbital Follow**, begin with **Target Offset** `(0, 0, 0)`, **Binding Mode** set to **World Space**, **Position Damping** `(0, 0, 0)`, **Orbit Style** set to **Sphere**, and **Radius** `0`.
4. On **Cinemachine Camera Offset**, begin with **Offset** `(0, 0, 0)` and **Apply After** set to **Noise**.
5. On **First Person Cinemachine**, preserve the Ultimate Character Controller first-person **Culling Mask**, **Overlay Render Type**, **First Person Camera**, and **First Person Culling Mask** required by the active render pipeline. Tune **Min Pitch Limit**, **Max Pitch Limit**, and the bob settings for the intended feel.
The head target establishes the camera position, but the Ultimate Character Controller View Type still supplies gameplay pitch, yaw, look direction, field of view, recoil, and first-person overlay behavior. Test animated head movement carefully; an unstable target can make the view shake even when all damping values are zero.
## Configure third person
Use the character root or another stable character-relative target:
1. On **Cinemachine Camera**, set **Tracking Target** to the character.
2. Set **Position Control** to **Orbital Follow** and **Rotation Control** to **Rotation Composer**.
3. On **Cinemachine Orbital Follow**, begin with **Target Offset** `(0, 0, 0)`, **Binding Mode** set to **World Space**, **Position Damping** `(1, 1, 1)`, **Orbit Style** set to **Sphere**, and **Radius** `4`.
4. On **Cinemachine Rotation Composer**, begin with **Target Offset** `(0, 1.81, 0)` and tune it for the character's actual height and desired framing.
5. On **Cinemachine Camera Offset**, begin with **Offset** `(0, 0, 0)` and **Apply After** set to **Noise**.
These values are a starting composition, not a character-size requirement. Tune the orbit radius, damping, and target offset with the actual model, movement speed, field of view, and gameplay spaces. The integration does not add obstruction avoidance; add and configure Cinemachine's **Deoccluder** or another supported collision extension when walls can enter the shot.
## How camera ownership works
| System | Responsibility |
| --- | --- |
| **Camera Controller** | Attaches the character, receives Ultimate Character Controller look input, selects the active View Type, exposes the gameplay look source, and coordinates zoom, states, and perspective changes. |
| **First Person Cinemachine** or **Third Person Cinemachine** | Connects the active Ultimate Character Controller View Type to one Cinemachine Camera and translates field of view, look direction, offsets, springs, character up, and runtime activation. |
| **Cinemachine Camera** | Tracks the selected target and applies its Position Control, Rotation Control, Noise, and extensions. |
| **Cinemachine Brain** | Chooses the live Cinemachine Camera and applies its result to the Unity Camera. The integration changes the assigned camera's priority when the Ultimate Character Controller View Type activates. |
| **Ultimate Character Locomotion and Perspective Monitor** | Move the character and update first-person or third-person model presentation after the perspective changes. |
At runtime the integration puts Cinemachine Brain into a manual update route coordinated with Ultimate Character Controller's Simulation Manager. It also updates the Brain's world-up override from the character's current up direction, which allows the shot to follow Ultimate Character Controller dynamic gravity instead of assuming global Y is always up.
When Camera Controller changes perspective, it deactivates the outgoing Cinemachine View Type and activates the selected default for the new perspective. **First Person Cinemachine** also updates the first-person overlay camera and culling mask in response to the perspective event. Configure the Ultimate Character Controller [Transition View Type](https://opsive.com/support/documentation/ultimate-character-controller/camera/view-types/included-view-types/transition/) or the Cinemachine Brain blend deliberately; avoid applying a long blend in both systems until each handoff works on its own.
## Key choices
- **Cinemachine Camera:** this is the required camera assigned to the Ultimate Character Controller View Type. “Virtual Camera” is the Cinemachine 2 name and is not the current field label.
- **Field Of View** and **Field Of View Damping:** Ultimate Character Controller writes the active View Type's field of view into the Cinemachine Camera lens. Camera states such as Aim can therefore change the lens without bypassing Cinemachine.
- **Look Direction Distance:** controls how far forward the gameplay look direction extends.
- **Use Character Look Direction:** enable this when abilities and items should use the character's forward direction. Leave it disabled when the Cinemachine Camera and crosshairs should define the look direction.
- **Camera Offset:** requires **Cinemachine Camera Offset**. The bridge warns when a nonzero offset is requested without that extension.
- **Position Spring**, **Rotation Spring**, and their secondary springs: preserve Ultimate Character Controller camera forces such as recoil and impacts. Add the integration's **Cinemachine Spring Extension** when Cinemachine orientation should receive rotational spring corrections.
- **First-person overlay:** choose the same **Overlay Render Type** and camera-layer setup used by the rest of the Ultimate Character Controller first-person camera workflow. Cinemachine does not replace the render-pipeline overlay configuration.
- **Obstruction and bounds:** use Cinemachine extensions such as **Deoccluder** or **Confiner**. The Cinemachine View Types do not inherit the included Ultimate Character Controller third-person collision fields.
- **Split screen:** each Camera Controller needs its own Cinemachine Brain and Cinemachine Cameras. Assign distinct Cinemachine output channels so one player's Brain does not select another player's shot.
- **Timeline:** Timeline can override Cinemachine's normal priority and activation rules. Do not let Timeline and Ultimate Character Controller compete for the same gameplay Cinemachine Camera; make the ownership handoff explicit and verify the return to gameplay.
## Verify in Play Mode
1. Enter Play Mode and confirm the Console has no missing **Cinemachine Brain** or **Cinemachine Camera** error.
2. Inspect the assigned Cinemachine Camera. It should report **Live**, and the Ultimate Character Controller Cinemachine View Type should be selected as active on Camera Controller.
3. Move horizontal and vertical look input. Confirm the shot responds as intended and the character or item uses the same gameplay look direction.
4. Walk, turn, jump, aim, use an item, and apply a camera force. Framing, field of view, first-person overlays, and spring motion should remain synchronized.
5. For third person, walk behind walls and through narrow spaces. Confirm the configured Cinemachine collision or occlusion extension keeps the target visible without clipping.
6. For both perspectives, switch in both directions while standing, moving, aiming, and holding an item. The correct Cinemachine Camera should become Live, the outgoing one should deactivate, and model visibility should match the perspective.
7. Test a slope or dynamic-gravity surface when the game uses nonstandard up directions. The Brain's world up should follow the Ultimate Character Controller character.
8. Test respawn, teleport, pause, and scene loading. If Timeline or another cinematic camera takes control, confirm the Ultimate Character Controller gameplay View Type becomes Live again afterward.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| Unity reports that `Unity.Cinemachine` or a Cinemachine type is missing | Cinemachine may be absent, older than 3.1, or excluded from a custom assembly definition that contains the integration scripts | Install Cinemachine 3.1 or later from Package Manager. If the scripts were moved under an assembly definition, add **Unity.Cinemachine** and the required Opsive assemblies to that assembly's references. |
| The Cinemachine View Types are absent from the add menu | The integration may not have imported or may have stopped compiling | Resolve the first Console error, then reimport the Ultimate Character Controller Version 3 Cinemachine integration. |
| Play Mode logs that a Cinemachine Brain must be set up | **Cinemachine Brain** is not on the same GameObject as **Camera Controller** | Move or add Cinemachine Brain to the Unity Camera that owns Camera Controller. |
| Play Mode logs that the Cinemachine Camera must be set | The View Type's **Cinemachine Camera** field is empty | Assign the intended Cinemachine Camera component to that View Type. Use a different camera for each perspective. |
| The camera is present but never becomes Live | Another Cinemachine Camera, output channel, Timeline track, or inactive GameObject may own the Brain | Check the Brain's channel and active camera, stop the competing owner, and let the Ultimate Character Controller View Type activate its assigned camera. |
| Look input moves the shot but items aim in another direction | **Use Character Look Direction**, the crosshairs, View Type, and Movement Type may describe different facing rules | Choose whether character forward or camera/crosshairs should own the look direction, then test the matching Movement Type and item setup. |
| A nonzero Ultimate Character Controller camera offset has no effect | **Cinemachine Camera Offset** may be missing from the assigned camera | Add the extension, set **Apply After** to **Noise**, and retest the View Type's **Camera Offset**. |
| Recoil or camera impacts do not rotate the Cinemachine shot | **Cinemachine Spring Extension** may be absent | Add the integration's spring extension to the assigned Cinemachine Camera and verify the View Type spring values. |
| The third-person camera passes through walls | No Cinemachine obstruction extension is configured | Add **Cinemachine Deoccluder** or another suitable Cinemachine 3 collision workflow and configure its layers and obstacle behavior. |
| Perspective switching flashes, cuts twice, or blends unpredictably | Ultimate Character Controller Transition and the Cinemachine Brain may both be blending, or both View Types may share one Cinemachine Camera | Give each perspective its own camera and establish one blend owner before adding a second layer of transition. |
| First-person arms disappear or render incorrectly | The first-person **Overlay Render Type**, **First Person Camera**, or culling masks may not match the active render pipeline | Restore the Ultimate Character Controller first-person overlay setup and verify it before tuning the Cinemachine composition. |
## Related pages
- [Integrations](https://opsive.com/support/documentation/ultimate-character-controller/integrations/)
- [Camera](https://opsive.com/support/documentation/ultimate-character-controller/camera/)
- [View Types](https://opsive.com/support/documentation/ultimate-character-controller/camera/view-types/)
- [First Person View Type](https://opsive.com/support/documentation/ultimate-character-controller/camera/view-types/included-view-types/first-person/)
- [Third Person View Type](https://opsive.com/support/documentation/ultimate-character-controller/camera/view-types/included-view-types/third-person/)
- [Transition](https://opsive.com/support/documentation/ultimate-character-controller/camera/view-types/included-view-types/transition/)
- [Post Processing](https://opsive.com/support/documentation/ultimate-character-controller/camera/post-processing/)
- [Split Screen](https://opsive.com/support/documentation/ultimate-character-controller/camera/split-screen/)
- [State System](https://opsive.com/support/documentation/ultimate-character-controller/state-system/)
## Developer reference
The integration supplies `CinemachineViewType`, `FirstPersonCinemachine`, `ThirdPersonCinemachine`, `CinemachineUpdater`, and `CinemachineSpringExtension`.
During initialization, `CinemachineViewType` requires a `CinemachineBrain` on the Camera Controller GameObject and an assigned `CinemachineCamera`. It adds `CinemachineBrainEvents` and `CinemachineUpdater` when needed. The updater sets the Brain to manual updates and invokes it once during the render frame so Cinemachine runs in the intended order with Ultimate Character Controller simulation.
When the View Type activates, the bridge enables Cinemachine Brain, raises its assigned camera above the current live camera's priority, synchronizes field of view, and activates that camera GameObject. When it deactivates, it lowers the priority and deactivates the assigned camera. This lifecycle is why a Cinemachine Camera should belong to one gameplay View Type and why Timeline or another priority controller must hand ownership back explicitly.
The View Type returns either character forward or the Cinemachine Camera's rotation as the gameplay look direction, then incorporates crosshairs and Ultimate Character Controller spring corrections where configured. `FirstPersonCinemachine` additionally listens for Ultimate Character Controller perspective and height-change events to update overlays and vertical offset. Custom extensions should preserve these responsibilities rather than moving the Unity Camera independently of Camera Controller.
---
# Control Freak
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/integrations/control-freak/)
Use the [Control Freak](https://assetstore.unity.com/packages/tools/input-management/control-freak-2-touch-input-made-easy-11562?aid=1100lGdc) integration when a Control Freak 2 touch rig should provide movement, look, and action input while Ultimate Character Controller continues to run the character, camera, abilities, and items. The integration replaces the character's Unity input provider with **Control Freak Input**; it does not replace **Player Input Proxy** or create separate touch ownership for multiple players.
## Before you begin
- Install and test an Ultimate Character Controller Version 3 character with its existing input before changing providers.
- Install [Control Freak 2](https://assetstore.unity.com/packages/tools/input-management/control-freak-2-touch-input-made-easy-11562?aid=1100lGdc) before importing the Ultimate Character Controller integration. The bridge compiles against the `ControlFreak2` API.
- Use the Ultimate Character Controller Control Freak integration package offered for the installed Ultimate Character Controller Version 3 release. The supplied bridge does not declare a minimum or maximum Control Freak version, so retest the isolated scene after upgrading either product.
- Commit or back up the project. The setup removes the character's current input provider and any Ultimate Character Controller virtual-control UI that would compete with the Control Freak rig.
- Plan one input owner. The supplied bridge reads Control Freak's shared input source and active rig; it does not expose a player or rig assignment for split-screen touch input.
## Install and connect the integration
1. Import Control Freak 2 and allow Unity to compile.
2. Sign in to [Opsive Downloads](https://opsive.com/downloads/) and download the Control Freak integration. The bridge is not included in the base product's Integrations folder before this download.
3. Import the downloaded package and resolve every Console error. Importing it creates the integration files in the project; confirm that **Control Freak Input** is available from **Add Component** and that `CF2-Opsive-Rig` is present.
4. In the Hierarchy, expand the character and select its `Input` GameObject, such as `AtlasInput`.
The image shows the legacy **Unity Input** provider. A character created with Unity's Input System instead has an Opsive **Unity Input System** provider on this object.
5. Remove the current Opsive input provider, either **Unity Input** or **Unity Input System**, and add **Control Freak Input** to the same GameObject. Keep only one enabled Opsive `PlayerInput` implementation. If no other project code uses Unity's separate **Player Input** component, remove that component when replacing the Input System route as well.
6. Select the character root and assign the new component to **Player Input Proxy > Player Input**.
7. Add `CF2-Opsive-Rig` to the scene, or use a project-owned Control Freak rig with equivalent bindings.
8. In the rig, make the axis and button names match the names requested by the Ultimate Character Controller character. The supplied rig includes common mappings such as `Horizontal`, `Vertical`, `Mouse X`, `Mouse Y`, `Jump`, `Fire1`, and `Reload`; add or rename bindings for any custom ability or item input.
9. Remove the Ultimate Character Controller **VirtualControls** UI created by Setup Manager. Those controls target Ultimate Character Controller's Unity Input or Unity Input System providers, not **Control Freak Input**.
10. Save the scene and prefab changes, then test this one character before adding the integration to a larger scene.
## Configure touch-control behavior
| Choice | Use it when |
| --- | --- |
| **Hide All Touch Controls When Not In Gameplay** | Leave this enabled, its default, when menus or interactions should hide the active Control Freak rig after Ultimate Character Controller disables gameplay input. Disable it only when the rig must remain visible and its own switches decide which controls can be used. |
| **Non Gameplay Switch Name** | Keep the default `Non-Gameplay` when the active rig contains a switch with that exact name. The integration turns the switch on while gameplay input is disabled and off when gameplay resumes. Clear the field if the rig does not use this switch. |
| **Horizontal Look Input Name** and **Vertical Look Input Name** | Keep `Mouse X` and `Mouse Y` when the rig uses the supplied look bindings. Otherwise, change both the rig and these fields to the same names. |
| **Look Vector Mode** and **Look Sensitivity** | Start with Ultimate Character Controller's normal smoothed look and tune sensitivity after movement and action buttons work. The bridge reads Control Freak's raw axis values; Ultimate Character Controller then applies the selected look-vector behavior. |
For a custom rig, bind every visible control to the same name used by the corresponding Ultimate Character Controller ability, item action, movement axis, or camera field. Changing a button's label does not change the input name it sends.
## Understand input ownership
Each playable Ultimate Character Controller character still needs its own **Player Input Proxy**, and that proxy must reference the **Control Freak Input** component intended for the character. At runtime the proxy exposes the provider to the character, camera, abilities, and items.
The supplied provider itself reads the static `CF2Input` source and operates `CF2Input.activeRig`. It has no serialized player ID or rig reference. This is a clear single-active-rig handoff, but duplicating the provider and prefab does not create isolated touch players. For local multiplayer, use a project-specific adapter that separates Control Freak input and rig ownership, or choose an input route with explicit player/device assignment before following the [Split Screen](https://opsive.com/support/documentation/ultimate-character-controller/camera/split-screen/) workflow.
When Ultimate Character Controller disables gameplay input for a menu or interaction, **Control Freak Input** first disables the normal Ultimate Character Controller input path and then updates the active rig. Depending on the two fields above, it hides the touch controls and turns on the `Non-Gameplay` switch. Closing the menu must re-enable gameplay input so the rig and character recover together.
## How input reaches the character
1. A Control Freak touch control writes a named button or axis to `CF2Input`.
2. **Control Freak Input** reads that value through Ultimate Character Controller's standard player-input contract.
3. **Player Input Proxy** exposes the provider on the character root.
4. Ultimate Character Controller's character, camera, ability, and item handlers request their configured input names and produce the visible gameplay result.
This boundary lets the rest of the Ultimate Character Controller setup remain unchanged. If movement works but one action does not, inspect the requested input name before changing the character or ability logic.
## Verify in Play Mode
1. Enter Play Mode and confirm the Console has no missing `ControlFreak2` type or unassigned **Player Input** error.
2. Drag the movement controls through their full range. The intended character should move in every direction and return to idle when the touch ends.
3. Drag the look control slowly and quickly. Both look axes should respond with the intended sensitivity and stop when released.
4. Press `Jump`, `Fire1`, `Reload`, and any project-specific action once. Each control should start only the matching ability or item action.
5. Open a menu or interaction that disables Ultimate Character Controller gameplay input. With **Hide All Touch Controls When Not In Gameplay** enabled, gameplay controls should hide; with a configured `Non-Gameplay` switch, the rig's menu controls should enter that switch state.
6. Close the menu. The gameplay controls should return and the character should respond without reloading the scene.
7. Make a development build for the target mobile device and repeat the test with real multitouch, orientation changes, safe-area placement, pausing, death, and respawn.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| Unity reports that `ControlFreak2` or `CF2Input` is missing. | Control Freak 2 may be absent, may have been imported after the bridge, or may not compile in the current project. | Install and compile Control Freak 2 first, then reimport the matching Ultimate Character Controller Version 3 integration. |
| The character does not respond. | **Player Input Proxy > Player Input** may be empty or may still reference the removed Unity provider. | Assign the character's enabled **Control Freak Input** component and keep only one Opsive input provider active. |
| Movement works but look or an action does not. | The Control Freak binding and the Ultimate Character Controller field or ability may use different names. | Match the names exactly on both sides, including spaces and capitalization. |
| One press triggers twice or two control layouts appear. | A Unity input provider or Ultimate Character Controller **VirtualControls** UI may still be active beside the Control Freak setup. | Remove the competing provider and generated Ultimate Character Controller virtual controls; keep the intended Control Freak rig. |
| Touch controls remain visible over a gameplay-blocking menu. | **Hide All Touch Controls When Not In Gameplay** may be disabled, no active rig may exist, or the menu may not disable Ultimate Character Controller gameplay input. | Enable the field, confirm the rig is active, and make the menu send the normal Ultimate Character Controller gameplay-input disable and enable flow. |
| The wrong controls are available while a menu is open. | **Non Gameplay Switch Name** may not match a switch in the active rig. | Create the matching `Non-Gameplay` switch, correct the field, or clear it when the rig does not use switch-based menu controls. |
| A second local character responds to the same touch controls. | Both providers read the shared `CF2Input` source; the supplied bridge has no per-player assignment. | Do not duplicate the stock bridge as a split-screen ownership solution. Add a project-specific isolated provider or use an input system with player/device assignment. |
| Cursor-position aiming or UI-hover blocking does not work. | The stock bridge returns a zero mouse position and reports that the pointer is not over UI. | Use touch bindings that do not depend on screen-pointer queries, or extend the provider to return the Control Freak pointer and UI state required by the project. |
## Related pages
- [Integrations](https://opsive.com/support/documentation/ultimate-character-controller/integrations/)
- [Input](https://opsive.com/support/documentation/ultimate-character-controller/input/)
- [Virtual Controls](https://opsive.com/support/documentation/ultimate-character-controller/input/virtual-controls/)
- [Quick Setup](https://opsive.com/support/documentation/ultimate-character-controller/getting-started/quick-setup/)
- [Split Screen](https://opsive.com/support/documentation/ultimate-character-controller/camera/split-screen/)
## Developer reference
The integration supplies `Opsive.Shared.Input.ControlFreak.ControlFreakInput`, which derives from Ultimate Character Controller's `PlayerInput`. Button requests delegate to `CF2Input.GetButton`, `GetButtonDown`, and `GetButtonUp`. Both ordinary and raw axis requests begin with `CF2Input.GetAxisRaw`; the inherited Ultimate Character Controller look settings then determine whether and how the look vector is smoothed.
`GetMousePosition` returns zero and `IsPointerOverUI` returns `false` in the stock bridge. Movement, named buttons, and named look axes do not depend on those methods, but screen-position View Types, cursor-following crosshairs, point-and-click movement, or abilities that block while the pointer is over UI need a project-specific override.
When Ultimate Character Controller changes gameplay-input state, the provider calls the base implementation and then checks `CF2Input.activeRig`. It can call `ShowOrHideTouchControls` and set the configured non-gameplay switch, but it does not search for or assign a rig. Keep the intended rig active before this lifecycle runs.
---
# Dialogue System
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/integrations/dialogue-system/)
Use the [Dialogue System](https://assetstore.unity.com/packages/tools/behavior-ai/dialogue-system-for-unity-11672?aid=1100lGdc) integration when an Ultimate Character Controller character should start conversations through the normal Interact ability, hand camera and input control to the conversation when needed, and include Ultimate Character Controller character data in Dialogue System saves.
For example, the player can approach an NPC, see an interaction prompt, press the Action input, talk with movement and weapons disabled, and return to gameplay when the conversation ends.
## Before you begin
- Start with a working Ultimate Character Controller Version 3 character. Verify movement, camera, input, and the Interact ability before adding dialogue.
- Install Dialogue System for Unity and create a small conversation that works with its Dialogue Manager.
- Sign in to [Opsive Downloads](https://opsive.com/downloads/) and download the current Pixel Crushers bridge. It is not included in the base product's Integrations folder before download. The downloaded package does not declare a semantic minimum or maximum Dialogue System version, so reinstall the matching current bridge after updating either product.
- Back up the project before importing or replacing an integration package.
This workflow describes the supported Ultimate Character Controller Version 3 bridge. It does not apply to the legacy UFPS, UTPS, First Person Controller, or Third Person Controller integrations that appeared on the older version of this page.
## Install the integration
1. Open **Tools > Opsive > Ultimate Character Controller > Integrations Manager**.
2. Find **Dialogue System for Unity**, select **Integration**, and import the package provided for the installed products.
3. Allow Unity to compile. Resolve the first Console error before configuring the scene; the bridge requires both Ultimate Character Controller and Dialogue System assemblies.
4. Add Dialogue System's **Dialogue Manager** prefab from **Plugins > Pixel Crushers > Dialogue System > Prefabs** to the scene, then assign the project's dialogue database and UI using the normal Dialogue System workflow.
5. Confirm that the imported support contains **Converse**, **Dialogue System Trigger Interactable Target**, **UCC Saver**, and the supplied **UCC DS Example** scene.
If the project also uses Ultimate Inventory System, add `UIS` to **Edit > Project Settings > Player > Other Settings > Scripting Define Symbols** after importing the bridge. This enables the integration's Ultimate Inventory System-aware menu and input handling.
## Configure the player
1. Select the player root and open the **Abilities** list on **Ultimate Character Locomotion**.
2. Add the **Converse** ability. Leave **Start Type** and **Stop Type** set to **Manual**; the integration starts and stops this passive ability from Dialogue System conversation events.
3. Leave **Allow Positional Input** and **Allow Rotational Input** disabled so the character cannot move or turn during the conversation.
4. Configure the conversation behavior:
- **Hide UI** hides Ultimate Character Controller gameplay UI while dialogue is active.
- **Disable Gameplay Input** sends Ultimate Character Controller's gameplay-input event off at the start and restores it after the conversation.
- **Detach Camera** temporarily removes the character from the active Ultimate Character Controller Camera Controller so Dialogue System can own the shot.
The current bridge enables all three choices by default; disable one only when another system deliberately owns that responsibility.
5. Under **Allow Equipped Slots**, disable any slots that must be holstered while talking. For a two-slot character, this normally means disabling **Slot 0** and **Slot 1**.
6. Add or keep the standard Ultimate Character Controller **Interact** ability. Converse does not detect an NPC or start a conversation by itself.
7. In the Interact ability, set **Ability Message Text** to a prompt such as `Talk to {0}`. The integration replaces `{0}` with the target Dialogue Actor's name.
### Choose camera ownership
- Keep **Detach Camera** disabled when the normal Ultimate Character Controller gameplay camera should remain attached throughout the conversation.
- Enable **Detach Camera** when Dialogue System's sequencer should control the shot. Assign a dedicated camera under **Dialogue Manager > Display Settings > Camera & Cutscene Settings > Sequencer Camera** and verify that only one camera owns the conversation view.
The stock **Converse** ability locates the first active Ultimate Character Controller Camera Controller. A split-screen or multi-camera game should use a project-specific bridge that resolves the correct camera for each player rather than relying on this single-camera behavior.
### Configure the conversing input state
1. On the input component used by the player, add a state named `Conversing` that exposes the cursor and blocks the gameplay controls that should not run during dialogue.
2. If the character uses Ultimate Character Controller's **Unity Input** component, apply the imported `ConversingUnityInputPreset` as the starting configuration.
3. If the character uses Unity Input System, Rewired, or another input integration, create the equivalent `Conversing` state on that provider. The supplied preset targets **Unity Input** and should not be assumed to configure every provider.
4. If gamepad dialogue should use a separate state without exposing the cursor, create a second state such as `ConversingDisableCursor` and assign it to **Converse > Conversing State Names > Conversing State Hide Cursor**.
Converse selects the normal or hide-cursor state from Dialogue System's current input-device information. Test both mouse and gamepad instead of assuming that one cursor rule fits every device.
### Coordinate Ultimate Inventory System menus
When Ultimate Inventory System owns menus and cursor state:
1. Add **UCC Menu Utility** and **Dialogue System Events** to the player.
2. Connect **Dialogue System Events > On Conversation Start ()** to **UCC Menu Utility > On Open Menu**.
3. Connect **On Conversation End ()** to **UCC Menu Utility > On Close Menu**.
4. Test the end of a conversation while another Ultimate Inventory System menu is open. The `UIS` scripting symbol allows Converse to avoid restoring gameplay input while Ultimate Inventory System still owns the menu.
## Configure an NPC or conversation object
1. Select the NPC or object that the player should use.
2. Add **Dialogue System Trigger Interactable Target**. Set **Trigger** to **On Use**, then configure its conversation action and actor assignments as you would on a normal Dialogue System trigger.
3. Add Ultimate Character Controller's **Interactable** component to the same detected object and assign **Dialogue System Trigger Interactable Target** in **Targets**.
4. On the player's Interact ability, choose an **Object Detection** mode, **Detect Layers**, and **Cast Distance** that can find the Interactable.
5. Enter Play Mode and use Ultimate Character Controller's ability message to confirm that the intended object is detected before testing the conversation.
Do not add a second ordinary **Dialogue System Trigger** for the same Ultimate Character Controller interaction. **Dialogue System Trigger Interactable Target** already receives Ultimate Character Controller's interaction and invokes its configured **On Use** action.
If the NPC is also an Ultimate Character Controller character, place the **Interactable** on the detected collider object, normally the **Colliders > CapsuleCollider** child. Ultimate Character Controller character roots are commonly tagged `Player` while their collider children are untagged, so a tag-based Dialogue System trigger may miss the collider. The Ultimate Character Controller Interactable route avoids that mismatch.
## Add Ultimate Character Controller data to saved games
Dialogue System saves its own dialogue, quest, and variable data. Add **UCC Saver** to an Ultimate Character Controller character when the same save should also include selected Ultimate Character Controller state:
1. Add **UCC Saver** to the character root.
2. Enable only the categories the game needs: **Save Perspective**, **Save Mouse Settings**, **Save Position**, **Save Attributes**, and **Save Inventory**. The current bridge enables all five by default.
3. Tag the player root `Player` when a Dialogue System scene portal or save-system load should place the player at a spawn point. The integration also uses this tag as its default player lookup.
4. Test a complete save and load after changing every enabled category. **Save Mouse Settings** depends on the active Ultimate Character Controller input route and should be verified rather than assumed.
For runtime pickups that were not present in the starting inventory:
1. Select **Create > Pixel Crushers > Dialogue System > UCC Saver Runtime Pickups**.
2. Add the runtime item identifiers to the asset's **Runtime Items** list.
3. Assign the asset to **UCC Saver > Runtime Pickups**.
To respawn at the most recent save instead of the normal Ultimate Character Controller respawn point, replace **Character Respawner** with **Checkpoint Character Respawner** and set **Checkpoint Save Slot** to the slot used by the game. Its default is slot `1`; when that slot has no saved game, normal Ultimate Character Controller respawning is used.
## How it runs
1. Ultimate Character Controller's Interact ability detects the **Interactable** and calls the assigned **Dialogue System Trigger Interactable Target**.
2. The target invokes its **On Use** conversation action with the interacting character as the user.
3. Dialogue System's conversation events start **Converse** on the actors involved in the conversation. Converse applies its input, UI, equipped-slot, state, and camera choices.
4. Dialogue System runs the conversation and any sequencer commands. Ultimate Character Controller continues to own the character's locomotion and abilities unless the integration deliberately disables or detaches them.
5. When the conversation ends, Converse restores the camera, UI, input, equipped slots, and conversing state. Input restoration is delayed briefly so a newly starting conversation does not cause a one-frame gameplay-input handoff.
## Key choices and limitations
| Choice | Use it when | Important consequence |
| --- | --- | --- |
| Keep the Ultimate Character Controller camera attached | Dialogue uses the normal gameplay view | Leave **Detach Camera** disabled; do not ask a sequencer camera to control the same shot. |
| Let Dialogue System control the shot | A conversation needs cuts or staged framing | Enable **Detach Camera** and configure a dedicated **Sequencer Camera**. |
| Use Ultimate Character Controller interaction | The player should use the normal Action input, detection, prompt, and ability rules | Use **Interactable** plus **Dialogue System Trigger Interactable Target**, not a duplicate ordinary trigger. |
| Save Ultimate Character Controller character state | Dialogue System saves must include position, attributes, inventory, perspective, or mouse settings | Add **UCC Saver** and explicitly test each enabled category. Custom ability state is not included automatically. |
| Use multiple local players or cameras | Each player has separate camera, input, or menu ownership | The stock camera and menu utilities use a global or first-camera lookup; extend them so the correct player owns each conversation. |
The interactable target rejects a non-local network character when Ultimate Character Controller multiplayer support is enabled, but that does not make the rest of the stock bridge split-screen aware. Camera, cursor, menu, and save ownership still need a deliberate per-player design.
## Verify in Play Mode
1. Approach the NPC. The Interact ability message should show the Dialogue Actor name in place of `{0}`.
2. Press the Action input. The configured conversation should start exactly once.
3. Confirm that movement, look, items, gameplay UI, cursor, and camera follow the selected Converse settings.
4. End the conversation. The same player should regain input, UI, equipped items, camera ownership, and the previous cursor behavior.
5. Start another conversation immediately. Input should not flash on between the two conversations.
6. Test with mouse and gamepad. The correct conversing state should activate for each device.
7. If Ultimate Inventory System is installed, end dialogue while an Ultimate Inventory System menu is still open. Gameplay input should remain disabled until the menu closes.
8. Save after changing an enabled attribute, inventory item, perspective, and position; change them again, then load. Only the categories enabled on **UCC Saver** should be restored.
9. Load a scene through the selected Dialogue System save flow and test the configured spawn point or checkpoint slot.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| The bridge scripts are missing or Unity reports unresolved Pixel Crushers or Opsive types | One product may be absent, or the imported bridge may not match the installed releases | Install both products first, then obtain and reimport the current bridge through **Integrations Manager**. Resolve the first Console error. |
| The prompt appears but no conversation starts | **Interactable > Targets** may be empty, **Trigger** may not be **On Use**, or the target may have no configured conversation action | Assign **Dialogue System Trigger Interactable Target** in **Targets**, select **On Use**, and configure its action and actors. |
| The prompt never appears | The Interact ability may not detect the correct collider or layer | Inspect **Object Detection**, **Detect Layers**, **Cast Distance**, and the collider that owns **Interactable**. Put it on the detected CapsuleCollider child for an Ultimate Character Controller NPC. |
| The conversation starts twice | An ordinary **Dialogue System Trigger** may be running beside the integration target | Keep one interaction route. Remove or disable the duplicate trigger for the same use action. |
| The player can move, look, or use items during dialogue | Converse may be absent from the participating Ultimate Character Controller character, its restrictions may be disabled, or the allowed equipped-slot mask may still permit the item | Add Converse to the actor, keep its start and stop types Manual, enable the needed UI/input restrictions, and update **Allow Equipped Slots**. |
| Input or the cursor is wrong during dialogue | The active input provider may not have the named conversing state | Apply `ConversingUnityInputPreset` only to **Unity Input**, or create matching `Conversing` and optional hide-cursor states on the actual provider. |
| Gameplay input stays disabled after dialogue | Conversation end may not have fired, Ultimate Inventory System may still own a menu, or two input owners may be restoring state in the wrong order | Confirm **On Conversation End ()**, the `UIS` symbol and menu events, then reduce the setup to one clear menu/input owner and retest. |
| The camera snaps, goes blank, or never returns | **Detach Camera** may be enabled without a working sequencer camera, or two camera systems may be competing | Configure one dedicated **Sequencer Camera**, or disable **Detach Camera** to keep the Ultimate Character Controller camera attached. Test the end event and camera return. |
| A save restores dialogue but not health, inventory, or position | Dialogue System's save exists, but **UCC Saver** or its category is missing | Add **UCC Saver** to the character and enable the exact Ultimate Character Controller categories that should be included. |
| A runtime pickup disappears after loading | Its item identifier may not be in the assigned runtime-pickups asset | Add it to **UCC Saver Runtime Pickups > Runtime Items** and assign that asset to **UCC Saver > Runtime Pickups**. |
| Respawn loads the wrong checkpoint or uses the normal respawn point | **Checkpoint Save Slot** may not match the slot that contains the save | Select the correct slot. Normal respawn is expected when no saved game exists in that slot. |
| The wrong local player or camera is affected | The stock bridge may have resolved the first Camera Controller or the `Player`-tagged object | Give each player an explicit camera, input, menu, and save owner in a project-specific extension. Do not rely on the stock global lookup for split screen. |
## Related pages
- [Integrations](https://opsive.com/support/documentation/ultimate-character-controller/integrations/)
- [Interact ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/detect-object-ability-base/interact/)
- [Input](https://opsive.com/support/documentation/ultimate-character-controller/input/)
- [Camera](https://opsive.com/support/documentation/ultimate-character-controller/camera/)
- [Items and Inventory](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/)
- [Ultimate Inventory System integration](https://opsive.com/support/documentation/ultimate-character-controller/integrations/ultimate-inventory-system/)
- [Respawner](https://opsive.com/support/documentation/ultimate-character-controller/spawn-system/respawner/)
- [Events](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/)
- [Pixel Crushers' Ultimate Character Controller integration manual](https://www.pixelcrushers.com/dialogue_system/manual2x/html/ucc.html)
## Developer reference
The bridge supplies these primary integration points:
- `Converse` listens to Dialogue System conversation events for the Ultimate Character Controller character and applies the configured UI, gameplay-input, camera, item-slot, and state behavior. It is passive and does not initiate a conversation.
- `DialogueSystemTriggerInteractableTarget` implements Ultimate Character Controller's interactable target and message interfaces. It passes the interacting character to its **On Use** action and uses the target's Dialogue Actor name for `{0}` prompts.
- `UCCMenuUtility` sends Ultimate Character Controller's gameplay-input event and changes cursor visibility for Dialogue System or Ultimate Inventory System menu events. The stock component resolves the character from the active Camera Controller.
- `UCCSaver` contributes the selected position, attribute, inventory, perspective, and mouse-setting data to Pixel Crushers' Save System. Dialogue System remains responsible for its own dialogue and quest data.
- `CheckpointCharacterRespawner` loads **Checkpoint Save Slot** on respawn when that slot has a saved game, otherwise it falls back to the ordinary Ultimate Character Controller respawn behavior.
Add **Ultimate Character Controller Lua** to the Dialogue Manager only when dialogue Lua needs Ultimate Character Controller data. It registers `uccGetAttribute`, `uccSetAttribute`, `uccGetItemCount`, `uccAddItem`, `uccRemoveItem`, `uccEquipItem`, `uccUnequipItem`, and `uccNotifyOnEquip`. A blank character name resolves the `Player`-tagged Ultimate Character Controller character; append `.CollectionName` to select a nondefault item collection, such as `Vendor.SpecialStock` or `.Backpack` for the tagged player. The remove function removes items, not ammunition, and equip or unequip calls require **Equip Unequip Item Ability > Auto Equip** to be **NotPreset**.
The bridge also adds the Dialogue System sequencer command `uccLookAt(target, subject, duration, allAxes)`. The target defaults to the listener, the subject defaults to the speaker, duration is optional, and omitting `allAxes` keeps the subject upright. The command temporarily disables the subject's **Ultimate Character Locomotion** while it rotates, so do not overlap it with another system that must move that character during the same sequence.
---
# Easy Build System
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/integrations/easy-build-system/)
Use the [Easy Build System](https://assetstore.unity.com/packages/slug/45394?aid=1100lGdc) integration when an Ultimate Character Controller character should enter and control a building workflow through a character Ability instead of bypassing Ultimate Character Controller input, camera, locomotion, and State coordination.
## Install and add the ability
1. Install and verify Easy Build System without Ultimate Character Controller.
2. Sign in to [Opsive Downloads](https://opsive.com/downloads/), download the Easy Build System integration, and import `UltimateCharacterControllerEasyBuildSystem.unitypackage`. The bridge does not exist in the base product's Integrations folder before this download; importing it creates the integration files in the project.
3. Let Unity compile and confirm the **Building Ability** type is available in the Ultimate Character Locomotion ability list.
4. Add **Building Ability** to the character and configure its inherited Start Type, Stop Type, input, State, and concurrency settings for the intended build mode.
5. Connect the Easy Build System controller expected by the installed integration version.
The released bridge contains one `BuildingAbility` source file. Easy Build System still owns its preview, placement, adjustment, destruction, and save configuration.
## Verify in Play Mode
1. Start the Building Ability and confirm the expected build controller enters its mode.
2. Place and cancel one preview while checking cursor, camera, movement, and item input ownership.
3. Stop or interrupt the Ability and confirm the preview and build mode are cleaned up.
4. Test perspective changes, pause, death, respawn, and scene reload.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| Building Ability is missing. | Check Easy Build System, the bridge package, and the first Console error. | Install the dependency first and reimport the released Ultimate Character Controller bridge. |
| Build input and item input both fire. | Check the Ability State and input ownership. | Disable or block the competing item/gameplay input while Building Ability is active. |
| A preview remains after interruption. | Check the bridge and build controller cleanup path. | Stop building through the Ability lifecycle and add project cleanup for the installed version if needed. |
## Related pages
- [Abilities](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/)
- [Creating a New Ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/new-ability/)
- [States](https://opsive.com/support/documentation/ultimate-character-controller/state-system/)
---
# Edy's Vehicle Physics
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/integrations/edys-vehicle-physics/)
Use the [Edy's Vehicle Physics](https://assetstore.unity.com/packages/tools/physics/edy-s-vehicle-physics-403?aid=1100lGdc) integration when an Ultimate Character Controller character should approach a vehicle, enter its driver position, hand driving and optional camera control to Edy's Vehicle Physics, then return to ordinary character control on exit.
## Before you begin
- Build and test the Ultimate Character Controller Version 3 character, camera, and **Drive** ability without relying on the vehicle to diagnose character setup.
- Build and test the Edy's Vehicle Physics vehicle with **Vehicle Controller** and **Vehicle Standard Input** before connecting Ultimate Character Controller. Follow the [Edy's Vehicle Physics 5 user guide](https://www.edy.es/dev/vehicle-physics/user-guide/) for its wheels, Rigidbody, handling, and control setup.
- The audited integration project contains Edy's Vehicle Physics 5.3. The bridge has no embedded minimum or maximum version check, so confirm the required `EVP.VehicleStandardInput` and `EVP.VehicleCameraController` APIs still exist when using a later 5.x release.
- Decide whether Ultimate Character Controller's Camera Controller or Edy's **Vehicle Camera Controller** should own the Unity Camera while driving.
- Check the input boundary before importing. Edy's supplied **Vehicle Standard Input** reads Unity's legacy `Input.GetAxis` API directly; it does not read the character's Ultimate Character Controller **Player Input Proxy**.
## Install the integration
1. Install [Edy's Vehicle Physics](https://assetstore.unity.com/packages/tools/physics/edy-s-vehicle-physics-403?aid=1100lGdc) and verify one of its vehicles in Play Mode.
2. Sign in to [Opsive Downloads](https://opsive.com/downloads/) and download the Edy's Vehicle Physics integration. The bridge is not included in the base product's Integrations folder before this download.
3. Import the downloaded Version 3 bridge after the vehicle asset. Importing it creates the integration files in the project.
4. Allow Unity to compile. Resolve the first Console error before adding components; the bridge requires both Ultimate Character Controller and the `EVP` types.
5. Open the imported integration sample and confirm that **EVP Drive Source** is available from Add Component.
Reimport the current bridge after updating Ultimate Character Controller or Edy's Vehicle Physics. A working 5.3 integration scene is useful evidence, but it is not a compatibility guarantee for every later package combination.
## Connect the vehicle
1. Select the vehicle root that contains **Vehicle Controller**.
2. Add or keep **Vehicle Standard Input** on this same GameObject. Assign its **Target** to the Vehicle Controller, or leave it empty so Edy's component finds the Vehicle Controller beside it when enabled.
3. Add **EVP Drive Source** to the same GameObject. The bridge specifically looks for **Vehicle Standard Input** beside itself and cannot enable a component on another object.
4. Create a child Transform named `Driver Location`. Position and rotate it at the character's seated pose, then assign it to **EVP Drive Source > Driver Location**.
5. Set **Animator ID**. Use `0` for a simple vehicle with the default Drive animation set, or use a unique base ID when the Animator contains vehicle-specific Enter, Drive, and Exit states.
6. Add one or more **Move Towards Location** children beside the doors or other safe entry and exit points. Drive requires at least one clear location even when **Teleport Enter Exit** is enabled.
7. Add the collider or trigger that Drive should detect. Put it on a layer included by the ability's **Detect Layers** and keep **EVP Drive Source** on that object or one of its parents.
8. Confirm that every active vehicle collider which should ignore the seated character is below the EVP Drive Source GameObject when the scene starts. The bridge caches those child colliders once during `Start`.
### Configure Edy's driving input
On **Vehicle Standard Input**, choose the control behavior before testing the Ultimate Character Controller handoff:
- **Steer Axis** defaults to `Horizontal`.
- **Throttle And Brake Input** can use **Single Axis** with **Throttle And Brake Axis** `Vertical`, or **Separate Axes** with **Throttle Axis** `Fire2` and **Brake Axis** `Fire3`.
- **Continuous Forward And Reverse** allows the vertical input to brake and then reverse without a separate modifier.
- **Handbrake Axis** defaults to `Jump`. **Handbrake Overrides Throttle** reduces throttle while the handbrake is applied.
- **Reset Vehicle Key** defaults to Return.
These are Unity Input Manager names, not Ultimate Character Controller action names. If the project uses Unity Input System only, either enable the legacy Input Manager compatibility required by Vehicle Standard Input and create these mappings, or adapt the Drive Source to enable a project-owned EVP input component. Do not expect assigning an Ultimate Character Controller **Unity Input System** component to the character to feed Edy's `Input.GetAxis` calls.
## Configure the character
1. Add **Drive** to **Ultimate Character Locomotion > Abilities**. Keep its normal `Action` input unless the project uses another enter and exit control.
2. For an animated approach, add **Move Towards** above Drive in the ability list. Add the exact `OnAnimatorEnteredVehicle` and `OnAnimatorExitedVehicle` events to every reachable entry and exit animation.
3. Enable **Teleport Enter Exit** when the character should move immediately between the selected Move Towards Location and **Driver Location** without entry or exit animation events.
4. Configure the inherited **Object Detection**, **Detect Layers**, and optional **Object ID** so Drive detects the vehicle collider.
5. Choose whether the character may keep items or Aim active with **Allow Equipped Slots** and **Can Aim**. Use **Disable Mesh Renderers** when the seated character body should be hidden.
6. Follow the complete [Drive ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/detect-object-ability-base/drive/) workflow for exit clearance, collision handling, item restoration, interpolation, and vehicle-specific Animator IDs.
The Ultimate Character Controller `Action` input starts and stops Drive. Edy's Vehicle Standard Input remains disabled until the character has fully entered, then reads its own steering, throttle, brake, handbrake, and reset controls.
## Choose the camera owner
### Keep the Ultimate Character Controller camera
Disable **EVP Drive Source > Use Vehicle Camera Controller** and disable or remove Edy's **Vehicle Camera Controller**. Ultimate Character Controller's Camera Controller then remains active while the character is seated at **Driver Location**.
Use this route when the existing Ultimate Character Controller View Type already gives the desired vehicle framing. The bridge does not automatically switch to a vehicle-specific Ultimate Character Controller View Type, so configure any perspective or state change separately.
### Use Edy's vehicle camera
1. Add **Vehicle Camera Controller** to the same active GameObject as Ultimate Character Controller's **Camera Controller** and **Camera Controller Handler**.
2. Assign **Target** to the vehicle and choose the starting **Mode**: Attach To, Smooth Follow, Mouse Orbit, Look At, or Free.
3. Configure **Follow Center Of Mass**, **Camera Collisions**, **Collision Mask**, and the selected mode's framing. **Change Camera Key** defaults to `C`.
4. Enable **EVP Drive Source > Use Vehicle Camera Controller**. This choice is enabled by default in the audited bridge.
5. Leave the camera GameObject active when the scene starts. EVP Drive Source finds the first Vehicle Camera Controller once during `Start`, disables it while the vehicle is unoccupied, and enables it after entry.
When Edy's camera becomes active, the bridge disables Ultimate Character Controller's Camera Controller and Camera Controller Handler on that Unity Camera. It reverses the handoff as soon as exit begins. The Unity Camera and Audio Listener themselves remain on the same GameObject.
The stock bridge does not change **Vehicle Camera Controller > Target** when a different vehicle is entered. A scene with several drivable vehicles must update the target deliberately or use a project-specific Drive Source. The first scene-wide Vehicle Camera Controller found at startup is the only one the stock source toggles.
## How it runs
1. At scene start, **EVP Drive Source** caches its GameObject, Transform, and active child colliders. It finds **Vehicle Standard Input**, finds the first Vehicle Camera Controller, and disables the vehicle input and opted-in Edy camera.
2. Ultimate Character Controller Drive detects the source and begins the approach or teleport. `EVPDriveSource.EnterVehicle` does not enable the vehicle yet, so the character and Ultimate Character Controller camera retain control during entry.
3. When entry completes, Ultimate Character Controller calls `EnteredVehicle`. The bridge remembers the character, enables Vehicle Standard Input, and optionally enables Edy's camera while disabling the Ultimate Character Controller camera components.
4. Vehicle Standard Input writes steering, throttle, brake, and handbrake values to Edy's Vehicle Controller. Ultimate Character Controller Drive keeps the character aligned with **Driver Location** and ignores collisions with the cached vehicle colliders.
5. A valid exit request calls `ExitVehicle` before the exit animation completes. The bridge disables Vehicle Standard Input, which zeros the vehicle controls, disables Edy's camera, and re-enables the Ultimate Character Controller camera components.
6. Ultimate Character Controller completes the exit, restores character collision and parenting, and places the character at the selected clear Move Towards Location.
## Key choices and limitations
| Choice | Use it when | Important consequence |
| --- | --- | --- |
| **Teleport Enter Exit** | No enter or exit animations are available | Entry and exit are immediate, but a clear Move Towards Location is still required. |
| Animated entry and exit | The character should approach a door and play seated transitions | Animator events must call `OnAnimatorEnteredVehicle` and `OnAnimatorExitedVehicle` at the handoff points. |
| Ultimate Character Controller camera | One Ultimate Character Controller View Type should remain active | Disable **Use Vehicle Camera Controller** and the Edy camera component so they do not compete. |
| Edy's vehicle camera | EVP modes should control the shot | Put both camera controllers on one GameObject and assign the correct vehicle target before entry. |
| Legacy Input Manager | Vehicle Standard Input should be used unchanged | Configure its named axes; its input is global and separate from Ultimate Character Controller Player Input Proxy. |
| Unity Input System, mobile, or local multiplayer | Input needs action maps, touch ownership, or per-player devices | Use a project-owned EVP input handoff instead of assuming Vehicle Standard Input understands the Ultimate Character Controller provider. |
The stock integration assumes one local driver and one scene-wide vehicle camera. It contains no multiplayer synchronization, per-player input selection, or dynamic camera-target assignment. When Ultimate Character Controller multiplayer support is enabled, an `IDriveSource` is responsible for notifying remote players; EVP Drive Source does not implement that network layer.
A forced stop is another important boundary. Ultimate Character Controller Drive restores its own character state when force-stopped, but the stock EVP source disables vehicle input and returns camera ownership only in its normal `ExitVehicle` callback. Death, destruction, scene changes, or custom code that force-stops Drive while seated should perform equivalent EVP input and camera cleanup.
## Verify in Play Mode
1. Enter Play Mode without entering the vehicle. Vehicle Standard Input should be disabled, the parked vehicle should not respond to its axes, and the intended gameplay camera should be active.
2. Approach the entry collider. Drive's inherited **Detected Object** should show the vehicle.
3. Press the configured `Action` input. Confirm the character reaches the expected Move Towards Location or teleports, then aligns with **Driver Location**.
4. During the entry animation, the vehicle should remain disabled. It should accept steering, throttle, brake, and handbrake only after entry completes.
5. If **Use Vehicle Camera Controller** is enabled, confirm Edy's selected mode takes over after entry and Ultimate Character Controller camera look no longer competes. If it is disabled, confirm the Ultimate Character Controller camera remains in control.
6. Drive forward, reverse, steer, brake, use the handbrake, and reset the vehicle. Release every control and confirm its corresponding Vehicle Controller input returns to zero.
7. Press `Action` with a clear exit location. Vehicle input should stop and Ultimate Character Controller camera ownership should return as soon as exit begins; ordinary character movement should return when exit completes.
8. Block one exit location and try again. Drive should remain active until another configured location is clear.
9. Test death, forced ability stop, scene loading, and vehicle destruction while seated. Confirm the project returns vehicle input and camera ownership explicitly for each supported interruption.
10. For more than one vehicle or player, repeat the full test with each target and input owner. No other vehicle, character, or camera should respond.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| Unity reports missing `EVP` types after import | Edy's Vehicle Physics may be absent, imported after the bridge, or incompatible with the bridge source | Install and compile the vehicle asset first, then reimport the current Ultimate Character Controller Version 3 integration. |
| The Console says EVP Drive Source must be attached to a vehicle with the Edy controller | **Vehicle Standard Input** may not be on the same GameObject as **EVP Drive Source**, or its **Target** cannot resolve Vehicle Controller | Put Vehicle Controller, Vehicle Standard Input, and EVP Drive Source on the vehicle root and assign **Target**. |
| Drive never detects the vehicle | The detected collider's layer may be excluded, the source may not be on a parent, or no clear Move Towards Location exists | Correct **Detect Layers**, move EVP Drive Source to the detected hierarchy, and add a clear entry or exit location. |
| The character enters but the vehicle does not respond | Vehicle Standard Input may not have enabled, its axis names may be absent, or entry may still be waiting for its Animator event | Inspect the component after entry, add `OnAnimatorEnteredVehicle`, and configure the named Input Manager axes. |
| The vehicle works with the old Input Manager but not Unity Input System | Vehicle Standard Input calls legacy `Input.GetAxis` directly | Enable and configure the compatible legacy input route, or adapt EVP Drive Source to enable a project-owned Input System provider. |
| The vehicle moves before the character enters | Another script or Vehicle Manager may be enabling or writing Vehicle Controller input | Give the bridge sole input ownership for this vehicle, or replace the stock handoff with an explicit manager integration. |
| Edy's camera never takes over | **Use Vehicle Camera Controller** may be disabled, the component may be absent or on an inactive GameObject at startup, or the source may have started before it existed | Add it to the active Ultimate Character Controller camera GameObject before Play Mode, enable the toggle, assign **Target**, and retest. |
| The Ultimate Character Controller and Edy cameras fight | Both camera controllers may be active, or **Use Vehicle Camera Controller** may be disabled while Edy's component remains enabled | Choose one owner. Let the bridge toggle Edy's camera when enabled, or disable Edy's component and keep the Ultimate Character Controller camera. |
| The camera follows the wrong vehicle | The stock bridge found one scene-wide camera whose **Target** still references another vehicle | Assign the intended target before entry or extend the Drive Source to update it for each vehicle. |
| Exit input does nothing | No Move Towards Location may be clear | Add another exit point or clear the overlap around its optional clearance collider. |
| Vehicle input or Edy's camera stays active after death or a forced stop | The normal `ExitVehicle` callback may have been bypassed | Add project cleanup that disables Vehicle Standard Input and Edy's camera and re-enables Ultimate Character Controller Camera Controller and Camera Controller Handler. |
| The character collides with a collider added after startup | EVP Drive Source caches active child colliders only once in `Start` | Keep required colliders active below the source at startup or update the custom source's collider list when the vehicle changes. |
## Related pages
- [Integrations](https://opsive.com/support/documentation/ultimate-character-controller/integrations/)
- [Drive ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/detect-object-ability-base/drive/)
- [Move Towards](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/move-towards/)
- [Move Towards Location](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/move-towards-location/)
- [Input](https://opsive.com/support/documentation/ultimate-character-controller/input/)
- [Camera](https://opsive.com/support/documentation/ultimate-character-controller/camera/)
- [Split Screen](https://opsive.com/support/documentation/ultimate-character-controller/camera/split-screen/)
## Developer reference
`EVPDriveSource` implements Ultimate Character Controller's `IDriveSource`. It exposes **Driver Location**, **Animator ID**, and **Use Vehicle Camera Controller**, and supplies the vehicle GameObject, Transform, and cached child colliders to Drive.
Its lifecycle callbacks have deliberately small responsibilities:
- `EnterVehicle(Drive)` does nothing while the character approaches or animates into the seat.
- `EnteredVehicle(Drive)` stores the character and enables Vehicle Standard Input and the optional Edy camera handoff.
- `ExitVehicle(Drive)` disables vehicle input, returns camera ownership, and clears the stored character as soon as a valid exit starts.
- `ExitedVehicle(Drive)` does nothing after Ultimate Character Controller finishes restoring the character.
At startup, the source uses `GetComponent()`, `GetComponentsInChildren()`, and `FindObjectOfType()`. These lookups explain the same-GameObject input requirement, the startup collider snapshot, and the single scene-wide camera limitation.
Vehicle Standard Input sends values directly to `VehicleController.steerInput`, `throttleInput`, `brakeInput`, and `handbrakeInput`. Its `OnDisable` method resets all four to zero. A custom integration should preserve that zeroing behavior whenever driver ownership ends, including forced stops and interruption paths.
---
# Feel
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/integrations/feel/)
Use the [Feel](https://assetstore.unity.com/packages/tools/particles-effects/feel-183370?aid=1100lGdc) integration to add an `MMF_Player` feedback sequence to an Ultimate Character Controller item use, character damage, item impact, or another deliberate gameplay event without replacing either system.
## Before you begin
- Start with a working Ultimate Character Controller Version 3 character and one working item. Verify the character and item in Play Mode before adding feedback.
- Install [Feel](https://assetstore.unity.com/packages/tools/particles-effects/feel-183370?aid=1100lGdc), add an **MMF Player** component, and build a small feedback sequence that works from Feel's own **Play** control.
- Import the Ultimate Character Controller Feel integration after both products compile. Use **Tools > Opsive > Ultimate Character Controller > Integrations Manager > Available Integrations**, or obtain the current package from the [Opsive Downloads page](https://opsive.com/downloads/).
- Back up the project before replacing an integration package.
The source-audited integration project contains Ultimate Character Controller `3.2.2`, Feel `3.16`, and Unity `2022.3.11f1`. The bridge does not declare a minimum or maximum Feel version. Current Feel documentation describes Feel 6 and still exposes `MMF_Player.PlayFeedbacks`, but that does not prove that every bridge package works unchanged with every later Feel release. Reimport the current bridge after upgrading either product and repeat the tests on this page.
## Prepare the MMF Player
1. Add **MMF Player** to the character, item action GameObject, or a dedicated feedback GameObject.
2. Add and configure the Feel feedbacks that should play together.
3. Disable **Auto Play on Start** and **Auto Play on Enable** when Ultimate Character Controller should be the only trigger. This prevents an automatic Feel play from being mistaken for a successful Ultimate Character Controller connection.
4. Enter Play Mode and use the MMF Player's **Initialization** and **Play** controls. Confirm the complete sequence works before connecting it to Ultimate Character Controller.
5. Keep a direct reference to this component available. The Ultimate Character Controller bridge searches only the same GameObject when **Player** is empty; it does not search children or the scene.
## Play feedback when an item is used
The bridge supplies item-use modules for Shootable, Melee, Magic, and Throwable actions. Each module runs when that action receives its normal Ultimate Character Controller use callback.
1. Select the item and find its **Shootable Action**, **Melee Action**, **Magic Action**, or **Throwable Action** component.
2. Open **Extra Module Group** and select **Add**.
3. Add the module that matches the action and the amount of the Feel sequence that should play:
| Item action | Play the complete MMF Player | Play one feedback |
| --- | --- | --- |
| Shootable | **Play Feedbacks Shootable Module** | **Play Feedback Shootable Module** |
| Melee | **Play Feedbacks Melee Module** | **Play Feedback Melee Module** |
| Magic | **Play Feedbacks Magic Module** | **Play Feedback Magic Module** |
| Throwable | **Play Feedbacks Throwable Module** | **Play Feedback Throwable Module** |
4. Assign the prepared MMF Player to **Player**. Assign it explicitly even when the component is on the same GameObject; this makes ownership clear when the item hierarchy changes.
5. Set **Intensity** to `1` for the normal Feel intensity, then tune it only after the sequence works.
6. For a complete sequence, leave **Revert** disabled for normal forward playback.
7. For one feedback, select it with **Feedback Index**, or set **Feedback Index** to `-1` and enter its exact **Feedback Label**.
Use a complete sequence for a coordinated response such as muzzle flash, camera impulse, sound, and haptics. Use one feedback when the same MMF Player contains several reusable responses and this item needs only one of them.
## Connect damage, impacts, and abilities
The bridge does not add a dedicated Ultimate Character Controller damage, impact, or ability module. Use the event already owned by that Ultimate Character Controller system, or add a small project adapter when the event must be filtered.
### Play feedback when a character takes damage
1. Select the character's **Character Health** component.
2. Open **Events**, then add a listener to **On Damage Event**.
3. Drag the GameObject containing the MMF Player into the listener.
4. Select **MMF Player > PlayFeedbacks()** as a static, parameterless call.
5. Damage the character twice in Play Mode. The sequence should play once for each accepted damage event.
Use **On Death Event** instead when the sequence should run only on death. The Ultimate Character Controller **Damaged Effect** field is not a reliable route with the audited bridge package; the character Effect limitation is described below.
### Play feedback at an item impact
1. Find the Impact Action Group used by the item's hit, projectile, or cast.
2. Add **Impact Unity Event** to that group.
3. In **On Impact Event**, drag the GameObject containing the MMF Player into the listener.
4. Select the parameterless **MMF Player > PlayFeedbacks()** call.
5. Hit a valid target in Play Mode and confirm the feedback plays at the same time as the other impact actions.
This route triggers the MMF Player, but it does not pass Ultimate Character Controller's impact position or strength into the parameterless Feel call. Use a project adapter when the feedback must use `ImpactCallbackContext` to move the player to the contact point or scale its intensity from the hit.
### Play feedback from an ability
Every ability has a **Start Effect** choice, and Ultimate Character Locomotion exposes **Events > On Ability Active Event**. The audited Feel bridge does not provide a working ability-specific adapter:
- Binding `MMF_Player.PlayFeedbacks()` directly to **On Ability Active Event** plays for every ability start and stop because that event reports both the ability and its active state.
- Selecting the bridge's character Effect as **Start Effect** does not replay the Feel sequence in the audited package.
For a production ability, use a small adapter that listens to **On Ability Active Event**, checks the intended ability and `active == true`, and then calls the assigned MMF Player. This keeps one clear trigger and avoids playing the sequence for unrelated abilities or for the stop transition.
## Character Effect boundary
The integration adds **Play Feedbacks** and **Play Feedback** to **Ultimate Character Locomotion > Effects**. In the audited Ultimate Character Controller `3.2.2` bridge, both classes call Feel from the Effect lifecycle `Start()` method. Ultimate Character Controller calls that method once while the character initializes. Later activation through an ability's **Start Effect**, Character Health's **Damaged Effect**, or `TryStartEffect` calls `EffectStarted()` instead, which these integration classes do not override.
As a result, the audited package plays a configured character feedback once at startup and does not play it again when the Effect is activated. Do not use that package's character Effect route for damage or ability feedback. If a newer downloaded bridge changes the callback to `EffectStarted()`, verify one startup, two activations, and one stop in Play Mode before relying on it.
## How it runs
1. During initialization, the bridge uses the assigned **Player** or looks for an MMF Player on the same GameObject. It calls the player's initialization method and disables the Ultimate Character Controller Effect or item module when no player can be resolved.
2. An item-use module receives Ultimate Character Controller's `UseItem` callback for its matching action type.
3. **Play Feedbacks** calls the MMF Player with the item action's Transform position, **Intensity**, and **Revert** choice. **Play Feedback** resolves one feedback by label or index and plays it with the same position and intensity.
4. Damage and impact Unity Events call the MMF Player directly when their owning Ultimate Character Controller system reports the event.
5. The bridge does not stop a running Feel sequence when an item use or ability ends. Configure Feel's own overlap, cooldown, duration, and stop behavior for repeated gameplay triggers.
## Key choices and limitations
| Choice | Use it when | Important consequence |
| --- | --- | --- |
| **Play Feedbacks** | The entire MMF Player is one coordinated gameplay response | Every feedback in the player is requested on each item use. |
| **Play Feedback** by index | The feedback list order is controlled and unlikely to change | Index `0` is the first feedback; reordering the list changes which feedback plays. |
| **Play Feedback** by label | A stable, descriptive Feel label should select the response | In the audited bridge, a valid index overwrites a label match despite the field tooltip. Set **Feedback Index** to `-1` when using **Feedback Label**. |
| **Intensity** `1` | The feedback should play at its authored strength | The audited bridge serializes `-1` as its default and passes it directly to Feel. Many feedbacks multiply their output by this value, so set and test it deliberately. |
| **Revert** disabled | The Feel sequence should use its normal direction | In Feel 3.16 the bridge's Boolean is passed as `forceRevert`, which toggles the player's direction. Enable it only after testing the intended reverse behavior. |
| Ultimate Character Controller Unity Event | Damage or an impact needs a no-code trigger | The parameterless call ignores Ultimate Character Controller's event data. Use an adapter when position, strength, ability identity, or active state matters. |
The supplied integration is local-only glue. Its character Effects are not network synchronized, and its item modules do not opt into Ultimate Character Controller module network synchronization. In a multiplayer project, trigger equivalent feedback for the intended local player or observer through the project's networking layer instead of assuming the bridge replicates it.
## Verify in Play Mode
1. Start with Feel's **Auto Play on Start** and **Auto Play on Enable** disabled. Nothing should play before the chosen Ultimate Character Controller trigger, except the audited character Effect startup behavior described above.
2. Use the item once. Confirm the intended MMF Player or single labeled feedback plays exactly once.
3. Use the item repeatedly. Confirm Feel's cooldown and overlap behavior match the intended rate and that the sequence does not stack unexpectedly.
4. Switch perspective and use the item again. Camera, UI, and haptic feedback should still target the intended local player.
5. For damage, apply two nonlethal hits and one lethal hit. **On Damage Event** should run for each accepted hit; **On Death Event** should run only when health reaches its death state.
6. For an impact, hit a valid target and then miss. The impact feedback should play only for the configured Impact Action Group.
7. For an ability adapter, start and stop the chosen ability and then activate a different ability. The feedback should play only on the intended start transition.
8. Test after death and respawn, item unequip and re-equip, and a scene reload. No stale player reference or duplicate event listener should remain.
9. Make a development build for the target platform and verify any Feel feedback that depends on haptics, render-pipeline features, audio, or a third-party package.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| Unity reports missing `MoreMountains.Feedbacks` or Feel types | Feel may be absent, imported after the bridge, or incompatible with that bridge package | Install and compile Feel first, then import the current Ultimate Character Controller Version 3 integration again. Resolve the first Console error. |
| The Feel modules are missing from the item menu | The integration may not have compiled, or the selected action may not be Shootable, Melee, Magic, or Throwable | Confirm the bridge scripts compile and add the module whose suffix matches the item's action type. |
| The Console says an MMF Player must be assigned | **Player** is empty and no MMF Player exists on the action or character GameObject itself | Assign the MMF Player explicitly. Do not rely on a child or scene-wide search. |
| A sequence plays as soon as Play Mode starts | Feel auto-play may be enabled, or the audited Ultimate Character Controller character Effect may be calling Feel from lifecycle `Start()` | Disable Feel auto-play. Remove the character Effect route and use the intended item or Unity Event trigger. |
| An ability or **Damaged Effect** becomes active but no Feel feedback plays | The audited character Effect does not call Feel from `EffectStarted()` | Use the relevant Ultimate Character Controller Unity Event or a filtered adapter, or install and verify a bridge version that corrects the lifecycle callback. |
| The wrong individual feedback plays | **Feedback Index** may still be valid and therefore override the label in the audited source | Set the correct index, or set it to `-1` and use a unique exact **Feedback Label**. |
| A label cannot be found | The label may be misspelled, duplicated, or the index may be outside the list without a matching label | Use a unique Feel label, preserve its capitalization, and verify it on the assigned MMF Player. |
| The feedback is inverted, silent, or much stronger than expected | **Intensity** may still be `-1`, or **Revert** may be changing direction | Start with **Intensity** `1` and **Revert** disabled, then tune one choice at a time. |
| Damage feedback never runs | The listener may be on the wrong Health component, or the target may be invincible and reject the damage | Bind **Character Health > Events > On Damage Event** on the damaged character and confirm its health value actually changes. |
| Impact feedback runs at the item instead of the contact point | The parameterless MMF Player callback has no impact position | Use an adapter that reads `ImpactCallbackContext.ImpactCollisionData.ImpactPosition` and passes that position to Feel. |
| Every ability start and stop plays the same feedback | The MMF Player is bound directly to the unfiltered **On Ability Active Event** | Replace the direct listener with an adapter that checks the intended ability and the active Boolean. |
| A remote character's feedback is missing or plays on the wrong client | The supplied bridge does not synchronize the Effect or item module | Replicate the gameplay event through the project's network code, then play feedback only for the correct local observer. |
## Related pages
- [Integrations](https://opsive.com/support/documentation/ultimate-character-controller/integrations/)
- [Character Effects](https://opsive.com/support/documentation/ultimate-character-controller/character/effects/)
- [Abilities](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/)
- [Health](https://opsive.com/support/documentation/ultimate-character-controller/attributes/health/)
- [Item Actions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/)
- [Impact Actions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/impact-actions/)
- [Events](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/)
- [Feel MMF Player documentation](https://feel-docs.moremountains.com/mmf-player.html)
## Developer reference
The bridge consists of `FeelUtility`, two Ultimate Character Controller `Effect` subclasses, and eight item modules:
- `PlayFeedbacks` and `PlayFeedback` derive from Ultimate Character Controller `Effect`.
- The complete-sequence item classes derive from the corresponding `ShootableExtraModule`, `MeleeExtraModule`, `MagicExtraModule`, or `ThrowableExtraModule` and implement `IModuleUseItem`.
- The single-feedback item classes use the same four module bases and callback.
`FeelUtility.InitializePlayer` uses the assigned `MMF_Player`, otherwise calls `GetComponent()` on the owning Ultimate Character Controller GameObject, then calls `Initialization()`. `PlayFeedbacks` forwards the position, intensity, and revert Boolean to `MMF_Player.PlayFeedbacks`. `PlayFeedback` resolves a cached `MMFeedback` from the player's list and calls `MMFeedback.Play(position, intensity)`.
The audited single-feedback resolver checks **Feedback Label** first but then assigns the indexed feedback whenever **Feedback Index** is in range. This is why `-1` is required for label-only selection. The audited Effect classes override `Start()` instead of `EffectStarted()`, which is why `TryStartEffect`, ability **Start Effect**, and Character Health **Damaged Effect** do not replay them.
Useful Ultimate Character Controller event boundaries are `Health.OnDamageEvent`, `ImpactUnityEvent.OnImpactEvent`, and `UltimateCharacterLocomotion.OnAbilityActiveEvent`. The last event supplies `(Ability ability, bool active)`, so an ability-specific adapter should require both the target ability and `active == true`. An impact adapter can read `ImpactCallbackContext.ImpactCollisionData.ImpactPosition` and `ImpactStrength` before calling the MMF Player with project-defined intensity rules.
---
# Final IK
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/integrations/final-ik/)
Use the [Final IK](https://assetstore.unity.com/packages/tools/animation/final-ik-14290?aid=1100lGdc) integration when RootMotion should solve the character's limbs, aim, look direction, grounding, or object interactions while Ultimate Character Controller continues to decide when those actions occur.
## Before you begin
- Start with a working Ultimate Character Controller Version 3 character. Confirm locomotion, animation, the camera or other look source, and one representative item or ability in Play Mode before replacing its IK.
- Install [Final IK](https://assetstore.unity.com/packages/tools/animation/final-ik-14290?aid=1100lGdc) before importing the Ultimate Character Controller integration. The bridge compiles against RootMotion types and cannot compile without them.
- Commit or back up the project. You will remove **Character IK** from the animated model and replace it with **Final IK Bridge**.
- Configure each RootMotion solver with the [Final IK documentation](https://www.root-motion.com/finalikdox/html/pages.html). The bridge connects Ultimate Character Controller to those solvers; it does not build or validate the Final IK rig for you.
The Ultimate Character Controller Version 3 integration catalog currently lists Final IK, but it does not declare a minimum or maximum Final IK version. The source snapshot verified for this page uses Ultimate Character Controller `3.2.0`, Final IK `2.2`, and Unity `2021.3.0f1`; the current Asset Store release is newer. Treat those numbers as an audited snapshot, not a compatibility matrix. After upgrading either product, import the current bridge and repeat the isolated Play Mode checks below before updating production scenes.
## Install and connect the bridge
1. Install Final IK and wait for Unity to compile without errors.
2. Open **Tools > Opsive > Ultimate Character Controller > Integrations Manager**, select **Available Integrations**, and find **Final IK**.
3. Use the **Integration** action to follow the current distribution route. If it opens the documentation route, sign in to the [Opsive Downloads page](https://opsive.com/downloads/) and obtain the Ultimate Character Controller Version 3 Final IK integration.
4. Import the integration after Final IK, then resolve every Console compile error before changing the character.
5. Select the animated character-model GameObject that has the **Animator** and **Animator Monitor** components. Do not add the bridge only to the Ultimate Character Controller locomotion root when the Animator is on a child model.
6. Remove **Character IK** from that model. Leave one IK provider on a model so items and abilities do not select competing owners.
7. Add **Final IK Bridge** to the same model GameObject.
8. Add and configure the RootMotion components needed for the scenarios in the next section. **Full Body Biped IK**, **Look At IK**, **Aim IK**, and **Interaction System** must be on the same GameObject as **Final IK Bridge** because the bridge discovers them there.
9. Repeat the replacement on every animated model that Ultimate Character Controller can activate. Configure only the Final IK solvers supported by that model's rig.
## Choose the Final IK components
Add only the systems the character needs:
| Goal | Components | What the bridge supplies |
| --- | --- | --- |
| Position an off-hand on an equipped item or apply Ultimate Character Controller limb offsets | **Full Body Biped IK** | Assigns the non-dominant hand and elbow targets, forwards final hand and foot adjustments, and updates the solver after animation. |
| Follow the camera, an AI look source, or a Look At ability target | **Look At IK** | Moves a runtime target from Ultimate Character Controller's current look source or explicit look target. |
| Aim an equipped item while Aim or Use is active | **Aim IK** | Assigns the active item transform and supplies the animated aim axis while the item is aiming or in use. |
| Place feet on uneven surfaces | **Full Body Biped IK** and **Grounder Full Body Biped** | The bridge updates the Full Body Biped solver. Grounder remains a Final IK-owned layer that modifies that solver through its callbacks. |
| Reach a button, handle, or other ability target | **Full Body Biped IK** and **Interaction System** | Maps an Ultimate Character Controller Ability IK Target to a Final IK Interaction Object and starts or stops the matching effector interaction. |
**Interaction System** requires **Full Body Biped IK**. The bridge does not directly adapt unrelated Final IK solvers such as VRIK, Biped IK, or Limb IK; those need their own project-specific ownership and testing.
## Configure the bridge
Keep the normal Ultimate Character Controller-owned route simple:
- Leave **Set Look At Target** enabled when Ultimate Character Controller should drive **Look At IK** from its current look source or a Look At ability. Leave **Set Aim Target** enabled when Ultimate Character Controller should drive **Aim IK** for equipped items.
- Assign **Head** when using Look At IK or Aim IK without Full Body Biped IK. When Full Body Biped IK is present, the bridge obtains the head from its biped references.
- Use **Look At Offset** to adjust where the body looks without changing the camera. **Look At Adjustment Speed** controls how quickly the generated target follows the requested direction.
- Keep **Active Look At State Name** set to `LookAt` when the existing Ultimate Character Controller state should activate for an explicit target, or use the exact name of the project's replacement state.
- Adjust **Animated Aim Direction** when the weapon animation's authored forward axis is not the model's forward axis. Start at `(0, 0, 1)` and change it only after observing a consistent aiming offset in Play Mode.
- Use **Position Spring** and **Rotation Spring** for Ultimate Character Controller secondary forces such as item recoil. Tune the visible response after the base pose and Final IK references are correct.
Disable **Set Look At Target** or **Set Aim Target** only when a custom system intentionally owns that Final IK target. That changes solver ownership and update order, so verify it as a separate integration rather than combining both owners by accident.
## Configure an interaction target
Use this setup when the Interact ability should place a hand or another limb on an object:
1. On the animated character model, add and configure **Full Body Biped IK**, **Interaction System**, and **Final IK Bridge** on the same GameObject.
2. On the exact target GameObject that represents the contact point, add Ultimate Character Controller's **Ability IK Target** and Final IK's **Interaction Object**. The bridge looks for the Interaction Object on the same GameObject as the target transform.
3. Set the Ability IK Target **Goal** to the intended hand, elbow, foot, or knee. Configure the Interaction Object's effector target and weight curves using the Final IK Interaction System workflow.
4. Add the target beneath the scene object's **Interactable** and test the complete Interact workflow: detection, optional Move Towards alignment, limb contact, object response, and release.
The bridge starts the Final IK interaction when Ultimate Character Controller activates the Ability IK Target and stops that effector when Ultimate Character Controller clears it. Ultimate Character Controller still owns ability timing; Final IK owns the resulting limb solve.
## How ownership works
**Final IK Bridge** replaces Ultimate Character Controller's built-in **Character IK** component as the model's IK provider. Ultimate Character Controller continues to own the gameplay intent: the current look source, equipped item, Aim and Use state, ability IK target, secondary forces, death, respawn, and active character model.
The bridge converts that intent into Final IK targets and updates the supported solvers after animation each frame. When the bridge owns the target, it disables the normal component update for Full Body Biped IK, Look At IK, or Aim IK as appropriate and invokes the solver itself. A disabled Final IK component checkbox during Play Mode can therefore be expected; do not re-enable it solely because the bridge is updating it manually.
RootMotion still owns solver references, weights, constraints, Interaction Object curves, Grounder configuration, and the final bone calculations. This division is why a clean Ultimate Character Controller setup and a separately valid Final IK rig are both required.
## Verify in Play Mode
1. Enter Play Mode in a small scene containing one character, one configured model, and only the Final IK systems needed for the test.
2. Confirm the Console has no missing RootMotion types, missing head error, invalid biped references, or Interaction System warnings.
3. Move and rotate the camera, or update the AI look source. With Look At IK configured, confirm the head and body follow smoothly without the camera direction changing.
4. Equip an item with a non-dominant hand target. With Full Body Biped IK configured, confirm the second hand reaches the item and releases correctly on unequip.
5. Start and stop Aim and Use. With Aim IK configured, confirm the solver follows the item only during the intended actions and returns to the animated pose afterward.
6. Trigger an Interact object with an Ability IK Target and Interaction Object. Confirm the intended limb reaches the contact point, the object responds once, and the limb releases when Interact finishes.
7. If Grounder is used, walk over a flat surface, a slope, and stairs. Confirm both feet settle without pulling the pelvis or legs into an unstable pose.
8. Test death and respawn, every perspective or model switch used by the project, and one scene reload. The active model should regain the same IK behavior without duplicate targets or solvers.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| Unity reports missing `RootMotion.FinalIK` types after import. | Final IK is absent, imported after the bridge, or the imported bridge is not for Ultimate Character Controller Version 3. | Install Final IK first, then import the current Ultimate Character Controller Version 3 integration again and resolve the first Console error. |
| The bridge reports that no head is specified or remains inactive. | **Look At IK** or **Aim IK** is present without **Head** or valid Full Body Biped IK head references; the character may also have no attached look source. | Assign **Head** or repair the biped references, then confirm the player camera or AI look source attaches to the character. |
| The pose jitters or limbs are solved twice. | **Character IK** may still be present, more than one bridge may be active on the model, or a custom script may also own the Look At/Aim target. | Keep one CharacterIKBase owner per active model. Remove the competing component or return **Set Look At Target** and **Set Aim Target** to the Ultimate Character Controller-owned route. |
| The off-hand does not reach the equipped item. | Check the Full Body Biped IK hand references, the active model, and the item's non-dominant hand and elbow targets. | Repair the biped references and item targets, then retest equip and unequip on the model that is actually active. |
| Aim points consistently away from the reticle. | The weapon animation's forward axis does not match **Animated Aim Direction**, or Aim IK is not using the active item transform. | Correct the Aim IK setup, then tune **Animated Aim Direction** from its `(0, 0, 1)` starting value. |
| Look At IK does not follow the camera or AI. | Check **Set Look At Target**, **Head**, the attached look source, and whether the active model contains the bridge. | Restore the Ultimate Character Controller-owned target, assign the head, attach a working look source, and add the bridge to every switchable model that needs IK. |
| An Interact ability runs but the limb does not reach the object. | The model may lack **Interaction System** or **Full Body Biped IK**, or the contact GameObject may not contain both **Ability IK Target** and **Interaction Object**. | Put the required character components on the bridge GameObject and both target components on the same contact GameObject, then configure the Interaction Object's effector and curves. |
| Grounder has no effect. | **Grounder Full Body Biped** may not reference the model's Full Body Biped IK solver, or its Final IK grounding setup may be incomplete. | Assign the correct Full Body Biped IK component and validate Grounder independently on flat ground before testing it through the bridge. |
| IK works until the character model changes. | Only the original model contains the replacement CharacterIKBase and RootMotion solvers. | Repeat the bridge and solver setup on every model used by Model Manager, then verify each switch in Play Mode. |
## Related tasks
- [Integrations](https://opsive.com/support/documentation/ultimate-character-controller/integrations/) explains the shared install, isolation, and upgrade workflow.
- [Inverse Kinematics](https://opsive.com/support/documentation/ultimate-character-controller/inverse-kinematics/) covers the built-in Character IK route that this integration replaces.
- [Interact](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/detect-object-ability-base/interact/) configures Interactable objects, Ability IK Targets, and interaction timing.
- [Look At](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/detect-object-ability-base/look-at/) supplies an explicit Ultimate Character Controller look target.
- [Model Switch](https://opsive.com/support/documentation/ultimate-character-controller/character/model-switch/) explains active character-model changes that require matching IK setup.
- [Springs](https://opsive.com/support/documentation/ultimate-character-controller/animation/springs/) explains the spring response used by secondary IK forces.
## Developer and source reference
`Opsive.UltimateCharacterController.Integrations.FinalIK.FinalIKBridge` derives from `CharacterIKBase` and reports `UseOnAnimatorIK` as false. It discovers `FullBodyBipedIK`, `LookAtIK`, `AimIK`, and `InteractionSystem` with `GetComponent` on its own GameObject, creates a runtime target for the Ultimate Character Controller-owned look and aim route, and updates supported solvers from `LateUpdate`.
The bridge listens for Ultimate Character Controller look-source, Aim, Use, equip, unequip, secondary-force, death, respawn, and Animator-snap events. It assigns the non-dominant item hand to Full Body Biped IK, maps Ability IK Target goals to Final IK effectors, disables itself on death, and resumes on respawn. Grounder Full Body Biped and Interaction System attach to the Full Body Biped solver's callbacks, so the bridge's manual solver update still drives those Final IK layers.
The released Ultimate Character Controller package inspected for this page is `3.2.0`. The separate Opsive bridge sample contains Final IK `2.2` and was saved with Unity `2021.3.0f1`; the [Final IK Asset Store listing](https://assetstore.unity.com/packages/tools/animation/final-ik-14290?aid=1100lGdc) currently reports version `2.5`. Neither the current Opsive integration catalog nor the bridge source declares a broader semantic compatibility range. Use the current integration package, keep the tested product pair recorded in the project, and repeat compilation plus the Play Mode checklist after either dependency changes.
---
# FMOD
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/integrations/fmod/)
Use the [FMOD](https://assetstore.unity.com/packages/tools/audio/fmod-for-unity-2-03-311497?aid=1100lGdc) integration when Ultimate Character Controller should keep choosing and timing gameplay sounds while FMOD owns the event, spatialization, routing, and final playback.
## Before you begin
- Start with a working Ultimate Character Controller Version 3 scene. Confirm at least one ability, item, health, footstep, or impact sound through the normal Opsive audio workflow before changing the scene's playback module.
- Install and configure [FMOD for Unity](https://assetstore.unity.com/packages/tools/audio/fmod-for-unity-2-03-311497?aid=1100lGdc) first. In Unity, use **FMOD > Edit Settings** to connect the built banks, **FMOD > Refresh Banks** after rebuilding them, and **FMOD > Event Browser** to confirm the intended events are available.
- Keep the FMOD for Unity integration on the same major line as the FMOD Studio project. Follow the [FMOD for Unity user guide](https://www.fmod.com/docs/2.03/unity/user-guide.html) for plugin, bank, platform, and licensing setup before troubleshooting the Ultimate Character Controller bridge.
- Commit or back up the project. Assigning the FMOD module changes the playback owner for every sound routed through the scene's Opsive Audio Manager.
The released bridge snapshot verified for this page uses Ultimate Character Controller `3.3.3`, Opsive Shared `2.1.0`, FMOD for Unity `2.02.33`, and Unity `2022.3.62f3`. The current public FMOD line is `2.03`, but the Opsive package does not declare a semantic minimum or maximum. Treat the snapshot as an audited configuration, not a compatibility matrix. For FMOD `2.03`, import the current bridge after FMOD and pass the isolated compilation and Play Mode checks below before changing a production scene.
## Install the Ultimate Character Controller bridge
1. Install FMOD for Unity and configure its banks. Resolve all FMOD initialization, bank-loading, and event-browser errors first.
2. Sign in to [Opsive Downloads](https://opsive.com/downloads/) and download the FMOD integration. It is not included in the base product's Integrations folder before this download.
3. Import the downloaded package after FMOD has compiled. Importing it creates `Assets/Opsive/UltimateCharacterController/Integrations/FMOD` in the project.
4. Confirm that Unity imported `FMODAudioManagerModule.cs` and `FMODAudioManagerModule.asset`, then wait for compilation to finish.
5. If the scene does not have the standard manager object, open **Tools > Opsive > Ultimate Character Controller > Setup Manager**, select **Manager Setup**, and use **Add Managers**.
6. Select the scene's **Game** object and find its **Audio Manager** component.
7. Assign `FMODAudioManagerModule.asset` to **Audio Manager Module**.
8. Select the module asset. Assign **Default Audio Config** only when an Opsive audio request without its own Audio Config should use that shared set of placeholder clips.
9. Add at least one direct event mapping as described below, save the scene, and test that mapping before converting the rest of the project's sounds.
The included asset is the normal starting point. To maintain a separate mapping asset for another project or test scene, use **Assets > Create > Opsive > Audio > FMOD Audio Manager Module** and assign the new asset to **Audio Manager Module**.
## Map Ultimate Character Controller clips to FMOD events
The bridge preserves the Opsive Audio Clip Set and Audio Config workflow, but it uses each selected Unity AudioClip as an identifier. It does not play that clip's waveform.
For a direct mapping:
1. Create or reuse an Opsive Audio Config and add one placeholder AudioClip for each sound choice.
2. Select `FMODAudioManagerModule.asset` and expand **Audio Clip Event Mappings**.
3. Add an element, assign the placeholder to **Audio Clip**, and choose the FMOD event in **Event Reference**.
4. Repeat for every placeholder used by the test Audio Config.
5. Assign the Audio Config to the Ultimate Character Controller feature and trigger it in Play Mode.
Direct mappings are the safest route because the placeholder name and FMOD event hierarchy can change independently while the event reference remains explicit.
### Use a naming fallback
If a placeholder has no direct mapping, the module joins **Default Event Path Prefix** and `AudioClip.name`. The included default is `event:/`, so an AudioClip named `Footstep` resolves to `event:/Footstep`.
For a shared folder, set the prefix to a path such as `event:/Characters/Footsteps`. A placeholder named `Stone` then resolves to `event:/Characters/Footsteps/Stone`; the module inserts the missing slash when needed.
Use this fallback only when names and folders follow a controlled convention. A renamed AudioClip, a moved FMOD event, or a missing bank can make the path invalid without changing the Ultimate Character Controller Audio Config. Use a direct mapping for nested event structures and sounds maintained by different teams.
### Keep Opsive clip selection
Audio Config still chooses the placeholder before the bridge resolves an event:
- **Random** selects a random mapped placeholder.
- **Sequence** advances through the mapped placeholders in order.
- **Index** selects the placeholder at the current Audio Config index.
This lets existing ability, item, health, surface, and impact data keep its selection logic. The corresponding FMOD events own the actual audio content and their internal variations.
## How audio is routed
The scene **Audio Manager** remains the entry point used by Ultimate Character Controller. The FMOD module replaces its normal Unity AudioSource playback for every request that reaches that manager.
- Ultimate Character Controller owns when to request or stop a sound, which Audio Config or AudioClip is selected, and the supported volume, pitch, and delay overrides.
- The module resolves the placeholder to an FMOD event, creates an event instance, starts it immediately or after the requested delay, and tracks it against the originating GameObject.
- For a 3D FMOD event, normal playback attaches the instance to the GameObject so it follows the character, item, or moving object. Playback at a world position sets that initial position instead.
- A 2D FMOD event ignores the supplied GameObject or world position for spatial placement.
- FMOD owns event instruments, looping, parameters, buses, snapshots, effects, spatial behavior, and bank content.
- When Ultimate Character Controller stops tracked audio, **Allow Fadeout** chooses FMOD's fade-out stop mode; disable it only when that integration-wide stop should be immediate.
- **Cleanup Interval** controls how often completed instances are released. Keep the included `0.5` second value unless profiling shows a reason to change it; the Inspector prevents values below `0.1` seconds.
Keep one intended Audio Manager in the scene. This bridge is a scene-wide module, not a per-clip switch between FMOD and Unity AudioSource playback. If a particular system must keep using Unity audio, call that system separately or implement and test a project-owned hybrid module.
## Current limitations
The source-verified bridge forwards only Opsive clip selection, volume, pitch, and delay. Configure the following behavior in FMOD rather than expecting Unity AudioSource settings to transfer:
- **Audio Source Prefab**, **Output Override** or an Audio Mixer Group, **Stereo Pan**, **Spatial Blend**, and **Reverb Zone** do not configure the FMOD event.
- **Loop Override** does not make an event loop. Author looping in FMOD and ensure the Ultimate Character Controller feature stops the tracked event when the action ends.
- **Share Audio Source**, **Replace Previous Audio Source**, and **Copy Existing Audio Source Properties** describe the Unity AudioSource pool and do not control FMOD event instances.
- `PlayResult.AudioSource` is empty because FMOD playback does not return a Unity AudioSource. The module can still stop a matching tracked event through the Audio Config or returned PlayResult data.
- FMOD parameters, buses, snapshots, programmer sounds, and custom emitter behavior are not populated automatically from an Opsive Audio Config. Use FMOD components or project code for those features.
- Bank loading, platform binaries, listener setup, and FMOD Studio content remain FMOD responsibilities. The Ultimate Character Controller package supplies only the Audio Manager module.
When two identical events overlap on the same GameObject, stopping by Audio Config stops all tracked events for that config. Stopping by PlayResult stops one tracked event matching its clip and config; the PlayResult does not expose an FMOD event handle.
## Verify in Play Mode
1. Open a small scene with one **Audio Manager**, one Ultimate Character Controller character, one Audio Config, and one directly mapped FMOD event.
2. Enter Play Mode and confirm the Console has no missing `FMODUnity` types, bank-loading errors, invalid event-reference errors, or missing-mapping warnings.
3. Trigger the Ultimate Character Controller feature several times. Confirm the mapped event plays once per request and Random, Sequence, or Index chooses the expected placeholder.
4. Move the source GameObject while a 3D event plays. Confirm the sound follows it. Trigger a separate sound at a world position and confirm that event remains at the requested position.
5. Test one 2D event and confirm that moving the character does not spatialize it.
6. Apply distinct volume, pitch, and delay overrides in the Audio Config. Confirm those three values reach the FMOD event.
7. Start an event that Ultimate Character Controller later stops. Confirm **Allow Fadeout** produces the intended release and that the event does not continue after its gameplay owner ends.
8. Test an ability, item, health sound, footstep, and impact used by the project. Confirm every placeholder resolves through FMOD and that any default Unity AudioSource on the manager remains idle rather than playing the bridged requests.
9. Build for the target platform and verify bank inclusion, native FMOD libraries, listener behavior, and spatial playback outside the Editor.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| Unity reports missing `FMODUnity` types after importing the bridge. | FMOD for Unity is absent, failed to compile, or was imported after the Ultimate Character Controller package. | Install and configure FMOD first, then reimport the current Ultimate Character Controller Version 3 `FMOD.unitypackage` and resolve the first Console error. |
| The Console reports `[FMOD] No event mapping was found for AudioClip 'SomeClip'`. | The placeholder has no valid direct mapping and the fallback path does not resolve to a loaded event. | Add the clip under **Audio Clip Event Mappings**, or correct **Default Event Path Prefix**, the AudioClip name, and the bank content. |
| An Event Reference is assigned but nothing plays. | The event may be absent from loaded banks, the FMOD plugin and Studio project may use different major lines, or FMOD may have failed to initialize. | Use **FMOD > Refresh Banks** and **FMOD > Event Browser**, match the FMOD major line, and resolve FMOD's first initialization or bank error. |
| Every request is silent after assigning the module. | **Audio Manager Module** may reference the wrong asset, or the selected Audio Config may contain no placeholder clips. | Assign the included `FMODAudioManagerModule.asset`, add mapped placeholders, and test one direct mapping in isolation. |
| A sound plays in 2D when it should follow the character. | The FMOD event itself is 2D; Unity **Spatial Blend** is not forwarded. | Make the event 3D in FMOD, rebuild and refresh the banks, then repeat the moving-GameObject test. |
| Volume or pitch changes, but pan, mixer, reverb, spatial blend, or looping does not. | Those Unity AudioSource settings are outside the module's forwarded values. | Author the behavior in the FMOD event, bus, or snapshot. Use Opsive overrides only for volume, pitch, and delay. |
| A looping event continues after its ability or item stops. | Looping is FMOD-owned and the Ultimate Character Controller feature may not issue a matching stop request. | Ensure the feature retains and stops the matching Audio Config or PlayResult, and configure the event's FMOD release behavior. |
| The wrong event plays when using the fallback. | Another event path may share the clip name, or **Default Event Path Prefix** points to the wrong folder. | Use a direct **Event Reference**, or make the prefix and placeholder naming convention unambiguous. |
| Audio works in the Editor but not in a build. | Banks or the target platform's native FMOD libraries may be missing, or the bank source may not be included by CI. | Follow the FMOD platform and build guidance, include the built banks and platform package, and test a development build before changing Ultimate Character Controller mappings. |
## Related tasks
- [Audio](https://opsive.com/support/documentation/ultimate-character-controller/audio/) explains Audio Clip Sets, Audio Config selection, and the default Unity AudioSource module that this integration replaces.
- [Integrations](https://opsive.com/support/documentation/ultimate-character-controller/integrations/) covers the shared install, isolation, upgrade, and build workflow.
- [Character Foot Effects](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/character-foot-effects/) uses Audio Config assets for footsteps selected by the Surface System.
- [Health](https://opsive.com/support/documentation/ultimate-character-controller/attributes/health/) exposes damage, healing, and death audio that can route through this module.
- [Item Actions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/) describes the action modules that request item audio.
- [Master Audio](https://opsive.com/support/documentation/ultimate-character-controller/integrations/master-audio/) is the alternative scene-wide audio backend integration.
## Developer and source reference
`Opsive.Shared.Integrations.FMOD.FMODAudioManagerModule` derives from `AudioManagerModule`. The included source and asset are packaged at `Assets/Opsive/UltimateCharacterController/Integrations/FMOD/`; the create menu is **Assets > Create > Opsive > Audio > FMOD Audio Manager Module**.
The module resolves direct `AudioClip` to `FMODUnity.EventReference` mappings first, then calls `RuntimeManager.PathToEventReference` for the prefix-and-name fallback. It queries whether the event is 3D, attaches 3D instances with `RuntimeManager.AttachInstanceToGameObject`, applies volume and pitch, schedules delay through the Opsive Scheduler, and tracks instances per GameObject for stop and cleanup. Finished events are released on the configured cleanup interval, and instances associated with destroyed GameObjects are stopped and released.
The released source snapshot inspected for this page contains Ultimate Character Controller `3.3.3`, Opsive Shared `2.1.0`, FMOD for Unity `2.02.33`, and Unity `2022.3.62f3`. FMOD's [current Unity documentation](https://www.fmod.com/docs/2.03/unity/api.html) covers the `2.03` line and requires the FMOD for Unity major line to match the FMOD Studio project. The Opsive bridge has no declared cross-version guarantee, so record the tested FMOD/Ultimate Character Controller pair and rerun compilation, event resolution, stop behavior, and target-platform builds after either dependency changes.
---
# FPS Mesh Tool
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/integrations/fps-mesh-tool/)
Use [FPS Mesh Tool](https://assetstore.unity.com/packages/tools/modeling/fps-mesh-tool-28006?aid=1100lGdc) when a third-person skinned character mesh should be processed into a first-person-compatible prefab for an Ultimate Character Controller character that needs separate first-person rendering or body-part visibility.
## Prepare the source character
1. Back up the project and keep the unmodified source model and prefab.
2. Verify the source rig, Avatar, materials, blend shapes, and Animator in a normal Unity scene.
3. Build and test the Ultimate Character Controller character in third person before processing the mesh.
4. Open **Window > FPS Mesh Tool** and follow the tool's current workflow to create its processed prefab and generated mesh/material assets.
FPS Mesh Tool owns mesh processing. Ultimate Character Controller owns the character hierarchy, First Person Objects, Item Slots, camera, States, and perspective switching. Do not process the only copy of a production prefab.
## Connect the processed result to Ultimate Character Controller
1. Build or update the Ultimate Character Controller character with **First Person** or **Both** perspective support.
2. Put the processed first-person result under the character's **First Person Objects** hierarchy according to the FPS Mesh Tool integration workflow.
3. Match Item Slot IDs with the Character Item prefabs and the visible arms/body hierarchy.
4. Configure the intended first-person materials, shadows, hidden body parts, and first-person camera layers.
5. Build one simple item and verify equip, use, perspective switch, death, and respawn before converting the full loadout.
The current Ultimate Character Controller catalog routes to a provider video for this integration. Treat FPS Mesh Tool's installed UI and the package version used in the project as the authority for its processing options; Ultimate Character Controller does not ship the mesh-processing source in its integration folder.
## Verify in Play Mode
1. Switch between first and third person while idle and moving.
2. Confirm the first-person result has no missing renderer, doubled body, exposed hidden faces, pink material, or incorrect shadow.
3. Equip and use one item and confirm arms, item, and Animator remain aligned.
4. Test crouch, jump, camera pitch, death, and respawn for clipping or stale renderer state.
5. Make a target-platform build to verify generated meshes and materials are included.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| Body parts appear twice in first person. | Check the original third-person renderer and processed first-person renderer visibility. | Give each perspective one intended visible renderer path. |
| The item or arms are offset. | Check First Person Objects hierarchy, Item Slot ID, Avatar, and Animator Controller. | Rebuild the hierarchy with matching slots and align the visible item under the correct first-person parent. |
| Materials are pink or shadows are wrong. | Check active render pipeline and the generated material/shader route. | Convert or regenerate materials for the active pipeline and retest in a build. |
| A later model import breaks the processed prefab. | Check whether the source mesh, bones, or generated assets were replaced. | Preserve generated assets and rerun the tool deliberately from the updated source model. |
## Related pages
- [Character Creation](https://opsive.com/support/documentation/ultimate-character-controller/character/character-creation/)
- [Common Character Setups](https://opsive.com/support/documentation/ultimate-character-controller/character/character-creation/common-setups/)
- [First Person Perspective Items](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/first-person-perspective/)
- [Item Creation](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-creation/)
---
# High Definition Render Pipeline
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/integrations/high-definition-render-pipeline/)
Use the High Definition Render Pipeline (HDRP) support package when an Ultimate Character Controller Version 3 project runs in HDRP, especially when first-person arms and items must remain visible near walls without a second camera.
## Before you begin
- Back up or commit the project. Activating HDRP and converting materials can change many project assets.
- Install a released Ultimate Character Controller Version 3 package. Its Installer requires Unity 2021.3 or newer.
- Use the HDRP version supplied for the chosen Unity Editor. Unity couples Scriptable Render Pipeline major versions to Editor versions; do not select an arbitrary HDRP version because Ultimate Character Controller's minimum Unity version is satisfied.
- Make the character, Camera Controller, input, and one representative item work before converting the project. This gives you a known result to compare after the render-pipeline change.
The audited Ultimate Character Controller `3.2.0` source is in a Unity `2022.3.62f3` project, and the bundled HDRP shaders identify SRP `14.0.8`. Setup Manager does not enforce a maximum HDRP version: it detects HDRP's `CustomPassVolume` type and then imports the bundled support package. Treat a successful import as package detection, not as proof that an otherwise untested Unity, HDRP, and Ultimate Character Controller combination is compatible.
## Convert the project before importing Ultimate Character Controller support
Convert the base project first, then add the Ultimate Character Controller-specific assets. This keeps Unity's broad material conversion separate from the small Ultimate Character Controller support import.
1. In **Window > Package Manager**, install **High Definition RP** for the current Unity Editor.
2. Assign the HDRP Asset required by that Unity version and complete Unity's HDRP configuration checks. In HDRP 14, open **Window > Rendering > HD Render Pipeline Wizard**, select **HDRP**, and select **Fix All**.
3. Convert compatible Built-in Render Pipeline materials with **Edit > Rendering > Materials > Convert All Built-in Materials to HDRP**, or convert a controlled selection with **Convert Selected Built-in Materials to HDRP**.
4. Repair custom shaders and materials manually. Unity's converter does not convert every custom shader, particle shader, height-mapped material, or read-only package material.
5. Open a representative scene and confirm that its environment, character, items, effects, and UI render without pink materials or shader errors before importing the Ultimate Character Controller HDRP support package.
Follow Unity's [HDRP 14 conversion guide](https://docs.unity3d.com/Packages/com.unity.render-pipelines.high-definition@14.0/manual/Upgrading-To-HDRP.html) when using Unity 2022.3. For another Unity release, use the matching HDRP manual because menu labels and upgrade tools can change.
## Import the HDRP support package
1. Open **Tools > Opsive > Ultimate Character Controller > Setup Manager** and select **Project**.
2. Under **Render Pipeline**, select **HDRP** and select **Import**. If HDRP has not compiled, Setup Manager shows **HDRP Not Imported** and does not import the integration.
3. Confirm that `Assets/Opsive/UltimateCharacterController/Integrations/HDRP` contains **Overlay Pass**, **InvisibleShadowCasterHDRP**, and the supplied HDRP shader assets.
4. Drag **Overlay Pass** into the gameplay scene. The prefab contains a Global **Custom Pass Volume** that draws the Overlay layer, so keep one active instance in the loaded scene set rather than adding one per character or camera.
For a new project, **Update Buttons, Layers, and Render Pipeline** can import support for the already-active pipeline as part of the initial project update. Use the explicit **Render Pipeline > HDRP > Import** route when converting an existing project or reinstalling the support assets.
## Configure first-person overlay rendering
1. Select the camera with **Camera Controller** and expand **View Types**.
2. Select a first-person View Type, such as **First Person Combat**, and expand **Rendering**.
3. Set **Overlay Render Type** to **Render Pipeline**.
4. Keep **First Person Culling Mask** on the layer used by the first-person arms and items. The supplied setup uses **Overlay**.
5. Confirm that those first-person Renderers are on the same layer and that the normal scene **Culling Mask** does not render that layer as regular scene geometry.
Changing between **Second Camera** and **Render Pipeline** updates the other first-person View Types on the same Camera Controller. In **Render Pipeline** mode, Ultimate Character Controller removes the generated child first-person camera and temporarily adds **First Person Culling Mask** to the main camera while first person is active. The **Overlay Pass** then draws those objects with cleared depth so nearby scene geometry does not cut through them.
## Match the renderer and material setup
| Area | HDRP requirement | Expected result |
| --- | --- | --- |
| First-person arms and items | HDRP-compatible materials, Renderers on the Overlay layer, and **Cast Shadows** set to **Off** | The overlay remains visible near walls without adding a duplicate set of shadows. |
| Both first- and third-person perspectives | **Perspective Monitor > Invisible Material** uses **InvisibleShadowCasterHDRP** | The hidden third-person mesh can keep its intended shadow while the first-person mesh supplies the visible arms and item. |
| First-person-only character | Apply **InvisibleShadowCasterHDRP** to the third-person head, arms, body, or item Renderers that must be hidden | The first-person camera does not see unwanted third-person geometry. |
| Object Fader | The material supports transparency and **Color Property Name** matches its alpha-bearing color; standard HDRP materials use `_BaseColor` | Character and obstruction fades change alpha instead of turning pink or remaining opaque. |
| Surface Manager texture lookup | **Main Texture Property Name** matches the material's base texture; standard HDRP Lit uses `_BaseColorMap` | Texture-based Surface Type lookup reads the intended texture. |
| Ultimate Character Controller Surface Effect decals | A prefab with **MeshFilter**, **Renderer**, and an HDRP-compatible material | Impact marks and footprints spawn, fit the hit surface, and can be weathered by **Decal Manager**. |
The current Setup Manager initializes non-Built-in projects with `_BaseColor` for Object Fader and `_BaseMap` for Surface Manager. `_BaseMap` is the normal URP base texture name, while standard HDRP Lit uses `_BaseColorMap`; update **Surface Manager > Main Texture Property Name** when using HDRP Lit. Custom shaders can use different property names, so inspect the material rather than copying either value blindly.
Object Fader also needs its surface-mode fields to match the shader. Setup Manager supplies `_Surface` and `1` for non-Built-in pipelines, but standard HDRP shaders expose different internal surface properties. Follow the material-focused checks on [Object Fader](https://opsive.com/support/documentation/ultimate-character-controller/camera/object-fader/) and verify an actual fade before applying the settings to every material.
Ultimate Character Controller's **Decal Manager** does not spawn HDRP **Decal Projector** components. It places and pools a mesh decal prefab, checks the mesh corners against the hit surface, and fades its Renderer material. An HDRP Decal Projector prefab is therefore not a drop-in replacement for a prefab assigned to **Surface Effect > Decals**. Use an HDRP-compatible mesh material, then test both spawning and weathering.
## Verify in Play Mode
1. Enter Play Mode in a scene containing one active **Overlay Pass** and start in first person with an item equipped.
2. Move the arms and item close to a wall. They should remain fully visible, while scene geometry keeps normal depth and no child first-person camera is required.
3. Inspect the Game view for duplicated shadows. The third-person shadow can remain, but the first-person arms and item should not add a second shadow.
4. If both perspectives are available, switch to third person and back several times. The correct body should be visible in each perspective and the invisible shadow material should not appear as visible geometry.
5. Test an Object Fader material in third person. It should become transparent and restore its original material state.
6. Trigger one Surface Effect that uses a decal and one that resolves a Surface Type from a texture. The decal should render with its HDRP material, and the expected surface effect should play.
7. Enable one obvious HDRP post-processing override. It should affect the combined scene and first-person objects through the main camera.
8. Repeat the checks in a development build on every supported graphics API. A clean Scene view is not proof that the gameplay camera or player build uses the same render path.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| **HDRP Not Imported** appears after selecting **Import**. | HDRP may be installed but not compiled, or the active package may not expose `CustomPassVolume`. | Finish the Unity HDRP setup, resolve the first Console error, and reopen Setup Manager before importing again. |
| First-person arms or items clip into walls. | **Overlay Pass**, **Overlay Render Type**, the Overlay layer, or **First Person Culling Mask** is missing. | Import the support package, keep one active **Overlay Pass**, select **Render Pipeline**, and restore the expected layer masks. |
| First-person objects disappear entirely. | Their Renderer layer may not be included in **First Person Culling Mask**, or their shader may not render in the HDRP Custom Pass. | Restore the Overlay layer and test one standard HDRP-compatible material before repairing custom shaders. |
| Arms, items, or scene objects are pink. | A Built-in or custom shader was not converted, or the bundled Ultimate Character Controller HDRP shader is from an unverified SRP generation. | Use a material supported by the installed HDRP version. Reimport the matching Ultimate Character Controller support assets and validate the exact Unity, HDRP, and Ultimate Character Controller combination before upgrading production. |
| The view has duplicate first-person shadows. | One or more first-person Renderers still cast shadows. | Set **Cast Shadows** to **Off** on every Renderer under the first-person object hierarchy. |
| The third-person body is visible in first person or stops casting the intended shadow. | **Invisible Material** is absent, belongs to another render pipeline, or was not applied to a first-person-only body's hidden Renderers. | Assign **InvisibleShadowCasterHDRP** through **Perspective Monitor**, or apply it to the required hidden third-person Renderer materials. |
| Object Fader changes no alpha. | Its color or surface-mode property names do not exist on the HDRP shader, or the material is not configured for transparency. | Match the fields to the actual shader and confirm one material can fade before broadening the setup. |
| Surface effects use the fallback type on textured objects. | **Main Texture Property Name** may still be `_BaseMap` while the HDRP material uses `_BaseColorMap` or a custom name. | Enter the material's real base texture property on **Surface Manager** and repeat the representative impact. |
| An Ultimate Character Controller decal does not spawn or fade. | The assigned prefab may use an HDRP Decal Projector instead of the required mesh and Renderer, or its material may not support HDRP transparency. | Use a mesh decal prefab with **MeshFilter**, **Renderer**, and a compatible material; then test the Decal Manager limit and weathering path. |
| The overlay renders twice or produces unexpected ordering. | More than one active **Overlay Pass** may exist in additive scenes, or another Custom Pass may share the same stage. | Keep one Ultimate Character Controller Overlay Pass in the loaded scene set and review the priorities and injection points of other HDRP Custom Pass Volumes. |
## Related tasks
- [Quick Setup](https://opsive.com/support/documentation/ultimate-character-controller/getting-started/quick-setup/)
- [First Person View Types](https://opsive.com/support/documentation/ultimate-character-controller/camera/view-types/included-view-types/first-person/)
- [Post Processing](https://opsive.com/support/documentation/ultimate-character-controller/camera/post-processing/)
- [Object Fader](https://opsive.com/support/documentation/ultimate-character-controller/camera/object-fader/)
- [Surface System](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/)
- [Surface Manager](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/surface-manager/)
- [Layer Manager](https://opsive.com/support/documentation/ultimate-character-controller/layer-manager/)
- [Integrations](https://opsive.com/support/documentation/ultimate-character-controller/integrations/)
## Developer and compatibility notes
The released Setup Manager detects HDRP by looking for `UnityEngine.Rendering.HighDefinition.CustomPassVolume`. It maintains the `ULTIMATE_CHARACTER_CONTROLLER_HDRP` compile symbol for the active build target and imports the bundled `HDRP.unitypackage`; it does not install HDRP, select an HDRP Asset, run Unity's material converter, or validate a semantic HDRP version range.
The bundled **Overlay Pass** is a Global `CustomPassVolume` with a Draw Renderers pass filtered to Ultimate Character Controller's Overlay layer. It targets the camera color and depth buffers, clears depth for the overlay draw, and requests the material's `Forward` pass. Custom first-person shaders must therefore be compatible with the installed HDRP Custom Pass path as well as render normally in HDRP.
In **Render Pipeline** mode, the first-person View Type includes its **First Person Culling Mask** in the main camera only while first person is active. Switching away removes that mask. This is why the HDRP route can render the scene and first-person overlay through one camera, and why missing layer or material support appears as invisible arms rather than as a missing child camera.
Unity 2022.2 and 2022.3 pair with SRP 14.x. The audited Ultimate Character Controller support shaders were generated for SRP `14.0.8`, but the Setup Manager has no version gate and the inspected project does not prove every later HDRP generation. Record the Unity, HDRP, and Ultimate Character Controller versions that pass this page's Play Mode and build checks, and repeat them after changing any member of that set.
---
# Horse Animset Pro
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/integrations/horse-animset-pro/)
Use the [Horse Animset Pro](https://assetstore.unity.com/packages/3d/characters/animals/horse-animset-pro-riding-system-79902?aid=1100lGdc) generic integration when a visible Ultimate Character Controller rider should mount a Malbers horse, give Horse Animset Pro ownership of movement and mounted animation, then return to normal Ultimate Character Controller control after dismounting.
## Compatibility boundary
Horse Animset Pro and its Ultimate Character Controller bridge are maintained and distributed by Malbers Animations. They are not included in the Ultimate Character Controller package or installed through the Ultimate Character Controller Integrations Manager.
| Audited evidence | What it establishes |
| --- | --- |
| Ultimate Character Controller `3.2.0` | The Ultimate Character Controller release targeted by this guide. |
| Installed Horse Animset Pro rider source `4.4.2a` | The `MRider` behavior and Inspector workflow described below. |
| Malbers generic download labeled `HAP (4.4.2) UCC (3.0.8) Generic Integration` | The scene, prefabs, event, and Animator Controller audited for this workflow. Malbers' integration index describes this route as Ultimate Character Controller `3.08+`. |
| The older `Ride HAP.cs` bridge and its embedded Ultimate Character Controller `3.0.3` installer | A legacy implementation. Do not combine it with the generic bridge or import its old Ultimate Character Controller installer into an Ultimate Character Controller 3.2.0 project. |
The generic download does not declare a maximum Ultimate Character Controller version and does not explicitly name Ultimate Character Controller 3.2.0. The `3.08+` label is therefore not a blanket compatibility matrix. Import and validate the bridge in a copy or source-controlled branch of the actual project whenever Ultimate Character Controller, Horse Animset Pro, Cinemachine, or the bridge changes.
## Before you begin
- Install and test Ultimate Character Controller 3.2.0, including its required project layers, before adding the bridge.
- Install and test [Horse Animset Pro](https://assetstore.unity.com/packages/3d/characters/animals/horse-animset-pro-riding-system-79902?aid=1100lGdc) by itself. The horse must already move through the Malbers Animal Controller before Ultimate Character Controller is connected.
- Use a Humanoid Ultimate Character Controller rider with a visible third-person model, Animator, root Rigidbody, and main character collider. The official generic integration also requires the Ultimate Character Controller character to have a ragdoll.
- If the supplied **Mount Camera** and Cinemachine prefabs will be used, install the Cinemachine dependency required by the installed Horse Animset Pro release before importing the bridge. The generic package does not pin a Cinemachine version.
- Make project-owned copies of any Animator Controller or prefab that will be edited.
## Install the generic bridge
1. Download the package from Malbers' [Ultimate Character Controller 3.0.8 generic integration page](https://malbersanimations.gitbook.io/animal-controller/annex/integrations/opsive-integration-1). Choose the download whose label matches the installed Horse Animset Pro generation; do not substitute the similarly named legacy Ultimate Character Controller 3.0.3 integration.
2. Import in this order: Ultimate Character Controller 3.2.0, Horse Animset Pro, the required camera dependency, then the generic integration package. Allow Unity to compile after each product.
3. If an older integration is already present under `Assets/Malbers Animations/Horse AnimSet Pro/Integrations/Ultimate Character Controller`, inventory its scenes, prefabs, and `RideHAP` references before importing. A Unity package import does not delete obsolete assets. Keep one configured runtime route, and remove legacy components or source only after confirming that no project prefab or scene still references them.
4. Do not import `UltimateCharacterController3.0.3.unitypackage` or `UltimateCharacterController2.4.9.unitypackage` if either appears inside an older Horse Animset Pro installation. Keep the project's installed Ultimate Character Controller 3.2.0 package.
5. After import, inspect the supplied **HAP + Ultimate Character Controller new** scene, **Horse UCC** prefab, **Opsive Camera** prefab, **Mount Camera** prefab, **Opsive Mount** event, and **Demo HAP** Animator Controller. Resolve missing scripts and the first Console error before copying anything into a production scene.
The generic package is asset-based: it supplies a reference scene, prefabs, an event asset, and an Animator Controller. It does not add a `RideHAP` ability or another Ultimate Character Controller ride script.
## Configure the Ultimate Character Controller rider
1. Open **Tools > Opsive > Ultimate Character Controller > Character Manager** and build or update the playable Humanoid character with **Animator** and **Ragdoll** enabled. If the character already has a complete ragdoll, verify it instead of building a second one.
2. Confirm that the character walks, turns, animates, and uses its camera before adding Horse Animset Pro.
3. Add **MRider** to the same GameObject as the rider's **Animator** and root **Rigidbody**. The generic reference scene keeps Ultimate Character Controller's character components on this object as well; if the production hierarchy differs, compare every reference with the reference scene instead of relying on automatic lookup.
4. In **MRider**, keep **Parent to Mount** enabled as in the generic scene. Assign **Animator**, **Rigid Body**, **Rider's Root**, **Main Collider**, and the Horse Animset Pro **Collider Modifier** profile. The Main Collider must be the non-trigger collider that enters a horse's Mount Trigger.
5. Enable **Disable Components** and populate **Disable List** explicitly. The audited generic scene disables these six Ultimate Character Controller roles while mounted:
- **Ultimate Character Locomotion Handler**
- **Ultimate Character Locomotion**; the pinned reference scene may display its serialized migration component as **Legacy Character Locomotion**
- **Character IK**
- **Character Foot Effects**
- **Perspective Monitor**
- the active Opsive player-input implementation
6. For Ultimate Character Controller 3.2.0, use **Player Input Proxy > Player Input** to identify the concrete input behavior for the last entry, such as **Unity Input**, **Unity Input System**, or **Rewired Input**. Do not retain a missing reference copied from the Ultimate Character Controller 3.0.8 scene.
7. Do not leave **Disable List** empty. In the audited `MRider` source, an empty list disables every other Behaviour on the MRider GameObject while mounting, which can turn off unrelated Ultimate Character Controller systems.
8. Do not add Ultimate Character Controller's native **Ride** ability or the legacy **RideHAP** ability. The generic bridge uses `MRider` directly. The required Ultimate Character Controller **Ragdoll** ability is a separate prerequisite and remains in the character's normal ability list.
### Add the mounted Animator layer
1. Duplicate the rider's working Animator Controller and assign the copy to the Animator.
2. Select the MRider component. If the controller has no `Mounted` layer, select **Add Mounted Layer**.
3. Confirm that one `Mounted` layer was added and that the Horse Animset Pro parameters were merged into the controller. The button loads the `Layers/Mount v2` controller from Horse Animset Pro and edits the assigned controller in place.
4. Use the imported **Demo HAP** controller to validate the reference scene, not as an automatic replacement for a production controller with custom Ultimate Character Controller item and ability animation.
If **Add Mounted Layer** is not shown, MRider must be able to find an Animator on the same GameObject, and that Animator must use an editable Animator Controller. An Animator Override Controller or an unassigned runtime controller cannot receive the layer through this button.
## Configure the horse and cameras
1. Start with the imported **Horse UCC** prefab, or compare an existing Horse Animset Pro horse against it.
2. On a custom horse, verify the Malbers **Animal** (`MAnimal`) and **Mount** components. Assign **Mount > Mount Point** to the transform that anchors the seated rider.
3. Keep at least one child **Mount Trigger** with a trigger collider. Assign its parent Mount reference, mount-side ID, dismount-side ID, and whether that location may be used to dismount. MRider can mount only after its Main Collider enters one of these triggers.
4. Test the horse's own walk, turn, stop, and input without a rider. Horse movement remains owned by Horse Animset Pro after the rider mounts.
5. For the supplied camera handoff, keep one **Opsive Mount** event asset. In the generic scene, **MRider > On Start Mounting** invokes it with `true`, and **On End Dismounting** invokes it with `false`.
6. Use the imported **Opsive Camera** listener to deactivate the Ultimate Character Controller camera while mounted and restore it after dismount. Use **Mount Camera** to activate and target the horse camera, or replace both listeners with an equivalent project-owned handoff. Do not leave both camera pipelines active.
The provided Mount Camera contains references to Malbers' Cinemachine camera prefabs. A missing Cinemachine script must be resolved with the dependency that matches the installed HAP release, or the supplied camera handoff must be replaced; it is not a reason to downgrade Ultimate Character Controller.
## Configure mount and horse input
### Use Horse Animset Pro MInput
1. Open the MRider component menu and select **Create Mount Inputs**. The command adds **MInput** when it is absent.
2. Inspect the three generated rows:
- `Mount` uses a button-down input and calls `MRider.MountAnimal()`. The audited source creates it on `F`, disables it when mounting starts, and enables it when dismounting ends.
- `Dismount` calls `MRider.DismountAnimal()` after a `0.2` second long press. It starts inactive, enables when mounting ends, and disables when dismounting starts.
- `Call Mount` uses a button-down input and calls `MRider.CallAnimalToggle()`.
3. Remap these prototype keys and activation rules for the project. Ensure one press cannot unintentionally run both Mount and Call Mount.
4. Configure the Horse Animset Pro input that drives `MAnimal` while riding. Ultimate Character Controller movement actions do not automatically drive the horse.
### Use project-owned input
Bind the project's input events to `MRider.MountAnimal()` and `MRider.DismountAnimal()` instead of creating an Ultimate Character Controller ride ability. For Unity Input System or another action-map workflow, keep separate on-foot and riding ownership: disable the gameplay map when mounting finishes, enable the horse's riding map, then reverse that handoff after dismounting. The generic package's Malbers **MInput** rows do not automatically edit an Ultimate Character Controller action asset or switch Ultimate Character Controller action maps.
Whichever route is chosen, only one system should read movement at a time. Ultimate Character Controller owns on-foot movement; Horse Animset Pro owns mounted movement.
## Editor checkpoint
Before entering Play Mode, verify all of the following:
- The Console is clear, and the generic integration scene contains no missing scripts or missing serialized references after Ultimate Character Controller migration.
- MRider, Animator, Rigid Body, Rider's Root, Main Collider, and Collider Modifier references are assigned.
- The rider controller contains exactly one `Mounted` layer and the parameters added by Horse Animset Pro.
- **Disable Components** is enabled and **Disable List** contains six valid project components, including the Ultimate Character Controller 3.2.0 input implementation rather than a stale Ultimate Character Controller 3.0.8 reference.
- The Ultimate Character Controller ability list contains Ragdoll but contains neither **RideHAP** nor native **Ride** for this workflow.
- The horse has Animal, Mount, a Mount Point, and at least one enabled Mount Trigger.
- One mount input path and one horse movement input path are active.
- The `Opsive Mount` event has one deliberate Ultimate Character Controller-camera listener and one deliberate mounted-camera listener, or the project has an equivalent camera handoff.
## How it runs
When the rider's Main Collider enters a Mount Trigger, Horse Animset Pro assigns that Mount and allows `MountAnimal()` to start. At the start of mounting, MRider disables the rider colliders, parents Rider's Root to the horse's Mount Point when **Parent to Mount** is enabled, disables every Behaviour in the explicit Disable List, and sends **On Start Mounting**. The generic event handoff disables the Ultimate Character Controller camera and enables the mount camera.
At the end of mounting, MRider marks the rider as on the horse, synchronizes rider Animator values from the Malbers Animal, reconnects the mounted collider, and enables the Dismount input. Horse Animset Pro then owns horse movement and rider alignment; Ultimate Character Controller's locomotion and input behaviors remain disabled.
Dismounting unparents Rider's Root at the start of the transition. At the end, MRider restores its Rigidbody settings, main and child colliders, every Behaviour in Disable List, and the Mount input, then sends **On End Dismounting**. The camera listener returns control to Ultimate Character Controller. A forced interruption that never reaches the end callback needs equivalent project cleanup.
## Verify in Play Mode
1. Start on foot and confirm Ultimate Character Controller movement, look input, abilities, and the Ultimate Character Controller camera work normally.
2. Approach one Mount Trigger with the rider's Main Collider. In **MRider > Debug**, confirm **Can Mount** becomes enabled and the expected **Mount Trigger** and current Mount are shown.
3. Press Mount. During the transition, confirm **Is Mounting** is enabled, the explicit Ultimate Character Controller Disable List is disabled, the Ultimate Character Controller camera turns off, and the mounted camera turns on.
4. Wait for the transition to complete. Confirm **Mounted**, **Is on Horse**, and **Is Riding** are enabled, the rider is aligned to Mount Point, and the Animator is in the `Mounted` layer.
5. Walk forward and backward, turn, accelerate, and stop with the Horse Animset Pro controls. The horse should move, while on-foot Ultimate Character Controller movement and look input should not move or rotate the rider independently.
6. Request a dismount from a valid Mount Trigger. With the generated default, hold Dismount for at least `0.2` seconds. Confirm **Is Dismounting** becomes enabled and the rider unparents at the intended side.
7. After the transition, confirm the Ultimate Character Controller locomotion and input behaviors, Rigidbody settings, colliders, Ultimate Character Controller camera, and Mount input are restored. Ordinary on-foot movement and abilities should work immediately.
8. Repeat on both sides of the horse, on a slope, after changing camera perspective, and after rapidly releasing movement before dismount. No second camera or Transform writer should remain active.
9. Test every supported forced exit, including rider death, horse destruction, scene loading, or a network ownership change. Each path must restore Ultimate Character Controller components, input, colliders, and the local camera exactly once.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| Unity reports missing Ultimate Character Controller, Malbers, or camera types after import | The bridge may have been imported before its dependencies, legacy `RideHAP` source may target a different Ultimate Character Controller API, or the supplied camera may reference an absent Cinemachine release | Install and compile Ultimate Character Controller 3.2.0, HAP, and the matching camera dependency first. Remove only the unreferenced incompatible legacy route, then reimport the generic package. |
| The generic scene has missing references after import | The downloaded scene is serialized against Ultimate Character Controller 3.0.8 and may contain old component references | Open the scene in the backed-up test project, allow Ultimate Character Controller migration to finish, then replace every missing Disable List or camera reference with the Ultimate Character Controller 3.2.0 equivalent before saving a project-owned copy. |
| **Add Mounted Layer** is absent | MRider may not share a GameObject with Animator, the Animator Controller may be unassigned, or it may be an Animator Override Controller | Put MRider with the Animator used by the rider, assign an editable project-owned Animator Controller, and reopen the component. |
| Mount input does nothing and **Can Mount** stays disabled | The rider's Main Collider may not be entering an enabled Mount Trigger, or the trigger may not reference the intended Mount | Assign MRider's Main Collider, correct the trigger collider and layers, and assign the Mount before testing the input again. |
| Mount starts but never reaches **Is Riding** | The `Mounted` layer, its HAP state behaviors, parameters, or compatible rider clips may be absent | Add the layer from MRider to the production controller or compare it with **Demo HAP**, then restore the required HAP parameters and transitions. |
| The rider jitters, slides, or separates from the horse | Ultimate Character Controller and HAP may both be moving the rider because Disable List is incomplete, or native Ride/RideHAP is also active | Restore the six explicit Disable List roles and remove the competing Ride implementation. Let MRider own rider alignment while mounted. |
| The horse does not respond after mounting | The Horse Animset Pro riding input or action map may be inactive even though Ultimate Character Controller input was disabled | Enable and map the HAP riding input after mount completion, and confirm `MAnimal` responds before changing Ultimate Character Controller settings. |
| The camera disappears or two cameras fight | `Opsive Mount` may be missing a listener, the bool may be inverted incorrectly, or both camera owners may remain active | Copy the reference event wiring or implement one project handoff: Ultimate Character Controller camera off and mount camera on at start mount, then the reverse at end dismount. |
| Dismount input does nothing | The generated Dismount row may still be inactive, the long press may be shorter than `0.2` seconds, or no valid dismount trigger may be available | Finish the mount transition, hold the configured input, and add or enable a Mount Trigger that permits dismounting. |
| Ultimate Character Controller remains frozen after dismount | **On End Dismounting** may not have run, or a stale or missing component reference may prevent the intended restoration | Confirm the transition reaches MRider's end state, then restore the explicit Disable List references and add cleanup for every forced-interruption path. |
| The rider collides with the horse or dismounts in a bad pose | Main Collider, Collider Modifier, Mount Point, or trigger-side IDs may not match the rider and horse scale | Copy the corresponding references from the working generic scene, then resize and reposition the collider profile, Mount Point, and left/right triggers for the production models. |
## Related pages
- [Integrations](https://opsive.com/support/documentation/ultimate-character-controller/integrations/)
- [Ragdoll](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/ragdoll/)
- [Animator Controller](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/animator-controller/)
- [Input](https://opsive.com/support/documentation/ultimate-character-controller/input/)
- [Camera](https://opsive.com/support/documentation/ultimate-character-controller/camera/)
- [Native Ride ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/detect-object-ability-base/ride/)
- [Rideable](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/rideable/)
- [Malbers' general Horse Animset Pro integration guide](https://malbersanimations.gitbook.io/animal-controller/annex/integrations/general-hap-integration)
## Integration ownership and APIs
The generic package contains no Ultimate Character Controller `Ability` implementation. Horse Animset Pro's `MRider` owns the transition and rider root while mounted, its `Mount` and `MAnimal` components own the horse, and its input owns horse movement. Ultimate Character Controller is paused by disabling selected Behaviors; the `Opsive Mount` event performs only the sample's camera handoff.
The primary project integration points are:
- `MRider.MountAnimal()` and `MRider.DismountAnimal()` for explicit mount requests.
- `MRider.CallAnimalToggle()` for the optional call-mount input.
- **On Start Mounting**, **On End Mounting**, **On Start Dismounting**, and **On End Dismounting** for input, camera, item, UI, and interruption handling.
- MRider's runtime state, including **Can Mount**, **Can Dismount**, **Mounted**, **Is on Horse**, **Is Mounting**, **Is Riding**, **Is Dismounting**, Current Mount, and Mount Trigger, for diagnostics rather than a second movement controller.
The normal end-dismount callback restores the objects MRider owns: its Rigidbody and collider settings and every Behaviour in its Disable List. The listeners created by **Create Mount Inputs** then re-enable Mount input, and the generic scene's event listener restores the Ultimate Character Controller camera. The generic package does not define Ultimate Character Controller inventory policy. Use MRider events to unequip, hide, or constrain items before mounting and restore them after a completed or forced dismount.
The package also contains no Ultimate Character Controller Save System adapter. Persist a stable rider identity, mount identity, ownership, and a safe transform deliberately. Restoring the rider already mounted or midway through a transition requires project code; loading into a normal dismounted state is safer unless the complete MRider and horse state is reconstructed.
No network authority or replication layer is supplied. A multiplayer implementation must arbitrate one rider per mount, give one peer authority over rider and horse movement, synchronize mount and dismount transitions, and run camera switching only for the local owner. Do not let two peers, or Ultimate Character Controller and HAP on one peer, write the same rider Transform.
The legacy `RideHAP` class is a different bridge. It is a manually started and stopped Ultimate Character Controller Ability that listens to MRider events and copies the HAP rider pose into Ultimate Character Controller while disabling Ultimate Character Controller input, gravity, and collision. Those details explain old scenes, but they are not setup instructions for the generic package described on this page.
---
# InControl
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/integrations/incontrol/)
Use the [InControl](https://assetstore.unity.com/packages/tools/input-management/incontrol-14695?aid=1100lGdc) integration when InControl should translate keyboard, mouse, controller, or touch input while Ultimate Character Controller continues to run the character, camera, abilities, and items. The integration replaces the character's Opsive Unity input component with **InControl Input**; it does not configure InControl's devices, bindings, UI navigation, or multiplayer joining for you.
## Before you begin
- Start with an Ultimate Character Controller Version 3 character that moves, looks, jumps, and uses one representative item before changing its input provider.
- Install [InControl from the Unity Asset Store](https://assetstore.unity.com/packages/tools/input-management/incontrol-14695?aid=1100lGdc) first and complete its own project setup. When using InControl's Unity Input Manager backend, its documented menu is **InControl > Setup Input Manager**. Add its runtime manager with **GameObject > InControl > Manager**.
- Commit or back up the project before importing the bridge or regenerating `ProjectSettings/InputManager.asset`.
- Use only one input provider for the character. Keeping Opsive **Unity Input**, Opsive **Unity Input System**, and **InControl Input** active together can duplicate actions or leave **Player Input Proxy** pointing to the wrong component.
The bundled Ultimate Character Controller Version 3 integration assembly declares no minimum or maximum InControl version. The Asset Store listed InControl `1.8.11` when this page was verified, but that current listing is not a compatibility guarantee for every Ultimate Character Controller Version 3 release. Import the installed pair, resolve compilation first, and run the Play Mode checks below before updating a production scene.
## Import the integration
1. Install InControl and wait for Unity to finish compiling.
2. Open **Tools > Opsive > Ultimate Character Controller > Integrations Manager**, select **Available Integrations**, find **InControl**, and use its **Integration** action to open the current distribution route.
3. Sign in to [Opsive Downloads](https://opsive.com/downloads/), download the InControl integration, and import it with **Assets > Import Package > Custom Package**. The bridge is not in the base product's Integrations folder before download; importing it creates `Assets/Opsive/Shared/Integrations/InControl`. Import InControl first because the bridge assembly compiles against its types.
4. Confirm that Unity has added `Assets/Opsive/Shared/Integrations/InControl` and that the Console has no missing `InControl` namespace, type, or assembly errors.
## Replace the character input provider
1. In the Hierarchy, expand the character and select its `Input` child, such as `AtlasInput`.
2. Remove the existing Opsive **Unity Input** component. If the character used Unity's Input System, remove the Opsive **Unity Input System** component and disable or remove the Unity **Player Input** component that belonged to that route. Keep the input GameObject and the character's **Player Input Proxy**.
3. On the same input GameObject, select **Add Component**, search for **InControl Input**, and add it.
4. On the character, assign **Player Input Proxy > Player Input** to the new **InControl Input** component.
5. Ensure the scene contains the **InControl Manager** created by **GameObject > InControl > Manager**.
6. For a first test, set **InControl Input > Bindings Type** to `Opsive.Shared.Integrations.InControl.SampleBindings`.
7. If the Setup Manager previously added Ultimate Character Controller **Virtual Controls** or **On Screen Controls**, disable or remove that input UI while testing InControl. The supplied bridge does not translate those controls; use InControl's touch controls and include them in the selected bindings instead.
## Configure the bindings
The sample bindings are a starting point for a clean integration test. They map common Ultimate Character Controller names such as `Horizontal`, `Vertical`, `Mouse X`, `Mouse Y`, `Controller X`, `Controller Y`, `Jump`, `Fire1`, `Fire2`, `Reload`, `Action`, item selection, and perspective switching to keyboard, mouse, and controller controls.
For a production game, create a class that inherits InControl's `PlayerActionSet` and implements the integration's `IBindings` interface, then enter its full namespace and class name in **Bindings Type**. The class must:
- create its actions in `CreateBindings()`;
- return the matching action from `GetInputControl(string name)`; and
- use the exact names requested by the Ultimate Character Controller ability, item action, camera, or movement setting.
Follow InControl's [binding actions to controls](https://www.gallantgames.com/pages/incontrol-binding-actions-to-controls) workflow for the bindings themselves. Ultimate Character Controller reads each axis as one float, so build movement and look axes with InControl one-axis actions. A `TwoAxisInputControl` produces a warning and returns zero through this bridge; expose horizontal and vertical as separate one-axis controls instead.
The supplied **InControl Input** component enables **Disable Cursor** and **Enable Cursor With Escape** by default. This locks and hides the cursor while playing, releases it with Escape, and captures it again after a click outside UI. Disable or coordinate these options when a menu, pointer-driven game, or another camera system owns the cursor.
## Choose device, touch, and UI ownership
| Scenario | Recommended ownership |
| --- | --- |
| One local player | Leave the action set's InControl `Device` unassigned unless the game needs a fixed controller. InControl then chooses an active device when the action set is used. |
| Local split-screen | Give every character its own **InControl Input** component and binding instance, point each **Player Input Proxy** to its own component, and assign a different InControl device in code. The bridge has no **Player** or **Device** Inspector field and does not pair joining controllers. |
| Keyboard and mouse plus controller | Decide whether both should control the same player. The sample bindings include both, so copying them to multiple local players can make one keyboard control more than one character. |
| Touch controls | Use InControl's touch-control workflow and bind those controls to the same actions. Ultimate Character Controller's generated Virtual Controls and On Screen Controls target its Unity input providers, not this bridge. |
| Controller-driven menus | On the EventSystem, add **Add Component > Event > InControl Input Module** and disable or remove **Standalone Input Module**. By default this UI module reads InControl's current active device; per-player menus require their own deliberate action and ownership setup. |
See [Split Screen](https://opsive.com/support/documentation/ultimate-character-controller/camera/split-screen/) for camera, viewport, and HUD ownership. A second Camera Controller does not separate input devices.
## Verify in Play Mode
1. Enter Play Mode and confirm that the Console does not report **No bindings specified**, **No InControl Manager was found**, or an inability to create the configured `PlayerActionSet`.
2. Test movement and look with the intended keyboard, mouse, or controller. The character should respond once per input, and releasing an axis should return it to zero.
3. Test `Jump` and one representative ability or item action. The Ultimate Character Controller Inspector name and the binding name must produce the same action.
4. Press Escape and click back in the Game view to verify the intended cursor behavior. Open and close any full-screen menu and confirm gameplay input remains disabled only while that menu owns it.
5. If the game uses touch, test the InControl touch layout on the target device rather than relying on mouse simulation alone.
6. For split-screen, test every controller separately. One device should move only its assigned character, and each camera and HUD should continue following that same character after respawn and a scene reload.
7. Make a development build for the target platform and repeat the controller attach, detach, pause, and reconnect flows supported by that platform.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| Unity reports missing `InControl` namespaces or assembly references. | The bridge was imported before InControl, or the installed InControl package does not provide the referenced runtime assembly. | Install InControl first, let it compile, then reimport the bundled Ultimate Character Controller Version 3 `InControl.unitypackage`. If the pair still fails, return to the last verified versions rather than editing assembly references blindly. |
| The Console reports **No bindings specified**. | **InControl Input > Bindings Type** is empty. | Enter the full type name, such as `Opsive.Shared.Integrations.InControl.SampleBindings`. |
| The Console reports that it cannot create the action set or that it does not implement `IBindings`. | The type name is misspelled, cannot be resolved, or the class does not inherit `PlayerActionSet` and implement `IBindings`. | Correct the namespace and class name, fix compilation, and use a class that implements both required contracts. |
| The Console reports **No InControl Manager was found**. | No enabled `InControlManager` exists when **InControl Input** awakens. | Add it with **GameObject > InControl > Manager**, then reload the scene or re-enter Play Mode. |
| The character does not respond, but InControl sees the device. | **Player Input Proxy > Player Input** may be empty, reference the removed provider, or point to another character's input object. | Assign this character's **InControl Input** component and disable competing providers. |
| One ability fails while movement works. | Its requested input name is absent from `GetInputControl`, differs in spacing or capitalization, or was not created by `CreateBindings()`. | Add the exact Ultimate Character Controller input name to the binding map and retest that one action. |
| The Console warns that Ultimate Character Controller does not support `TwoAxisInputControl`. | A movement or look name returns an InControl two-axis action. | Return two separate one-axis controls, such as horizontal and vertical, through separate Ultimate Character Controller names. |
| One controller moves multiple characters. | Their action sets have no fixed `Device`, include the same devices, or share global keyboard and mouse bindings. | Assign a distinct device to each action set after it initializes, restrict included devices where appropriate, and remove shared keyboard bindings from device-exclusive players. |
| Gamepad navigation does not operate a menu. | The EventSystem still uses a different input module, or **InControl Input Module** has not been given the intended submit, cancel, and move actions. | Configure InControl's UI module separately; the Ultimate Character Controller character bridge does not install or bind it. |
| Actions fire twice. | More than one Opsive input provider remains enabled or two proxies reference the same provider. | Keep one provider per player and verify each **Player Input Proxy** reference. |
## Related pages
- [Input](https://opsive.com/support/documentation/ultimate-character-controller/input/)
- [Virtual Controls](https://opsive.com/support/documentation/ultimate-character-controller/input/virtual-controls/)
- [Split Screen](https://opsive.com/support/documentation/ultimate-character-controller/camera/split-screen/)
- [Quick Setup](https://opsive.com/support/documentation/ultimate-character-controller/getting-started/quick-setup/)
- [Integrations](https://opsive.com/support/documentation/ultimate-character-controller/integrations/)
## Developer reference
`Opsive.Shared.Integrations.InControl.InControlInput` derives from Opsive's `PlayerInput`. During `Awake()` it resolves **Bindings Type**, creates that `PlayerActionSet`, verifies `IBindings`, calls `CreateBindings()`, and checks for an `InControlManager`. Button reads map to `IsPressed`, `WasPressed`, and `WasReleased`; axis reads accept `OneAxisInputControl.Value` or `RawValue`.
The `ActionSet` property exposes the created `PlayerActionSet`. Assign a local player's device only after **InControl Input** has initialized successfully:
```csharp
using InControl;
using Opsive.Shared.Integrations.InControl;
public static void AssignDevice(InControlInput playerInput, InputDevice device)
{
playerInput.ActionSet.Device = device;
}
```
InControl also exposes `IncludeDevices` and `ExcludeDevices` on the action set when a game needs a broader ownership policy. The supplied Ultimate Character Controller bridge does not provide an Inspector for those lists, a controller-join flow, binding persistence or rebinding UI, an InControl UI module, or touch controls. Build those responsibilities with InControl and keep Ultimate Character Controller connected through the character's **Player Input Proxy**.
For API behavior and action-set lifetime guidance, see InControl's [PlayerActionSet reference](https://www.gallantgames.com/incontrol-api/html/class_in_control_1_1_player_action_set.html). The discontinued open-source edition is frozen at `1.4.4`; current feature development is distributed through the Asset Store, so do not treat the GitHub edition as a current substitute for the installed package.
---
# Juicy Actions
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/integrations/juicy-actions/)
Use the [Juicy Actions](https://assetstore.unity.com/packages/slug/269711?aid=1100lGdc) integration when reusable Action assets should request Ultimate Character Controller behavior or react to Ultimate Character Controller events without creating a separate scene script for every sequence.
## Install the integration
1. Install Juicy Actions and verify one Action Executor directly.
2. Sign in to [Opsive Downloads](https://opsive.com/downloads/), download the Juicy Actions integration, and import `UltimateCharacterControllerJuicyActions.unitypackage`. The bridge does not exist in the base product's Integrations folder before this download; importing it creates the integration files in the project.
3. Let Unity compile, then search the Juicy Actions selector for an Ultimate Character Controller action such as **Set Character Ability**.
4. Put the Action Executor on an object with an explicit reference to the target Ultimate Character Controller character.
## Choose an action or event
- **Character actions:** Add Character Force, Adjust Character Item Amount, Remove Character Item, Spawn Character Item, Set Character Ability, Set Character Animator Parameter, Set Character Attribute, Set Character Movement Type, and Wait For Character Event.
- **UCC event triggers:** Ability Active, Attribute Change, Camera View Type, Damage, Death, Gameplay Input, Grounded, Item Equip, Item Pickup, Jump, Land, Movement Type, Object Impact, and Respawn.
- **Blackboard and Conditions:** Character Blackboard Populator and Character Conditional Helper expose project-selected Ultimate Character Controller values and predicates to Juicy Actions.
- **Extension points:** Juicy Actions Ability and Juicy Actions Module let an Ultimate Character Controller Ability or modular item action participate in an Action sequence.
## Build a first workflow
1. Create an Action Executor that sets one named character Attribute or starts one known Ability.
2. Run it and confirm Ultimate Character Controller accepts the request and produces the visible result.
3. Add a matching Ultimate Character Controller event trigger, such as **Action On Land**, to start a second Action sequence.
4. Stop or disable the owner and confirm subscriptions and waits are released.
5. Add item, camera, or movement operations only after the first ownership boundary is stable.
## Verify in Play Mode
1. Inspect the requested Ability, Attribute, item amount, movement type, or Animator parameter before and after the Action.
2. Force Ultimate Character Controller to reject an ability request and confirm the sequence takes its intended failure path.
3. Fire the selected event twice and confirm the Action does not register duplicate callbacks.
4. Test death, respawn, perspective changes, and scene reload.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| Ultimate Character Controller actions are absent. | Check Juicy Actions, the bridge package, and compilation. | Install the dependency first, remove duplicate bridge files, and reimport. |
| An Action changes the wrong character. | Check the target reference and Blackboard population. | Assign the intended Ultimate Character Controller root explicitly before using dynamic lookup. |
| An ability request has no effect. | Check Ultimate Character Controller ability presence, index, blockers, and normal Can Start rules. | Configure the ability through Ultimate Character Controller first, then request that working ability from Juicy Actions. |
| An event fires more than once. | Check duplicate trigger components and lifecycle registration. | Keep one event owner and verify it unregisters when disabled or destroyed. |
## Related pages
- [Abilities](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/)
- [Events](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/)
- [Attributes](https://opsive.com/support/documentation/ultimate-character-controller/attributes/)
- [Item Actions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/)
---
# Master Audio
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/integrations/master-audio/)
Use the [Master Audio](https://assetstore.unity.com/packages/tools/audio/master-audio-2022-aaa-sound-212962?aid=1100lGdc) integration when character abilities, damage, items, footsteps, and impacts should play through Master Audio Sound Groups. Ultimate Character Controller components keep their normal **Audio Config** fields, while Master Audio owns Variations, pooled voices, buses, spatial settings, and most playback behavior.
The Audio Manager has one active module. Replacing it routes every Opsive Shared audio request in the scene through Master Audio, including sounds from another installed Opsive product.
## Supported package boundary
The current local integration project was verified with Ultimate Character Controller 3.3.3, Opsive Shared 2.1.0, Unity 2022.3.62f3, and Master Audio 2024 v1.0.3. The bridge does not declare a minimum or maximum Master Audio version, so this is a source-verified combination rather than a general compatibility range. Import the package offered for the released Ultimate Character Controller Version 3 product, then compile and test the workflow on this page before migrating all project audio.
Master Audio includes a small `MA_Opsive.unitypackage` in its third-party integrations folder. That older bridge routes by Audio Clip name and does not include the current **Master Audio Config**, **Variation**, or **Require Group Name** workflow. Use the current Opsive `MasterAudio.unitypackage` from the [Opsive Downloads page](https://opsive.com/downloads/) and do not import both bridges.
## Before you begin
1. Back up or commit the project before replacing the scene's global audio module.
2. Install Master Audio and allow Unity to finish compiling.
3. Add and configure the Master Audio GameObject by following the [Master Audio documentation](https://www.dtdevtools.com/docs/masteraudio/TOC.htm).
4. In Master Audio's [Group Mixer](https://www.dtdevtools.com/docs/masteraudio/GroupMixer.htm), create at least one Sound Group with a playable Variation. Confirm that this group plays before connecting Ultimate Character Controller.
5. Open **Tools > Opsive > Ultimate Character Controller > Integrations Manager**, find **Master Audio**, and follow its download route. If downloading separately, use the package offered for Ultimate Character Controller Version 3 on Opsive Downloads.
6. Import `MasterAudio.unitypackage` with **Assets > Import Package > Custom Package**. Master Audio must already compile because the bridge directly references its runtime types.
After import, **Master Audio Manager Module** and **Master Audio Config** should appear under **Assets > Create > Opsive > Audio**.
## Route Ultimate Character Controller audio through Master Audio
1. Open **Tools > Opsive > Ultimate Character Controller > Setup Manager**.
2. Under **Manager Setup**, select **Add Managers** if the scene does not already contain the normal Ultimate Character Controller managers.
3. In the Hierarchy, select the `Game` GameObject and locate its **Audio Manager** component.
4. Use the included `MasterAudioManagerModule` asset, or create one with **Assets > Create > Opsive > Audio > Master Audio Manager Module**.
5. Assign that asset to **Audio Manager Module** on the Audio Manager.
6. Keep **Require Group Name** enabled for an explicit setup. Every migrated Ultimate Character Controller audio hook must then use a **Master Audio Config** with **Audio Group Name** assigned.
Disable **Require Group Name** only for a clip-name fallback workflow. In that mode the bridge resolves the Ultimate Character Controller Audio Clip and asks Master Audio for a Sound Group whose name exactly matches the clip. It still does not play that Audio Clip directly, so the matching Sound Group and Variation must exist.
## Connect a character damage sound
This example routes the Health component's damage response through a Sound Group named `Character Hurt`.
1. In Master Audio, create the `Character Hurt` Sound Group and add one or more Variations. Configure the group's spatial, distance, bus, and voice settings for a world-space character sound.
2. In the Project window, select **Assets > Create > Opsive > Audio > Master Audio Config** and name the asset `CharacterHurtMasterAudio`.
3. Set **Audio Group Name** to `Character Hurt`.
4. Leave **Variation** set to **(Random Variation)** to let Master Audio choose according to the Sound Group, or select one Variation for a fixed result. Select **[Type In]** only when the intended **Variation Name** cannot be listed.
5. Use the inherited Audio Modifier only for **Volume Override**, **Pitch Override**, or **Delay Override** when this Ultimate Character Controller use should differ from the Sound Group defaults.
6. Select the character and open **Health > Audio > Take Damage**.
7. Assign `CharacterHurtMasterAudio` to **Audio Config**.
With **Require Group Name** enabled, the inline **Audio Clips** list is not needed for this route because the Master Audio Sound Group supplies the Variations. Keeping source clips elsewhere can still make it easier to return to the default Opsive module later.
## Connect abilities, items, and surfaces
Use the same Master Audio Config pattern anywhere Ultimate Character Controller exposes **Audio Config** or an Audio Clip Set:
- Assign configs to an ability's **Start** and **Stop** Audio Clip Sets for short activation feedback or a long-running ability sound.
- Use **Health > Audio > Heal** and **Death** for separate character groups, and the Respawner's **Respawn** Audio Clip Set for return feedback.
- Assign configs to item actions and effects for firing, reloading, melee, magic, pickup, and other item sounds.
- On a Surface Effect, assign a Master Audio Config to **Audio > Audio Config** for footsteps, impacts, or collisions. Master Audio receives the originating transform when available, otherwise the world hit position.
Changing **Audio Manager Module** is global rather than per sound. Audit each Opsive Audio Config and Audio Clip Set after the switch. With **Require Group Name** enabled, a remaining standard Audio Config or inline clip cannot identify a Master Audio Sound Group and will be silent.
## Choose pooling, loops, fades, and movement behavior
Master Audio owns the Variation Audio Sources, pooling, Sound Group voice limits, buses, 2D or 3D spatial behavior, reverb, and loop rules. Configure those choices on the Master Audio Sound Group and its Variations, not on the inherited Ultimate Character Controller Audio Source fields.
- Configure loops on the Master Audio Variation. The bridge does not use the Ultimate Character Controller **Loop Override**.
- Configure Variation fade-in and natural fade-out behavior in Master Audio. An Ultimate Character Controller stop request is abrupt: the supplied bridge does not call Master Audio's fade methods.
- The bridge starts transform-based audio at the transform's current location but does not use Master Audio's follow-transform API. Short actions such as footsteps and weapon impacts are a natural fit. A long or looping 3D sound on a moving character needs a project-specific module or a separate Master Audio setup that follows the transform.
- Stopping an Ultimate Character Controller sound calls Master Audio's stop-all operation for the source transform. Other Master Audio sounds triggered by that same transform stop too. Use separate playback transforms or a custom module when independent long-running sounds must stop separately.
## Editor checkpoint
Before entering Play Mode, confirm that:
- Master Audio and the Opsive bridge compile without errors;
- the scene has one active Master Audio GameObject and one Opsive **Audio Manager**;
- **Audio Manager Module** references `MasterAudioManagerModule`;
- **Require Group Name** matches the explicit-config or clip-name fallback workflow;
- each explicit **Master Audio Config** has a valid **Audio Group Name**;
- a selected **Variation** belongs to that Sound Group, or random Variation selection is intentional;
- every referenced Sound Group has at least one playable Variation; and
- Master Audio owns the intended bus, voice, pooling, spatial, loop, and fade settings.
## Verify in Play Mode
1. Damage the character without killing it. Confirm that `Character Hurt` plays once and Master Audio shows the active voice in the expected Sound Group.
2. Repeat the damage several times. A random config should follow the Sound Group's Variation rules; a fixed **Variation** should remain consistent.
3. Trigger one ability or item sound and confirm that it also routes through Master Audio. This verifies that the Audio Manager module is global rather than Health-specific.
4. Walk across a configured surface or trigger a configured impact. Confirm that the sound uses the intended world position and 3D distance behavior.
5. Test one loop or delayed sound. Confirm that Master Audio, plus any supported volume, pitch, or delay override, produces the intended result.
6. Stop a long-running ability sound while another sound is active on the same character transform. Confirm whether the bridge's stop-all behavior is acceptable for that design.
7. Reload the gameplay scene and repeat one character and one surface or item sound to verify initialization order in the real scene.
## Saving and multiplayer
The integration redirects runtime playback; it does not add save data. Keep Sound Groups and Master Audio Config assets in source control. Save user volume, bus, or audio-option choices through the project's normal settings system or the corresponding Master Audio workflow.
The bridge calls the local Master Audio API and does not use `MasterAudioMultiplayerAdapter` or replicate sounds. An Ultimate Character Controller networking add-on can replicate the gameplay event, but the project must decide which client plays the resulting audio. Trigger it on the appropriate authority or receiving clients to avoid silence or duplicate playback. Master Audio's optional multiplayer packages are separate and must match the installed Master Audio release.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| Importing the bridge creates `DarkTonic.MasterAudio` errors | Master Audio may not be installed or compiling before the Opsive scripts. | Install and compile Master Audio first, then reimport the current Opsive bridge. |
| **Master Audio Config**, **Variation**, or **Require Group Name** is missing | The project may contain Master Audio's bundled `MA_Opsive.unitypackage` instead of the current Opsive package. | Remove the older bridge files and import the Ultimate Character Controller Version 3 `MasterAudio.unitypackage` from Opsive Downloads. Do not keep both. |
| No Ultimate Character Controller sound plays after assigning the module | Check the Master Audio GameObject, **Audio Manager Module**, Console, and requested Sound Group. | Keep both managers active, assign `MasterAudioManagerModule`, and fix the first runtime or missing-group error. |
| A direct Audio Clip worked before the module change but is now silent | **Require Group Name** is enabled and the Ultimate Character Controller hook has no Master Audio Config. | Assign a config with **Audio Group Name**, or use the fallback only after creating a same-named Sound Group for the clip. |
| **Audio Group Name** or **Variation** has no useful choices | The Master Audio GameObject, Sound Group, or Variations may not exist in the current scene. | Create or import them, then reselect the config so its Inspector can refresh the list. |
| The selected Variation does not play | Compare **Variation** or **Variation Name** with the direct children of the selected Sound Group. | Select an existing Variation or return to **(Random Variation)**. |
| A character sound is 2D, too quiet, or routed to the wrong bus | The inherited Ultimate Character Controller spatial and output fields do not drive this module. | Correct the Master Audio Sound Group and Variation Audio Source settings. |
| A looping sound stays behind when the character moves | The bridge uses position-at-start playback rather than Master Audio's follow-transform call. | Use a project-specific Audio Manager module or a direct Master Audio follow setup for that long-running sound. |
| Stopping one ability sound also stops another sound | Both sounds were triggered by the same character transform. | Use separate playback transforms or customize the module for group- or Variation-specific stopping. |
| A fade-out configured in Ultimate Character Controller is ignored | The bridge stops all sounds for the transform abruptly and does not use Ultimate Character Controller's loop or fade-style source overrides. | Configure natural fades in the Master Audio Variation, or customize the stop path when an interrupted sound must fade. |
| Audio plays twice in a networked game | More than one authority or client is responding to the replicated gameplay event. | Choose one replication/playback policy; the bridge itself does not suppress duplicate network calls. |
## Related pages
- [Ultimate Character Controller audio workflow](https://opsive.com/support/documentation/ultimate-character-controller/audio/)
- [Health](https://opsive.com/support/documentation/ultimate-character-controller/attributes/health/)
- [Jump ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/jump/)
- [Surface System](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/)
- [Integrations](https://opsive.com/support/documentation/ultimate-character-controller/integrations/)
- [Ultimate Inventory System Master Audio integration](https://opsive.com/support/documentation/ultimate-inventory-system/integrations/master-audio/)
- [Master Audio Sound Groups](https://www.dtdevtools.com/docs/masteraudio/SoundGroups.htm)
## Developer and runtime reference
The bridge supplies `Opsive.Shared.Integrations.MasterAudio.MasterAudioManagerModule`, derived from `AudioManagerModule`, and `MasterAudioConfig`, derived from `AudioConfig`. Ultimate Character Controller continues to call `Opsive.Shared.Audio.AudioManager`; changing the manager module redirects existing Health, ability, item, respawn, and Surface Effect calls without replacing those components.
For transform playback the module calls `MasterAudio.PlaySound3DAtTransform`. For positioned playback it calls `MasterAudio.PlaySound3DAtVector3`. **Audio Group Name** supplies the Sound Group, and **Variation** optionally supplies one exact Variation. If the call neither plays nor schedules a voice, the bridge returns `PlayResult.None`.
The module applies volume, pitch, and delay overrides from the individual request first, then from the Master Audio Config. Master Audio owns looping, output routing, stereo pan, spatial blend, reverb, pooling, voice limits, and Variation Audio Sources. The inherited Opsive fields for Audio Source prefabs, sharing or replacing Audio Sources, copying source properties, output, loop, stereo pan, spatial blend, and reverb are not consumed by this module.
Both `Stop` overloads call `MasterAudio.StopAllSoundsOfTransform` and return no Audio Source, so a stop by config or `PlayResult` is not isolated to one Sound Group or Variation. The integration routes Opsive sound-effect playback; it does not turn Ultimate Character Controller audio fields into Master Audio playlists.
The current bridge package has no formal third-party version constraint. Its source and compile boundary were checked with Ultimate Character Controller 3.3.3, Opsive Shared 2.1.0, and Master Audio 2024 v1.0.3. Recheck this minimal workflow whenever upgrading any of those packages.
---
# NWH Vehicle Physics
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/integrations/nwh-vehicle-physics/)
Use the [NWH Vehicle Physics](https://assetstore.unity.com/packages/tools/physics/nwh-vehicle-physics-2-166252?aid=1100lGdc) integration when an Ultimate Character Controller character should enter a vehicle, hand driving input and camera control to NWH Vehicle Physics 2, then return to ordinary character control on exit.
## Supported package boundary
This guide is verified against the released Ultimate Character Controller Version 3 `NWHDriveSource` bridge and the checked-in NWH test project, whose AssetInfo reports `10.20f`. The bridge package was last source-updated in July 2023 and does not declare a minimum or maximum NWH version. NWH has published later releases, so this is not a blanket compatibility guarantee for every 13.x package.
Before upgrading an existing project, import the current Opsive bridge into a copy and confirm that NWH still exposes `NWH.Common.Vehicles.Vehicle` and `NWH.Common.Cameras.CameraChanger`. Follow the [NWH Vehicle Physics documentation and changelog](https://www.nwhvehiclephysics.com/doku.php/index) for package-specific vehicle setup and migration changes.
## Before you begin
- Build and test the Ultimate Character Controller Version 3 character, camera, and **Drive** ability before connecting the vehicle.
- Build and test the NWH vehicle on its own. Its wheels, Rigidbody, powertrain, input provider, and cameras remain NWH responsibilities.
- Decide which NWH input provider owns the vehicle controls. The bridge enables the NWH **Vehicle** component; it does not translate Ultimate Character Controller character input into NWH steering, throttle, or brake values.
- Add an NWH vehicle camera. The stock bridge disables the Ultimate Character Controller Camera Controller GameObject while driving and has no option to keep that camera active.
## Install the integration
1. Install [NWH Vehicle Physics 2](https://assetstore.unity.com/packages/tools/physics/nwh-vehicle-physics-2-166252?aid=1100lGdc) and verify a vehicle in Play Mode.
2. Sign in to [Opsive Downloads](https://opsive.com/downloads/) and download the NWH Vehicle Physics integration. The bridge is not included in the base product's Integrations folder before this download.
3. Import the downloaded bridge after NWH has compiled. Importing it creates the integration files in the project.
4. Allow Unity to compile. Resolve the first Console error before continuing; the bridge requires both Ultimate Character Controller and the NWH `Vehicle` and `CameraChanger` APIs.
5. Confirm that **NWH Drive Source** is available from Add Component.
Reimport the current bridge after updating Ultimate Character Controller or NWH. If its source no longer compiles, restore the last working package combination or adapt the bridge to the installed NWH API before changing the scene setup.
## Connect the vehicle
1. Select the vehicle root containing NWH's **Vehicle Controller** component. Add **NWH Drive Source** to this same GameObject; the bridge looks for the NWH `Vehicle` component beside itself.
2. Create a child Transform named `Driver Location`. Position and rotate it where the character should sit, then assign it to **NWH Drive Source > Driver Location**.
3. Set **Animator ID**. Keep `0` when using the default Drive animation set, or use a distinct base ID when the Animator contains vehicle-specific Enter, Drive, and Exit states.
4. Add one or more **Move Towards Location** children beside doors or other safe entry and exit points. Drive requires at least one clear location even when **Teleport Enter Exit** is enabled.
5. Add the collider or trigger that Drive should detect. Put its actual layer in **Drive > Detect Layers**; do not assume an NWH prefab uses a particular layer.
6. Keep every vehicle collider that should ignore the seated character active below the NWH Drive Source GameObject when the scene starts. The bridge caches active child colliders once during `Start`.
The current bridge disables the NWH Vehicle component during `Start` and enables it after the character finishes entering. Do not follow older instructions to change NWH's removed **Awake On Start** option; that legacy screenshot and field no longer describe the audited package.
### Configure NWH input
Choose and configure an NWH input provider independently of the character's Ultimate Character Controller input:
- Use **Input System Vehicle Input Provider** for NWH's Unity Input System route, or **Input Manager Vehicle Input Provider** for its legacy Input Manager route. Configure the NWH actions or axes and verify them on a vehicle before adding Ultimate Character Controller.
- Leave the NWH Vehicle Controller's **Auto Set Input** enabled when it should collect values from the active scene provider. **Swap Input In R** is enabled by default and swaps throttle and brake while reversing.
- Disable **Auto Set Input** when AI or project code writes NWH vehicle input states directly.
- If the Ultimate Character Controller character also uses Unity Input System, install and configure the Ultimate Character Controller [Unity Input System integration](https://opsive.com/support/documentation/ultimate-character-controller/integrations/input-system/) separately. That integration controls the character and the `Action` used to start or stop Drive; it does not configure NWH's vehicle action asset.
Use only one local provider for a single vehicle test. Multiple global providers can make it unclear which device is supplying NWH's combined input.
### Configure the NWH camera
1. Add **Camera Changer** below the vehicle root so it can find the parent Vehicle Controller.
2. Add the desired camera GameObjects below Camera Changer.
3. Leave **Auto Find Cameras** enabled to collect child cameras automatically, or disable it and populate **Cameras** manually.
4. Set **Current Camera Index** to the camera which should appear first.
NWH Drive Source finds the first Camera Changer below its GameObject. After entry, it disables the entire Ultimate Character Controller Camera Controller GameObject and enables the NWH Vehicle and Camera Changer. On exit, it disables the NWH camera GameObjects and re-enables the Ultimate Character Controller camera.
The stock source therefore requires an NWH camera for a visible driving view. If the project must keep an Ultimate Character Controller View Type while driving, create a project-specific `IDriveSource` which does not deactivate the Ultimate Character Controller camera; there is no Inspector toggle for that behavior.
## Configure the character
1. Add **Drive** under **Ultimate Character Locomotion > Abilities**. The default `Action` input starts and stops the ability.
2. For animated entry, add **Move Towards** above Drive and add `OnAnimatorEnteredVehicle` and `OnAnimatorExitedVehicle` to every reachable entry and exit animation.
3. Enable **Teleport Enter Exit** when the character should move immediately between a Move Towards Location and Driver Location without those animation events.
4. Configure **Object Detection**, **Detect Layers**, and optional **Object ID** so Drive detects the vehicle collider.
5. Choose item behavior with **Allow Equipped Slots**, **Can Aim**, and **Disable Mesh Renderers**. With the default empty allowed-slots mask, Drive blocks item abilities while seated. Use **Item Equip Verifier** when items should be unequipped before entry and restored afterward.
6. Follow the complete [Drive ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/detect-object-ability-base/drive/) workflow for entry clearance, exit clearance, collision handling, animation events, and vehicle-specific Animator IDs.
NWH owns the controls after entry. Ultimate Character Controller's Drive ability still owns the seated character, entry and exit, item restrictions, collision ignores, and alignment with Driver Location.
## How it runs
1. During `Start`, NWH Drive Source caches its GameObject, Transform, and active child colliders. It finds the NWH Vehicle and first child Camera Changer, then disables both sides of the NWH vehicle view.
2. Ultimate Character Controller Drive detects the source and approaches or teleports to a Move Towards Location. NWH remains disabled while the character enters.
3. When entry finishes, Ultimate Character Controller calls `EnteredVehicle`. The bridge remembers the character, enables NWH's Vehicle component, disables the Ultimate Character Controller camera GameObject, and enables the NWH Camera Changer.
4. NWH's active input provider supplies steering, throttle, brake, and other vehicle controls. Ultimate Character Controller keeps the character aligned with Driver Location and ignores the cached vehicle colliders.
5. When a valid exit begins, Ultimate Character Controller calls `ExitVehicle`. The bridge disables NWH's Vehicle and cameras, returns the Ultimate Character Controller camera, and releases its character reference before the exit finishes.
6. Ultimate Character Controller completes the exit and restores the character's collision, parenting, movement, and configured items.
## Key choices and limitations
| Choice | Use it when | Important consequence |
| --- | --- | --- |
| **Teleport Enter Exit** | No enter or exit animations are available | Entry and exit are immediate, but a clear Move Towards Location is still required. |
| Animated entry and exit | The character should approach a door and play seated transitions | Animator events must call `OnAnimatorEnteredVehicle` and `OnAnimatorExitedVehicle` at the handoff points. |
| NWH Input System provider | The vehicle should use NWH's action asset and supported devices | It remains separate from the Ultimate Character Controller character's Input System integration. |
| NWH Input Manager provider | The vehicle should use NWH's legacy named inputs | Those inputs are global and do not inherit Ultimate Character Controller player ownership. |
| Automatic NWH input | A local player provider should control the vehicle | Keep **Auto Set Input** enabled and avoid competing scene providers. |
| AI or custom input | Code should write the vehicle controls | Disable **Auto Set Input** and assign the NWH states from the owning system. |
| Stock camera handoff | NWH child cameras should control the driving view | The bridge deactivates the complete Ultimate Character Controller Camera Controller GameObject while occupied. |
The stock bridge assumes one local driver. It contains no per-player device assignment, network ownership, vehicle-state replication, or save data. It also snapshots only colliders that are active below the source during `Start`.
A forced stop is another important boundary. Ultimate Character Controller restores its character-side Drive state when force-stopped, but NWH Drive Source performs its Vehicle and camera cleanup in the normal `ExitVehicle` callback. Death, destruction, scene changes, or custom code that interrupts Drive while seated should explicitly disable NWH vehicle control and restore the correct camera.
## Verify in Play Mode
1. Enter Play Mode without entering the vehicle. The NWH Vehicle and every NWH vehicle camera should be disabled, while the Ultimate Character Controller gameplay camera remains active.
2. Approach the entry collider. Drive's inherited **Detected Object** should show the intended vehicle.
3. Press the configured `Action` input. Confirm that the character reaches the expected Move Towards Location or teleports, then aligns with Driver Location.
4. During an entry animation, the vehicle should not accept driving input. It should enable only after the `OnAnimatorEnteredVehicle` event completes entry.
5. Confirm that the Ultimate Character Controller camera turns off and the camera at **Current Camera Index** turns on after entry. There should be one active Camera and one active Audio Listener.
6. Test steering, throttle, braking, reverse, and any configured camera-change input. Only the occupied vehicle should respond.
7. Press `Action` with a clear exit location. NWH control and cameras should turn off as exit begins; the Ultimate Character Controller camera and ordinary character movement should return.
8. Block one exit and retry. Drive should remain active until another Move Towards Location is clear.
9. Test death, a forced ability stop, scene loading, and vehicle destruction while seated. Confirm that project cleanup restores the camera and disables the NWH Vehicle in every supported interruption.
10. If the project supports saving or multiplayer, repeat the test after a save/load cycle and with every local or remote ownership role.
## Saving and multiplayer
NWH Drive Source does not save the current driver, Vehicle enabled state, vehicle transform, powertrain, input owner, camera owner, or item state. Save those through the project's vehicle and character save systems. A reliable baseline is to restore both character and vehicle unoccupied, unless the project deliberately reconstructs an occupied Drive session.
The bridge also sends no network messages. Ultimate Character Controller's multiplayer Drive path expects the `IDriveSource` to notify remote players, while NWH's optional multiplayer support manages its own Vehicle ownership and `MultiplayerIsRemote` behavior. A multiplayer project must coordinate those layers, assign input and cameras only to the local owner, replicate the vehicle through its chosen NWH networking package, and test entry and exit authority on every peer.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| Unity reports missing NWH types after import | NWH may be absent, may not have compiled before the bridge, or may expose a later incompatible API | Install and compile NWH first, then import the current Ultimate Character Controller bridge. Compare its `Vehicle` and `CameraChanger` APIs before adapting the source. |
| The Console says NWH Drive Source requires a Vehicle | **NWH Drive Source** and NWH's Vehicle Controller may be on different GameObjects | Put NWH Drive Source on the same vehicle root as the component derived from `NWH.Common.Vehicles.Vehicle`. |
| Drive never detects the vehicle | The collider layer may be excluded, the source may not be on a detected parent, or no Move Towards Location may be clear | Correct **Detect Layers**, keep the source in the detected hierarchy, and add a clear entry or exit location. |
| The character enters but the vehicle does not respond | NWH Vehicle may not have enabled, no NWH provider may be active, **Auto Set Input** may be off, or animated entry may still be waiting | Inspect the components after entry, add `OnAnimatorEnteredVehicle`, configure one NWH provider, and enable **Auto Set Input** for player control. |
| The Ultimate Character Controller Input System works but the vehicle does not | The character and vehicle use separate input integrations | Configure NWH's Input System Vehicle Input Provider and its action asset in addition to Ultimate Character Controller's Input System integration. |
| The vehicle responds before entry or another vehicle also responds | Another script may enable NWH Vehicle, or a global input provider may be supplying more than the intended vehicle | Give the bridge sole enabled-state ownership and use an explicit per-vehicle or per-player NWH input route. |
| The screen goes blank after entry | The bridge disables the Ultimate Character Controller Camera Controller GameObject but did not find a usable child Camera Changer and camera | Put Camera Changer and its camera GameObjects below the vehicle root and verify **Current Camera Index** before entry. |
| Two Cameras or Audio Listeners remain active | An extra scene camera may be outside the NWH Camera Changer list, or another system may reactivate it | Choose one camera owner and include or disable every vehicle camera deliberately. |
| Exit input does nothing | No Move Towards Location may be clear | Add another exit point or clear the overlap around its optional clearance collider. |
| Vehicle control or the NWH camera remains active after death or a forced stop | The normal `ExitVehicle` callback may have been bypassed | Add interruption cleanup that disables the NWH Vehicle and cameras and reactivates the correct Ultimate Character Controller camera. |
| The seated character collides with a collider added after startup | NWH Drive Source caches active child colliders only once in `Start` | Keep required colliders active below the source at startup or refresh the collider list in a custom source when the vehicle changes. |
## Related pages
- [Integrations](https://opsive.com/support/documentation/ultimate-character-controller/integrations/)
- [Drive ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/detect-object-ability-base/drive/)
- [Move Towards](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/move-towards/)
- [Move Towards Location](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/move-towards-location/)
- [Item Equip Verifier](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/item-equip-verifier/)
- [Input](https://opsive.com/support/documentation/ultimate-character-controller/input/)
- [Unity Input System integration](https://opsive.com/support/documentation/ultimate-character-controller/integrations/input-system/)
- [Camera](https://opsive.com/support/documentation/ultimate-character-controller/camera/)
- [Split Screen](https://opsive.com/support/documentation/ultimate-character-controller/camera/split-screen/)
## Developer reference
`NWHDriveSource` implements Ultimate Character Controller's `IDriveSource`. Its Inspector exposes only **Driver Location** and **Animator ID**. It supplies the source GameObject, Transform, cached child colliders, and animation ID to Drive.
Its lifecycle callbacks divide the handoff as follows:
- `EnterVehicle(Drive)` does nothing while the character approaches or animates into the vehicle.
- `EnteredVehicle(Drive)` stores the character and enables the NWH Vehicle and camera handoff.
- `ExitVehicle(Drive)` disables NWH, returns the Ultimate Character Controller camera, and clears the stored character when a valid exit begins.
- `ExitedVehicle(Drive)` does nothing after Ultimate Character Controller finishes restoring the character.
At startup, the source uses `GetComponent()`, `GetComponentsInChildren()`, and `GetComponentInChildren()`. These calls explain the same-GameObject Vehicle requirement, the active startup collider snapshot, and the first-child Camera Changer behavior.
The bridge toggles `Vehicle.enabled`; it does not call NWH input APIs directly. NWH's **Auto Set Input** gathers values from its active input providers, while a custom or AI integration can disable that option and write NWH's vehicle input states itself. A custom source should preserve the same entry, normal exit, forced-stop, camera, input-owner, and remote-owner cleanup guarantees.
---
# Omni Animation Packs
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/integrations/omni-animation-packs/)
Use the Omni Animation integration when the Ultimate Character Controller Animator logic already behaves correctly and you want Omni locomotion, knife, or pistol performances in its states. The integration is a set of editor-time Animation Replacement templates. It does not add a runtime bridge, replace the Ultimate Character Controller ability or item systems, or automatically retarget an incompatible rig.
## Compatibility boundary
This workflow was verified against Ultimate Character Controller 3.2.0 and the locally released Core Locomotion, Knife, and Pistol integration assets. The audited Omni assets identify their pack data as version 1.0. The current Unity Asset Store listings identify [Core Locomotion](https://assetstore.unity.com/packages/3d/animations/omni-animation-core-locomotion-pack-286945?aid=1100lGdc), [Knife](https://assetstore.unity.com/packages/3d/animations/omni-animation-knife-pack-277864?aid=1100lGdc), and [Pistol](https://assetstore.unity.com/packages/3d/animations/omni-animation-pistol-pack-276060?aid=1100lGdc) as version 1.0.1 with Unity 2021.3 as the original editor baseline.
Those facts are not an Ultimate Character Controller-to-Omni version matrix. Opsive supplies the Ultimate Character Controller replacement templates separately, and neither package declares a minimum or maximum compatible version of the other. After updating Ultimate Character Controller, an Omni pack, or a replacement template, repeat the Editor and Play Mode checks on a controller copy before updating production assets.
The integration covers the following supplied choices:
| Pack | Replacement Template | Populated mappings | Choose it for |
| --- | --- | ---: | --- |
| Core Locomotion | `CoreLocomotionAnimations` | 14 | The mapped idle, crouch, forward/backward, and strafe walk/run motions present in the selected controller. |
| Knife | `KnifeAnimations` | 34 | The standard knife stance and its mapped item actions. |
| Knife | `KnifeReverseGripAnimations` | 34 | The reverse-grip alternative. Start from an unchanged controller instead of applying both knife templates in sequence. |
| Pistol | `PistolHighReadyAnimations` | 31 | The High Ready pistol stance. |
| Pistol | `PistolLowReadyAnimations` | 31 | The Low Ready pistol stance. |
| Pistol | `PistolRelaxedAnimations` | 31 | The Relaxed pistol stance. |
| Pistol | `PistolTempleIndexAnimations` | 31 | The Temple Index pistol stance. |
A populated mapping is one source-to-replacement pair in the template, not a promise that every row exists in every controller. The Console replacement count can also be higher because one source clip may occur in multiple states or blend trees.
## Before you begin
- Install Ultimate Character Controller 3.2.0 and verify the unchanged character, Animator Controller, abilities, and items in Play Mode.
- Duplicate every Animator Controller that you intend to change into a project-owned folder. **Replace** edits the selected `.controller` asset in place and has no integration-specific rollback command.
- Commit or back up both the copied controllers and the Omni animation assets. **Replace Events** can change imported FBX clip event data shared by other controllers.
- Confirm which runtime Animator owns the body controller. First-person arms and animated visible items can use separate controllers and are not processed automatically.
- Decide whether each character is Humanoid or Generic. The supplied Omni clips and templates are configured for Humanoid retargeting; a Generic rig needs a matching hierarchy or a separate project-specific conversion.
## Install the packs and Ultimate Character Controller templates
Import dependencies in this order so the replacement assets can resolve their clip references:
1. Import and compile Ultimate Character Controller 3.2.0.
2. Import the required Omni pack from its Unity Asset Store listing: Core Locomotion, Knife, or Pistol. Allow Unity to finish importing before continuing. The pack manuals describe one-time scale warnings relative to the source rig as harmless.
3. Inspect the pack under `Assets/Opsive/OmniAnimation/Packs/`. Each installed pack includes an `Animations` folder and a demo scene. The bundled demo scene uses URP, so a material or render-pipeline difference there is not evidence of an animation integration failure.
4. Sign in to the [Opsive Downloads page](https://opsive.com/downloads/) with the Ultimate Character Controller invoice and download the matching Omni Animation replacement-template package.
5. Import the replacement-template package after the Omni pack. Confirm the expected templates appear under `Assets/Opsive/UltimateCharacterController/Integrations` and that Unity reports no missing-script or missing-reference errors.
The downloaded integration contains replacement data only. Do not add Omni's demo `MotionController` component to the Ultimate Character Controller character.
## Choose and verify the animation rig
Each pack contains `Original` and `TPose` animation folders:
- **Original** uses the recorded Omni rig and copies its shared Humanoid Avatar. The pack manuals recommend this variant when in doubt, and every supplied Ultimate Character Controller replacement template references these `Original` clips.
- **TPose** includes a T-pose and creates a Humanoid Avatar from each model. Choose it when you need Unity's generated Avatar or are preparing a project-specific retargeting workflow. The supplied Ultimate Character Controller templates do not select these clips automatically; override each populated replacement row or create a project replacement template.
Before changing a controller, select representative FBX clips in the Project window and check **Rig > Animation Type: Humanoid**. Open **Configure** or use the animation preview to confirm that Unity has a valid Avatar and that the target character does not twist, collapse, or enter a bind pose. Keep the imported `Original` Avatar assignment intact unless a deliberate retargeting test proves another configuration is correct.
If the target is Generic, stop here unless the target skeleton matches the animation hierarchy. The Animation Replacer swaps clip references; it cannot convert Humanoid clips to a Generic rig.
## Replace the controller animations
1. Open **Tools > Opsive > Ultimate Character Controller > Animation Replacer**.
2. Assign the duplicated, project-owned `.controller` asset to **Animator Controller**. Select the controller used by the character body's Animator, not an unrelated demo, first-person arm, or item controller.
3. Assign one template from the compatibility table to **Replacement Template**. Use exactly one Knife grip or Pistol readiness variant on a fresh controller copy.
4. Decide whether to keep **Replace Events** enabled. It is enabled by default and is appropriate only when the replacement clips should inherit the source clips' events. Disable it when the Omni clips already contain approved events or the related Ultimate Character Controller actions use duration-based timing.
5. Review every populated row. Each row is labelled with the original clip and can be overridden. Clear a replacement to keep that source clip unchanged; add a `TPose` clip manually when using that variant.
6. Select **Replace**. Confirm the Console reports ` animation clips were replaced.` A zero count means the selected controller did not contain the exact source clip references mapped by the template.
7. Open the copied Animator Controller. Inspect changed states and nested blend trees, then review the version-control diff. Parameters, transitions, layers, masks, state behaviours, and state settings should remain unchanged; only intended Motion references should differ.
8. Assign the edited copy to the character model's active **Animator > Controller** field. Repeat the process separately for any other body controller that should use the pack.
For a complete explanation of the tool, including custom templates and event transfer, see [Replacing Animations](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/replacing-animations/).
## Editor checkpoint
Before entering Play Mode, confirm all of the following:
- The active character model uses the edited controller copy, and the original controller remains available for comparison.
- The expected template was applied once. Knife grip and Pistol readiness variants have not been stacked on the same controller.
- Every intended row resolves to an `Original` clip, or to a manually selected `TPose` clip when that variant is deliberate.
- Representative clips preview on the character with a valid Humanoid Avatar and without a bind pose or distorted limbs.
- Controller parameters, transitions, layers, Avatar Masks, and StateMachineBehaviours match the original controller.
- Imported replacement clips have the intended loop, root-transform, and Animation Event settings.
- No Omni demo `MotionController` is attached to the Ultimate Character Controller character.
- The Console has no missing-reference, Avatar, or Animator errors.
## Verify in Play Mode
Keep the unchanged and edited controller copies available and compare the same inputs with each. This separates a replacement problem from an existing character, item, or ability setup problem.
1. With Core Locomotion applied, test idle, walk, run, sprint if configured, forward and backward movement, strafing, crouch, starts, stops, turns, jump, fall, and landing. Check every supported movement type and camera perspective used by the character.
2. Watch feet and capsule motion while starting, stopping, turning, moving on slopes, stepping off edges, and colliding. There should be no double movement, cumulative drift, unexpected rotation, or change in gravity behavior.
3. With a Knife template applied, test equip, idle, aim if configured, every attack, moving attacks, crouched use, interruption, and unequip. Confirm the selected normal or reverse grip remains consistent through the full action.
4. With a Pistol template applied, test equip, idle, aim, fire, reload, movement while aiming, interruption, and unequip. Confirm the chosen readiness pose returns after every action.
5. Exercise any Ultimate Character Controller ability whose state uses a replaced clip. Verify that it starts and ends once, transitions back to locomotion, and does not remain waiting for an Animation Event.
6. For every event-driven item or ability action, confirm the gameplay event occurs once at the visible contact, fire, reload, equip, or completion frame. Relative event transfer does not guarantee semantic timing on a differently paced performance.
7. If the character supports first person and third person, test both. These packs target the Humanoid body controller; separate Generic first-person arms should remain unchanged unless their own compatible clips were processed deliberately.
8. Repeat rapid input, action interruption, item switching, and a scene save/load or respawn flow used by the project. The controller should return to a valid idle or locomotion state.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| A downloaded template has missing references or leaves every replacement row empty. | Confirm the matching Omni pack was imported before the Ultimate Character Controller template package and that its `Original` animation folder is present. | Reimport the Omni pack, then reimport the matching Opsive replacement-template package. Do not remap missing references by guesswork. |
| **Replace** reports `0`. | Check that **Animator Controller** is the project-owned controller containing the exact Ultimate Character Controller source clips referenced by the template. | Select the controller actually assigned to the runtime body Animator, review the populated rows, and run **Replace** again. |
| Only some motions changed. | The selected controller may not use every source clip in the template, or another layer/controller may use different clip assets. | Inspect the active state and blend tree, replace the remaining state deliberately, and process each separate compatible controller on its own copy. |
| The character twists, collapses, or shows a bind pose. | Inspect the replacement clip's Humanoid Avatar and preview it on the target model. | Restore the controller copy, correct the rig/Avatar setup, and prove the clip in preview before replacing it again. |
| Selecting `TPose` seems to have no effect. | The supplied Ultimate Character Controller templates reference `Original` clips. | Override the replacement rows with the corresponding `TPose` clips or create a project-specific Animation Replacements asset. |
| The wrong Knife grip or Pistol readiness pose appears. | Check whether the wrong template was selected or multiple stance templates were applied sequentially. | Restore a clean controller copy and apply exactly one matching stance template. |
| A replaced action never completes, fires twice, or occurs at the wrong frame. | Check **Replace Events**, the imported replacement clip's event list, and the Ultimate Character Controller trigger's expected event name or duration. | Restore the approved event data, add or move the event to the visible action frame, or deliberately configure duration timing. |
| Existing Omni events disappeared. | **Replace Events** can replace an imported target clip's event list with the source list. | Restore the FBX importer data from version control or a clean package import, disable **Replace Events**, and retain the approved events manually. |
| Movement slides, rotates twice, or travels farther than the capsule. | Check the clip's root-transform import settings, Ultimate Character Controller's root-motion configuration, and the character for Omni's demo `MotionController`. | Remove the demo controller, make Ultimate Character Controller the sole movement owner, and configure each replacement as in-place or root-motion animation to match the original Ultimate Character Controller state. |
| First-person arms do not change. | Check whether the character uses a separate Generic arm Animator Controller. | Keep the Humanoid Omni clips on the body. Replace the arm controller only with clips authored or converted for that exact arm rig. |
| Another character or controller changes unexpectedly. | It may share the edited controller or an imported replacement clip whose events were changed. | Restore the shared asset, make project-specific controller or clip copies where licensing and import structure permit, and repeat the change on those assets. |
## Related pages
- [Replacing Animations](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/replacing-animations/) covers the Animation Replacer, custom mappings, and event-copy rules.
- [Animator Controller](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/animator-controller/) explains the Ultimate Character Controller layers, transitions, and customization boundary.
- [Animation Event Trigger](https://opsive.com/support/documentation/ultimate-character-controller/animation/animation-event-trigger/) explains event-driven and duration-driven action timing.
- [Character Item Support](https://opsive.com/support/documentation/ultimate-character-controller/character/character-creation/item-support/) covers the character-side setup required before testing Knife or Pistol animations.
## Developer and runtime ownership notes
In Ultimate Character Controller 3.2.0, `AnimationReplacer` traverses every Animator Controller layer, nested state machine, state, and nested blend tree. It changes every Motion reference whose exact source clip has a non-null mapping, marks the selected controller dirty, and logs the number of replacements. It does not create a controller, modify transition logic, or install a runtime integration API.
With **Replace Events** enabled, Ultimate Character Controller copies each source event's function name, parameters, message options, and normalized position to the replacement clip through its `ModelImporter`. This replaces the imported target clip's event list and does not write events to a standalone `.anim` asset. A shared imported clip therefore has one event list across every controller that references it.
Ultimate Character Controller remains responsible for character movement, collision, gravity, abilities, and root-motion application. Omni's demo `MotionController` also consumes `Animator.deltaPosition` and `Animator.deltaRotation`; attaching it to an Ultimate Character Controller character creates competing movement owners. The replacement templates add no event bus, input route, runtime download, or service dependency.
The integration adds no save data and no network messages. A save system continues to persist the project's normal Ultimate Character Controller state, not a selected Omni template. Every network participant must ship the same controller and licensed animation assets, while authority, prediction, ability replication, and respawn restoration remain responsibilities of the selected Ultimate Character Controller networking integration and project code.
---
# PlayMaker
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/integrations/playmaker/)
Use the [PlayMaker](https://assetstore.unity.com/packages/tools/visual-scripting/playmaker-368?aid=1100lGdc) integration to start Ultimate Character Controller abilities, change states and attributes, control items, and branch an FSM from Ultimate Character Controller results without writing a separate script for each workflow.
## Supported package boundary
The released Ultimate Character Controller Version 3 integration is a **PlayMaker 1** custom-action package. Its 28 actions inherit from PlayMaker 1's `FsmStateAction` and use `OnEnter`, `OnUpdate`, and `Finish`. The current [PlayMaker 1 Asset Store listing](https://assetstore.unity.com/packages/tools/visual-scripting/playmaker-368?aid=1100lGdc) reports 1.9.10f1, but the Opsive bridge was last source-updated in April 2023 and declares no minimum or maximum PlayMaker 1 version. Import and compile the exact package combination before updating a production project.
This bridge does **not** support PlayMaker 2. Hutong Games states that [PlayMaker 2 is not backward compatible with PlayMaker 1](https://hutonggames.com/playmaker/docs/welcome/installation/), and PlayMaker 2 uses a different custom-action lifecycle and editor API. Keep an existing Ultimate Character Controller project on PlayMaker 1, or port the Opsive actions before moving that project to PlayMaker 2.
## Before you begin
- Build and test the Ultimate Character Controller Version 3 character before adding an FSM. The integration controls existing Ultimate Character Controller components; it does not create the character, abilities, items, attributes, or states.
- Install PlayMaker 1 and complete its installer before importing the Opsive bridge. Do not import PlayMaker 1 and PlayMaker 2 into the same project.
- Decide where the FSM should live. Put **PlayMaker FSM** on the character when most actions use that character, or put it on a separate controller and assign **Target Game Object** explicitly.
- Add every ability, effect, item-set category, attribute, and named state that the FSM will reference before configuring actions.
## Install the integration
1. Install PlayMaker 1 and confirm that a simple PlayMaker FSM runs in Play Mode.
2. Sign in to [Opsive Downloads](https://opsive.com/downloads/) and download the PlayMaker integration. The bridge is not included in the base product's Integrations folder before this download.
3. Import the downloaded bridge after PlayMaker has compiled. Importing it creates the integration files in the project.
4. Allow Unity to compile. Resolve the first Console error before building an FSM; the action scripts require the `HutongGames.PlayMaker` and Ultimate Character Controller assemblies.
5. Open the PlayMaker **Action Browser**, search for **Ultimate Character Controller**, and confirm that the Opsive actions appear in that category.
The bridge adds PlayMaker actions and custom action editors. It does not add a required runtime component beyond the ordinary PlayMaker FSM and the Ultimate Character Controller components used by each action.
## Start an ability from an FSM
This is the smallest useful test because it verifies action discovery, character targeting, Ultimate Character Controller ability lookup, and PlayMaker transitions.
1. Add the Ultimate Character Controller ability that the FSM should control, such as **Jump**, to **Ultimate Character Locomotion > Abilities**.
2. Add **PlayMaker FSM** to the character and open the FSM editor.
3. Create a state named `Start Jump`, then add **Ultimate Character Controller > Start Stop Ability** from the Action Browser.
4. Leave **Target Game Object** at the owner when the FSM is on the character. Otherwise, assign the character GameObject.
5. Set **Ability Type** to **Jump**.
6. Leave **Priority Index** at `-1` when only one Jump ability exists. If multiple abilities use the same type, enter the Ultimate Character Controller ability index that should be controlled.
7. Keep **Start** enabled and assign separate **Success Event** and **Failure Event** transitions.
8. Enter Play Mode and activate the `Start Jump` state. The success branch should run only when Ultimate Character Controller's normal ability rules allow Jump to start.
Use another **Start Stop Ability** action with **Start** disabled when the FSM should request a stop. The action calls Ultimate Character Controller's normal `TryStartAbility` or `TryStopAbility` path, so ability conflicts, start conditions, movement state, and other Ultimate Character Controller rules still apply.
## Control an Ultimate Character Controller state
Use **Set State** when an FSM should apply several Inspector values as one named configuration rather than changing individual component fields.
1. Create and verify the named state and its preset through the Ultimate Character Controller [State System](https://opsive.com/support/documentation/ultimate-character-controller/state-system/).
2. Add **Ultimate Character Controller > Set State** to a PlayMaker state.
3. Set **Target Game Object** to the object containing the state, enter the exact **State Name**, and leave **Active** enabled to activate it.
4. Add another Set State action with the same name and **Active** disabled on the transition that should release the state.
5. In Play Mode, watch the Ultimate Character Controller State list and the affected Inspector values as the FSM enters and leaves those states.
The bridge deliberately does not contain one action for every Ultimate Character Controller field. Prefer a named state when designers need a reusable group of values, and use a dedicated action when the change represents a runtime operation such as starting an ability or applying damage.
## Work with attributes and health
The character or target object must already contain the relevant **Attribute Manager** or **Health** component.
- **Get Attribute Value** reads the current **Value**, **Min Value**, or **Max Value** into a PlayMaker float. **Attribute Name** defaults to `Health`, and **Every Frame** is off by default.
- **Set Attribute Value** writes the selected Value, Min Value, or Max Value. Keep **Every Frame** off for a one-time change.
- **Damage** and **Heal** call the target's Health component with a positive **Amount**. Enabling **Every Frame** applies that amount on every update, not once per second.
- **Is Alive** stores a Boolean and can send **Alive Event** or **Dead Event**.
- **Has Taken Damage** stores the attacker and sends **Damaged Event** or **Not Damaged Event**. It detects damage from the current or immediately preceding frame while the action is active; it is not a history query.
Use the [Attributes](https://opsive.com/support/documentation/ultimate-character-controller/attributes/) and [Health](https://opsive.com/support/documentation/ultimate-character-controller/attributes/health/) pages to create and verify the underlying Ultimate Character Controller data before reading it from PlayMaker.
## Control items and inventory
Configure the character's item definitions, Item Set Manager, categories, abilities, slots, and action IDs before adding these actions.
- **Adjust Item Identifier Amount** adds or removes the specified **Item Definition** amount from the target Inventory. **Amount** defaults to `0`; use a negative value to remove inventory.
- **Get Item Identifier Amount** stores the amount for an Item Definition in a PlayMaker integer.
- **Start Equip Unequip** selects an **ItemSet Category** and **Item Set Index**, then asks the matching Equip Unequip ability to change sets.
- **Start Item Set Ability** selects an **Ability Type** and **ItemSet Category** and sends success or failure. See the current source limitation below before using it with more than one item-set ability in a category.
- **Start Stop Use** finds a Use ability by **Slot ID** and **Action ID**. **Slot ID** defaults to `-1`, **Action ID** to `0`, **Start** to enabled, and **Wait For Use Complete** to enabled.
- **Reload** finds the Reload ability with the requested Slot ID and Action ID and is compiled only when the Ultimate Character Controller shooter feature is present.
Use the [Items and Inventory](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/) workflow to confirm that the same operation works through Ultimate Character Controller before asking an FSM to control it.
## Other included workflows
The action category also contains focused helpers for common Ultimate Character Controller operations:
| Goal | Actions | Important setup |
| --- | --- | --- |
| Inspect or control abilities | **Is Ability Active**, **Is Ability Enabled**, **Set Ability Enabled**, **Start Stop Ability** | Select the ability type; use **Priority Index** only when duplicate types exist. |
| Inspect or control effects | **Is Effect Active**, **Start Stop Effect** | The effect must already exist under Ultimate Character Locomotion. See the current editor limitation below. |
| Aim and move the character | **Set Aim Target**, **Set Move With Object Target**, **Set Position And Rotation** | The target requires Local Look Source, Move With Object, or Ultimate Character Locomotion respectively. |
| Assign or change the camera | **Assign Character**, **Toggle Perspective** | Assign Character targets the Camera Controller. Toggle Perspective compiles only when both first- and third-person features are installed. |
| Change the character model | **Change Model** | The target requires Model Manager; the shipped action accepts model indexes greater than `0`. |
| Use the Opsive object pool | **Instantiate Object**, **Destroy Object** | Store the instantiated GameObject when another state must destroy it later. |
| Send a name-only Opsive event | **Execute Event** | Do not use the shipped action without reviewing the current source defect below. |
## How targeting and transitions run
Most actions resolve **Target Game Object** when their PlayMaker state begins. An unassigned target means the GameObject that owns the FSM. Actions then find the required Ultimate Character Controller component on that object and either finish immediately or remain active when **Every Frame** or a wait option is enabled.
**Success Event**, **Failure Event**, **Active Event**, and similar fields send PlayMaker FSM events. They do not broadcast Ultimate Character Controller events. **Execute Event** is the exception: it sends a name-only event through the Opsive EventHandler to the selected GameObject.
Polling actions such as Is Ability Active, Is Ability Enabled, Is Effect Active, Get Attribute Value, Is Alive, and Has Taken Damage can run every frame. Keep that option off when a single snapshot is sufficient, and transition out of a polling state when its result is no longer needed.
## Current bridge limitations
- The package is written for PlayMaker 1 and cannot be treated as a PlayMaker 2 action pack.
- The bridge contains no action for every Ultimate Character Controller Inspector field. Use Ultimate Character Controller states for grouped configuration changes.
- **Execute Event** in the shipped source invokes the named event twice when **Every Frame** is disabled and never calls `Finish`. Do not use it unchanged for a one-shot event.
- The custom editor for **Start Stop Effect** populates **Effect Type** from Ultimate Character Controller ability classes instead of effect classes. Use **Is Effect Active** for inspection, or correct and retest the Start Stop Effect editor before relying on it.
- **Start Item Set Ability** displays **Ability Type**, but its runtime lookup selects the first Item Set ability matching the chosen category and does not use the selected type. Do not place multiple candidate item-set abilities in that category without adapting the action.
- With **Wait For Use Complete** enabled, **Start Stop Use** waits for completion but does not send its configured Success or Failure Event. Disable that option when the FSM transition depends on the result event, or adapt the action.
- Several actions return early when their required component, ability, item definition, or target is missing. Some of those paths do not call `Finish`, so an FSM can appear stuck until the setup is corrected.
## Verify in Play Mode
1. Open the Action Browser and confirm all expected actions appear under **Ultimate Character Controller** with no compile errors.
2. Run the Start Jump test. Confirm that a valid start follows **Success Event** and an intentionally blocked start follows **Failure Event**.
3. Activate and deactivate a named Ultimate Character Controller state. Confirm the State list and preset values change only on the intended GameObject.
4. Read `Health` with Get Attribute Value, apply one Damage action, and read it again. The amount should change once, not on every frame.
5. Use Is Alive and Has Taken Damage while the target receives damage. Confirm the PlayMaker events and attacker variable change on the expected frame.
6. Add one inventory item, query its amount, equip a known item set, and use the configured Slot ID and Action ID. Confirm the character's Ultimate Character Controller abilities remain the runtime owner of those operations.
7. Repeat one action from an FSM on another GameObject with **Target Game Object** assigned explicitly. Only the assigned character should respond.
8. Test every failure transition by disabling an ability, omitting a required item, or choosing a blocked action. The FSM should leave the state deliberately rather than remaining active without feedback.
9. If the project saves or networks gameplay, repeat the tests after load and for every local, authoritative, and remote role.
## Saving and multiplayer
The bridge does not persist PlayMaker states, FSM variables, active Ultimate Character Controller states, attributes, inventory, or ability progress. Save PlayMaker data and Ultimate Character Controller runtime data through their respective project save systems, then restore them in a defined order. A reliable baseline is to restore the Ultimate Character Controller character first and let the FSM resume from a neutral state rather than replaying one-shot actions during load.
The actions also send no network messages and perform no authority checks. Execute gameplay-changing actions only for the character's authoritative owner, then replicate the resulting Ultimate Character Controller ability, item, attribute, state, or transform through the project's supported multiplayer layer. A PlayMaker event is local unless the project explicitly sends it across the network.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| The Opsive actions do not appear | PlayMaker may not have compiled before the bridge, or PlayMaker 2 may be installed | Use PlayMaker 1, complete its installer, then reimport the current Ultimate Character Controller Version 3 integration. |
| Unity reports missing `HutongGames.PlayMaker` types | The bridge was imported before PlayMaker 1 or the PlayMaker installer was not completed | Finish the PlayMaker 1 installation, allow Unity to compile, then reimport the bridge. |
| The FSM controls the wrong object | **Target Game Object** may still use the FSM owner | Put the FSM on the Ultimate Character Controller character or assign the intended character, camera, inventory, or state owner explicitly. |
| Start Stop Ability does nothing | The selected ability type may not exist, the duplicate-type index may be wrong, or Ultimate Character Controller may reject its start rules | Add and enable the ability, keep **Priority Index** at `-1` for one instance, and wire both result events. |
| An action state never finishes | A required target, ability, effect, or look source may be missing, or the shipped Execute Event action may be in use | Inspect the Console and action fields, assign the missing dependency, avoid the unmodified Execute Event action, and add an explicit timeout around project-critical actions. |
| An attribute result never changes | The Attribute Manager may be absent or **Attribute Name** may not match exactly | Add the attribute, use its exact name, and store the result in a compatible PlayMaker float. |
| Damage or inventory changes repeat rapidly | **Every Frame** may be enabled | Disable it for one-shot changes, or scale the operation deliberately in a custom continuous action. |
| Item equip or use does not start | The category, Item Set Index, Slot ID, or Action ID may not match the character's configured abilities | Inspect the character's Item Set Manager and item abilities, then enter those exact identifiers. |
| Toggle Perspective is missing | Both first- and third-person scripting defines may not be present | Use a character package with both perspectives, or control the installed View Type through a project-specific workflow. |
| Change Model does nothing for index `0` | The shipped action rejects model indexes less than or equal to zero | Choose a valid available model index above zero or adapt the action if the first entry must be selected. |
| Execute Event fires twice or the state remains active | The shipped one-shot implementation has a source defect | Avoid the action unchanged; correct it to execute once and call `Finish`, then test the named receiver. |
| PlayMaker and Ultimate Character Controller work locally but not for remote players | The integration has no networking or ownership logic | Run actions on the authoritative owner and use the selected Ultimate Character Controller/network integration to replicate the result. |
## Related pages
- [Integrations](https://opsive.com/support/documentation/ultimate-character-controller/integrations/)
- [State System](https://opsive.com/support/documentation/ultimate-character-controller/state-system/)
- [Attributes](https://opsive.com/support/documentation/ultimate-character-controller/attributes/)
- [Health](https://opsive.com/support/documentation/ultimate-character-controller/attributes/health/)
- [Abilities](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/)
- [Effects](https://opsive.com/support/documentation/ultimate-character-controller/character/effects/)
- [Items and Inventory](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/)
- [Camera](https://opsive.com/support/documentation/ultimate-character-controller/camera/)
- [Events](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/)
- [Object Pool](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/object-pool/)
## Developer reference
Every shipped action uses `[ActionCategory("Ultimate Character Controller")]`. Most resolve the target with `Fsm.GetOwnerDefaultTarget`, cache the relevant Ultimate Character Controller component, and use PlayMaker fields for inputs, stored results, and transition events.
The 28 action sources are grouped as follows:
- Character and camera: `AssignCharacter`, `ChangeModel`, `SetAimTarget`, `SetMoveWithObjectTarget`, `SetPositionAndRotation`, and `TogglePerspective`.
- Abilities and effects: `IsAbilityActive`, `IsAbilityEnabled`, `SetAbilityEnabled`, `StartStopAbility`, `IsEffectActive`, and `StartStopEffect`.
- Items and inventory: `AdjustItemIdentifierAmount`, `GetItemIdentifierAmount`, `StartEquipUnequip`, `StartItemSetAbility`, `StartStopUse`, and conditionally compiled `Reload`.
- Attributes and health: `Damage`, `Heal`, `GetAttributeValue`, `SetAttributeValue`, `HasTakenDamage`, and `IsAlive`.
- State and events: `SetState` and `ExecuteEvent`.
- Pooling: `InstantiateObject` and `DestroyObject`.
`Reload` is wrapped in `ULTIMATE_CHARACTER_CONTROLLER_SHOOTER`. `TogglePerspective` is wrapped in both `FIRST_PERSON_CONTROLLER` and `THIRD_PERSON_CONTROLLER`. The custom action editors provide type and Item Set category popups from the current project; the Item Set category popup requires an initialized Item Set Manager in the scene, and Start Stop Effect has the type-popup defect described above.
When porting to PlayMaker 2, do not mechanically copy these classes. PlayMaker 2 replaces the `FsmStateAction` lifecycle and its `OnEnter`, `OnUpdate`, and `Finish` pattern with its newer action, parameter, update-mode, and editor APIs. Preserve the Ultimate Character Controller operation and result semantics while rebuilding each action against the PlayMaker 2 API.
---
# Quest Machine
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/integrations/quest-machine/)
Use the [Quest Machine](https://assetstore.unity.com/packages/tools/game-toolkits/quest-machine-39834?aid=1100lGdc) integration when quests should respond to an Ultimate Character Controller character's inventory or attributes, and when quest rewards should add items or change attribute values. Quest Machine owns the quest and dialogue; Ultimate Character Controller continues to own character interaction, movement, items, attributes, camera, and input.
For example, a knight can offer a shotgun quest through the normal Ultimate Character Controller Interact ability. Quest Machine watches the player's Ultimate Character Controller inventory, advances the quest after a shotgun is collected, and removes the shotgun when it is handed in.
## Supported package boundary
This page covers Ultimate Character Controller Version 3 and the Pixel Crushers Quest Machine bridge. As of August 2026, the Asset Store lists Quest Machine `1.2.72`, and Pixel Crushers has announced `1.2.73`. The Ultimate Character Controller Version 3 bridge source inspected for this page is dated January 2023 and does not declare a minimum or maximum Quest Machine version.
Quest Machine's [current documentation](https://www.pixelcrushers.com/quest_machine/Quest_Machine_Manual.pdf) still lists Ultimate Character Controller support, but that is not a compatibility guarantee for every later patch combination. Install the current bridge from [Opsive Downloads](https://opsive.com/downloads/) for the versions in the project. After upgrading Ultimate Character Controller, Quest Machine, or the bridge, repeat the compile, interaction, inventory-condition, and save tests on this page.
## Before you begin
- Start with a working Ultimate Character Controller Version 3 character. Verify movement, camera, input, and the Interact ability before adding quests.
- Add an inventory and the attributes that quests will read or change. Verify those systems independently first.
- Set up Quest Machine with a quest database and a small quest that can run without the Ultimate Character Controller bridge.
- Back up the project before importing or replacing an integration package.
- If the game will save progress, decide which single Pixel Crushers **Save System** object will own saving before adding savers.
## Install the integration
1. Sign in to [Opsive Downloads](https://opsive.com/downloads/) and download the Quest Machine integration. The bridge is not included in the 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.
3. Allow Unity to compile. Resolve the first Console error before configuring the scene; the bridge requires both Quest Machine and Ultimate Character Controller assemblies.
4. Confirm that the imported support contains **Greet Quest Giver**, **Quest Giver Interactable Target**, the Ultimate Character Controller quest actions and conditions, and the **Opsive Ultimate Character Controller Quest Machine Example** scene.
5. Run the supplied example once before adapting it. The **Get Shotgun** quest is a useful smoke test for interaction, an inventory condition, and an item-removal action.
Do not rely on an old copied support folder after upgrading either product. Reimport the bridge intended for the installed releases, compile, and retest the sample flow.
## Configure the scene and player
1. Add Quest Machine's normal configuration prefab to the scene and assign the project's quest database using the Quest Machine workflow.
2. Add **Quest Journal** to the Ultimate Character Controller player.
3. Keep the player tagged `Player` if bridge fields will leave **Character Name** blank. In a scene with more than one Ultimate Character Controller character, enter an explicit character GameObject name in every quest condition and action instead.
4. On **Ultimate Character Locomotion > Abilities**, add **Greet Quest Giver**.
5. Keep **Start Type** and **Stop Type** set to **Manual**. Quest Machine dialogue messages start and stop this ability; the ability does not initiate the conversation itself.
6. Choose the conversation handoff:
- **Hide UI** hides the Ultimate Character Controller gameplay UI while the quest dialogue is open.
- **Disable Gameplay Input** prevents the character from moving or using gameplay actions during dialogue.
- **Detach Camera** temporarily removes the character from the active Ultimate Character Controller Camera Controller so the dialogue can own the shot.
The inspected bridge enables all three choices by default.
7. Keep the standard Ultimate Character Controller **Interact** ability and its `Action` input. Interact detects and activates the quest giver; **Greet Quest Giver** only manages the character while the dialogue UI is open.
### Configure the greeting input state
The ability activates an Ultimate Character Controller state named `GreetingQuestGiver` for the duration of the conversation.
- If the character uses Ultimate Character Controller's legacy **Unity Input** component, add a state named `GreetingQuestGiver` and apply the imported `GreetingQuestGiverUnityInputPreset` as its preset.
- If the project uses Unity Input System or another input integration, configure an equivalent `GreetingQuestGiver` state in the provider that owns gameplay input and the cursor. The supplied preset targets **Unity Input** and should not be assumed to configure another provider.
- Test mouse, keyboard, and gamepad separately. The selected dialogue UI and input provider still own navigation and cursor behavior.
## Configure a quest giver
1. Select the NPC or object that should offer the quest.
2. Add Quest Machine's **Quest Giver** component and configure its identity, dialogue UI, and quests through the normal Quest Machine workflow.
3. Add **Quest Giver Interactable Target** to the same GameObject. This component requires **Quest Giver** and starts its player dialogue when Ultimate Character Controller interacts.
4. Add Ultimate Character Controller's **Interactable** component and assign **Quest Giver Interactable Target** in **Targets**.
5. On the player's Interact ability, choose an **Object Detection** mode, **Detect Layers**, and distance that can find the Interactable.
6. Enter Play Mode and approach the NPC. Confirm that Ultimate Character Controller shows the quest giver's ID as the interaction message before testing the quest dialogue.
The bridge's interactable target always reports that it can be used. Put gameplay restrictions such as distance, line of sight, cooldown, or actor state in Ultimate Character Controller's detection/ability setup or in a project-specific target extension.
## Build a Get Shotgun test quest
Use the supplied **Get Shotgun Quest** as a reference instead of starting with a large production quest:
1. Create or select a shotgun item type that is available to the player's Ultimate Character Controller inventory and Item Collection.
2. Create a short quest that the configured quest giver can offer.
3. On the stage that waits for the item, add **UCC Item Count Quest Condition**.
4. Leave **Character Name** blank for a single `Player`-tagged character, select the shotgun **Item Type**, choose **At Least**, and set **Required Value** to `1`.
5. On the hand-in or completion stage, add **Add UCC Item Quest Action** for the same item and set **Amount** to `-1`. A negative amount removes the item.
6. Register the quest in the active quest database, enter Play Mode, accept it, pick up the shotgun, return to the giver, and complete the hand-in.
The expected sequence is visible without code: the quest becomes active, the item condition becomes true after pickup, the return dialogue becomes available, and the shotgun is removed when the completion action runs.
## Choose quest conditions and actions
The bridge adds two conditions and two actions to Quest Machine's condition/action selectors.
| Integration type | Important fields | Result |
| --- | --- | --- |
| **UCC Item Count Quest Condition** | **Character Name**, **Item Type**, **Mode**, **Required Value** | Becomes true when the Ultimate Character Controller inventory count is **At Least** or **At Most** the required value. It checks immediately and then listens for pickup and removal changes. |
| **UCC Attribute Quest Condition** | **Character Name**, **Attribute Name**, **Mode**, **Required Value** | Becomes true when the named Ultimate Character Controller attribute is **At Least** or **At Most** the required value. It checks immediately and listens for that attribute to change. |
| **Add UCC Item Quest Action** | **Character Name**, **Item Type**, **Amount** | Adds a positive amount or removes a negative amount. Removing an equipped matching item unequips it first. An amount of `0` does nothing. |
| **Set UCC Attribute Quest Action** | **Character Name**, **Attribute Name**, **Operation**, **Value** | Uses **Set To Value**, **Modify By Value**, or **Randomize** to change the named Ultimate Character Controller attribute. |
Leave **Character Name** blank only when the first `Player`-tagged object with **Ultimate Character Locomotion** is unambiguously the intended character. The item integrations also require an inventory and access to the matching Item Collection. Attribute names must exactly match an attribute on the character's **Attribute Manager**.
Use the attribute action for quest meters and deliberate direct value changes. Setting the `Health` attribute this way does not run Ultimate Character Controller's normal damage or healing pipeline, so it does not provide attacker, impact, damage, or death semantics. Use the [Health](https://opsive.com/support/documentation/ultimate-character-controller/attributes/health/) workflow or a custom quest action when those semantics matter.
## How it runs
1. Ultimate Character Controller's Interact ability detects **Interactable** and calls **Quest Giver Interactable Target**.
2. The target asks Quest Machine's **Quest Giver** to start dialogue with the player.
3. Quest Machine's greeting message starts **Greet Quest Giver**. Ultimate Character Controller applies the selected UI, gameplay-input, camera, and `GreetingQuestGiver` state choices.
4. Quest Machine owns the dialogue and quest graph. Its Ultimate Character Controller conditions read inventory or attribute values and become true when their configured threshold is met.
5. Quest Machine executes the configured Ultimate Character Controller actions when the quest reaches those stages. Ultimate Character Controller owns the resulting inventory or attribute value.
6. When the quest dialogue UI closes, the bridge stops **Greet Quest Giver** and restores the character's Ultimate Character Controller UI, input, camera, and greeting state.
## Save quest and character progress
Quest Machine and Ultimate Character Controller save different data. Configure both deliberately:
1. Keep one Pixel Crushers **Save System** object in the game. Do not add a second Save System component to the Quest Machine object.
2. On **Quest Journal**, assign a unique **Key**, enable **Include In Saved Game Data**, and choose whether completed quests should be remembered.
3. Add **UCC Saver** to the Ultimate Character Controller player and give it a different unique **Key**.
4. Enable only the Ultimate Character Controller categories the save should include: **Save Perspective**, **Save Mouse Settings**, **Save Position**, **Save Attributes**, and **Save Inventory**. The inspected bridge enables all five by default.
5. Save after changing every enabled category, change them again, and load. Confirm that Quest Machine restores the journal while **UCC Saver** restores only the selected character categories.
For item types that can be picked up at runtime but are absent from the starting inventory:
1. Select **Create > Pixel Crushers > Dialogue System > UCC Saver Runtime Pickups**. The legacy `Dialogue System` menu name is used by the shared Pixel Crushers support asset even in a Quest Machine project.
2. Add those item types to **Runtime Items**.
3. Assign the asset to **UCC Saver > Runtime Pickups**.
If Ultimate Inventory System owns inventory saving, keep its saver and disable **Save Inventory** on **UCC Saver** so two systems do not restore the same inventory. Follow the [Ultimate Inventory System integration](https://opsive.com/support/documentation/ultimate-character-controller/integrations/ultimate-inventory-system/) for the installed versions.
The **UCC Saver** does not automatically preserve arbitrary active abilities, effects, Ultimate Character Controller states, or project-specific item-module data. Its attribute data is restored by array order, so do not reorder the character's attributes between saving and loading without a migration plan.
## Key choices and limitations
| Choice | Use it when | Important consequence |
| --- | --- | --- |
| Leave **Character Name** blank | There is exactly one intended Ultimate Character Controller character tagged `Player` | The bridge uses the first matching character it finds. This is ambiguous for multiple players. |
| Enter an explicit character name | A quest addresses a particular NPC, companion, or local player | The name must match the target GameObject exactly. Renaming that object breaks the lookup. |
| Keep the Ultimate Character Controller camera attached | Quest dialogue should use the normal gameplay view | Disable **Detach Camera** and do not ask another camera system to control the same shot. |
| Let quest dialogue own the camera | Dialogue needs its own framing | Enable **Detach Camera** and provide a working dialogue camera. The stock bridge finds the first active Ultimate Character Controller Camera Controller. |
| Change an attribute directly | A quest updates a meter, cost, or reward value | **Set UCC Attribute Quest Action** changes the attribute value without the richer Health damage/healing context. |
| Save inventory through **UCC Saver** | Ultimate Character Controller is the only inventory owner | Enable **Save Inventory** and test runtime item types, slots, equipped items, and ammunition. |
| Save inventory through Ultimate Inventory System | Ultimate Inventory System owns inventory persistence | Disable **Save Inventory** on **UCC Saver** and keep the Ultimate Inventory System save integration. |
The stock interactable target rejects a non-local network character when Ultimate Character Controller multiplayer support is compiled, but it does not synchronize quest state, dialogue, inventory actions, camera ownership, or saved data. Multiplayer and split-screen projects need an explicit per-player quest, camera, input, save, and network-authority design.
The January 2023 bridge source inspected for this page registers the item-count condition for `OnInventoryPickupItem` but unregisters `OnInventoryPickupItemType` when checking stops. That mismatch can leave a pickup listener registered. Before shipping a quest that repeatedly starts and stops **UCC Item Count Quest Condition**, import the latest bridge and verify its `StopChecking()` implementation, or apply a reviewed local fix.
## Verify in Play Mode
1. Approach the quest giver. The Ultimate Character Controller interaction prompt should appear for the intended NPC.
2. Press the Action input. The quest dialogue should start once, and **Greet Quest Giver** should become active.
3. Confirm that gameplay input, Ultimate Character Controller UI, cursor, and camera follow the selected greeting settings.
4. Accept the test quest. It should appear in the player's Quest Journal.
5. Pick up the required item. **UCC Item Count Quest Condition** should advance the quest at the configured threshold.
6. Return to the giver and complete the quest. A negative **Add UCC Item Quest Action** amount should remove the intended item once.
7. Close the dialogue. The same character should regain Ultimate Character Controller input, UI, camera ownership, and the previous greeting state.
8. Repeat with every supported input device. Test the correct cursor and UI navigation behavior for each one.
9. Save while the quest is active and after changing every enabled **UCC Saver** category. Change the state, load, and verify the journal and character data separately.
10. If the game has multiple players or cameras, repeat the entire flow for each owner. Do not accept a result that affects the first player or camera by accident.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| The Ultimate Character Controller quest actions, conditions, or greeting ability are missing | The bridge may not be imported, one product may be absent, or the package may not match the installed releases | Install both products first, then import the current Quest Machine bridge through **Integrations Manager** and resolve the first Console error. |
| The interaction prompt never appears | The Interact ability may not detect the giver's collider/layer, or **Interactable > Targets** may not contain the integration target | Correct **Object Detection**, **Detect Layers**, and range, then assign **Quest Giver Interactable Target** in **Targets**. |
| The prompt appears but dialogue does not start | **Quest Giver**, **Quest Giver Interactable Target**, the dialogue UI, or the quest database may be incomplete | Put both Quest Machine components on the same object, assign its quest/dialogue configuration, and test the ordinary Quest Machine greeting first. |
| The player can move or use items during dialogue | **Greet Quest Giver** may be absent, **Disable Gameplay Input** may be disabled, or the dialogue UI close/open messages may not be reaching it | Add the ability with Manual start/stop, enable the required handoff choices, and confirm it becomes active when greeting begins. |
| The camera goes blank or does not return | **Detach Camera** may be enabled without a dialogue camera, or another system may compete for the first Ultimate Character Controller Camera Controller | Configure one camera owner for the conversation, or disable **Detach Camera** to keep the Ultimate Character Controller camera attached. |
| The cursor or UI navigation is wrong | The active input provider may not have the `GreetingQuestGiver` state, or the legacy Unity Input preset may have been applied to a different provider | Configure the named state on the actual provider and test mouse and gamepad independently. |
| An item condition never becomes true | The character lookup, **Item Type**, inventory, Item Collection, **Mode**, or **Required Value** may not match the runtime character | Use an explicit character name when needed and inspect the actual Ultimate Character Controller inventory count for the selected item type. |
| An attribute condition or action cannot find its value | **Attribute Name** is case-sensitive or the target has no **Attribute Manager** | Enter the exact configured attribute name and confirm it exists on the selected character. |
| A quest changes Health but no damage or death response occurs | The quest action changes the raw attribute rather than calling Ultimate Character Controller's Health damage/healing workflow | Use a custom quest action that calls the intended Health API when combat semantics are required. |
| The wrong character receives an item or attribute change | **Character Name** is blank in a scene with several `Player`-tagged Ultimate Character Controller characters | Enter an explicit character GameObject name or replace the stock lookup with a project-specific player resolver. |
| Quest progress loads but character state does not | Quest Journal may be saved while **UCC Saver** or its category is missing | Add **UCC Saver** with a unique key and enable the exact Ultimate Character Controller categories that should be restored. |
| Character state loads but quest progress does not | **Quest Journal** may not have a unique key or **Include In Saved Game Data** may be disabled | Correct the journal save settings and test a new save slot. |
| Inventory is duplicated or overwritten after loading | **UCC Saver** and Ultimate Inventory System may both be restoring inventory | Choose one inventory save owner. Disable **Save Inventory** on **UCC Saver** when Ultimate Inventory System owns persistence. |
| A runtime pickup disappears after loading | Its item type may be absent from the assigned runtime-pickups asset | Add the item to **UCC Saver Runtime Pickups > Runtime Items** and assign the asset to **UCC Saver**. |
| Item-condition callbacks continue after a quest stops checking | The installed bridge may contain the pickup-event unregistration mismatch described above | Update the bridge or correct and review `UCCItemCountQuestCondition.StopChecking()`, then test repeated quest activation and cancellation. |
## Related pages
- [Integrations](https://opsive.com/support/documentation/ultimate-character-controller/integrations/)
- [Interact ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/detect-object-ability-base/interact/)
- [Items and Inventory](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/)
- [Attributes](https://opsive.com/support/documentation/ultimate-character-controller/attributes/)
- [Health](https://opsive.com/support/documentation/ultimate-character-controller/attributes/health/)
- [Input](https://opsive.com/support/documentation/ultimate-character-controller/input/)
- [Unity Input System integration](https://opsive.com/support/documentation/ultimate-character-controller/integrations/input-system/)
- [Ultimate Inventory System integration](https://opsive.com/support/documentation/ultimate-character-controller/integrations/ultimate-inventory-system/)
- [State System](https://opsive.com/support/documentation/ultimate-character-controller/state-system/)
- [Events](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/)
- [Split Screen](https://opsive.com/support/documentation/ultimate-character-controller/camera/split-screen/)
- [Quest Machine manual](https://www.pixelcrushers.com/quest_machine/Quest_Machine_Manual.pdf)
## Developer reference
The bridge keeps a narrow ownership boundary:
- `QuestGiverInteractableTarget` implements Ultimate Character Controller's interactable target and message interfaces, then calls Quest Machine's `StartDialogueWithPlayer()`. Its multiplayer guard only rejects a known non-local interactor; it does not replicate the interaction.
- `GreetQuestGiver` listens for Quest Machine greeting and dialogue-closed messages. It sends Ultimate Character Controller UI and gameplay-input events, toggles the `GreetingQuestGiver` state, and optionally detaches the first active `CameraController` until dialogue closes.
- `QuestDialogueUIMonitor` sends the close message when the selected quest dialogue UI GameObject is disabled.
- `QuestMachineUCCUtility` resolves a blank character name to the first `Player`-tagged object with `UltimateCharacterLocomotion`; a supplied name uses an exact GameObject lookup.
- `UCCItemCountQuestCondition` and `UCCAttributeQuestCondition` check once, then listen for Ultimate Character Controller inventory or attribute events until Quest Machine marks the condition true.
- `AddUCCItemQuestAction` changes the selected Ultimate Character Controller item amount. `SetUCCAttributeQuestAction` writes the selected attribute directly.
- `UCCSaver` contributes selected Ultimate Character Controller position, perspective, mouse-input, attribute, and inventory data to Pixel Crushers' Save System. Quest Journal remains responsible for quest progress.
Create a custom Quest Machine condition or action when a quest must start or stop an Ultimate Character Controller ability, activate an Ultimate Character Controller state, send an event with project-specific data, apply Health damage/healing semantics, resolve a network player, or persist custom item-module state. Keep Quest Machine responsible for quest decisions and call Ultimate Character Controller's supported systems to perform the character-side result.
---
# RayFire
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/integrations/rayfire/)
Use the [RayFire](https://assetstore.unity.com/packages/tools/game-toolkits/rayfire-2-342492?aid=1100lGdc) integration in an existing, version-matched project when an Ultimate Character Controller weapon impact should add damage to a RayFire object and let RayFire decide when and how that object breaks.
This is a legacy integration boundary. Read the compatibility section before purchasing RayFire, upgrading either product, or importing the bridge into a new project.
## Compatibility boundary
The original [RayFire for Unity](https://assetstore.unity.com/packages/tools/game-toolkits/rayfire-for-unity-obsolete-148690?aid=1100lGdc) line is now marked obsolete. Its final Asset Store release is `1.89`. The current product is the separate [RayFire 2](https://assetstore.unity.com/packages/tools/game-toolkits/rayfire-2-342492?aid=1100lGdc), which is at `2.12` as of August 2026.
The [Ultimate Character Controller 3.0.5 release notes](https://opsive.com/news/ultimate-character-controller-3-0-5-released/) record a RayFire integration update, but the released Ultimate Character Controller Version 3 source inspected for this page does not contain the RayFire integration package or its source. The existing public integration record names `RayFireImpact` and **Damage Multiplier**, but it does not declare a supported RayFire version range or confirm RayFire 2 compatibility.
Do not assume that the legacy bridge supports RayFire 2 because the products share a name. Before using this workflow:
1. Open [Opsive Downloads](https://opsive.com/downloads/) and confirm that the account offers a RayFire integration intended for Ultimate Character Controller Version 3.
2. Inspect the package notes or source for the RayFire generation it targets.
3. Import it into a version-controlled test project containing the installed Ultimate Character Controller and RayFire versions.
4. Continue only if Unity compiles and the `RayFireImpact` component appears without missing scripts.
If the package targets the obsolete RayFire API, keep it with the matching legacy project. For RayFire 2, obtain an explicitly compatible bridge or implement a small project-owned impact receiver against RayFire 2's current API.
## Before you begin
- Start with a working Ultimate Character Controller Version 3 character and an item that can hit an ordinary collider.
- Configure one simple RayFire object and prove that RayFire can demolish or shatter it without Ultimate Character Controller.
- Use an isolated test scene with one weapon, one collider, and one destructible object before testing fragments, clusters, explosions, pooling, or networking.
- Back up the project before importing or replacing the integration package.
## Install the legacy bridge
1. Install Ultimate Character Controller Version 3 and the version of RayFire that the bridge package explicitly supports.
2. Download the RayFire integration from [Opsive Downloads](https://opsive.com/downloads/). The package is not present in the released Ultimate Character Controller V3 integration directory inspected for this page, so do not expect the local **Integrations Manager** to prove compatibility.
3. Import the bridge and allow Unity to compile.
4. Resolve the first Console error before configuring a target. Missing `RayFire` types normally indicate that the required RayFire generation is absent or that the bridge targets a different API.
5. Confirm that **Add Component** offers `RayFireImpact` and that its Inspector exposes **Damage Multiplier**.
The available public documentation does not state the imported **Damage Multiplier** default. Keep the package's own value for the first smoke test, then tune it from an observed RayFire damage change instead of copying an assumed number.
## Configure the Ultimate Character Controller impact
Ultimate Character Controller must send its object-impact event. A visible hit effect or ordinary Ultimate Character Controller damage does not prove that this event is enabled.
1. Select the character item or spawned object that produces the hit.
2. Open the impact-action group that actually runs for that hit. A shootable, melee item, projectile, and explosion can each use a different group.
3. Add or select **Simple Damage**.
4. Set **Damage Amount** to a small, easy-to-measure test value.
5. Keep **Set Damage Impact Data** enabled so the impact context carries the damage value. This is enabled by default in the released Ultimate Character Controller V3 source.
6. Enable **Invoke On Object Impact**. This is disabled by default in the released Ultimate Character Controller V3 source.
7. Enter Play Mode and use **Debug Impact Context** temporarily if needed to confirm that the intended collider, impact point, and damage data reach the impact action.
When **Use Context Data** is enabled, **Simple Damage** uses damage and force values already supplied by the weapon or an earlier impact action. When it is disabled, the local **Simple Damage** values are used. Choose one clear damage owner so the RayFire result does not change unexpectedly when the item configuration changes.
## Configure a legacy RayFire target
These steps describe the contract documented for the original RayFire integration. Use the Inspector labels in the installed RayFire version when they differ.
1. Configure the object with RayFire's **Rayfire Rigid** or the legacy shatter workflow and prove that its selected demolition type works through RayFire alone.
2. If the RayFire object should accumulate hits, enable its damage feature and set an intentional maximum-damage threshold in RayFire.
3. Add `RayFireImpact` to the GameObject that owns the collider receiving the Ultimate Character Controller hit. When the RayFire component and collider share a GameObject, this is normally the RayFire object itself.
4. If the object is already fragmented and the parent has no collider, add `RayFireImpact` only to the child collider objects that should accept hits.
5. Set **Damage Multiplier** relative to the Ultimate Character Controller test value. For example, fire once and compare RayFire's damage before and after the hit, then adjust the multiplier until the observed change matches the design.
6. Do not place receivers on both a child collider and its parent Rigidbody until you have confirmed that one hit is not being processed twice.
### Choose a scenario
- **Repeated weapon damage:** use a RayFire rigid object with damage enabled and a threshold high enough to observe several hits before demolition.
- **One-hit breakable:** use a low RayFire threshold or the matching legacy shatter workflow. Verify the installed bridge's shatter behavior; the current bridge source was not available for this page.
- **Pre-fragmented wall:** place receivers on the fragment colliders that are actually hit. Start with one fragment before rolling the setup across the wall.
- **Explosion:** confirm that the explosion's own impact-action group enables **Set Damage Impact Data** and **Invoke On Object Impact**. Do not assume that configuring the weapon's direct-hit group also configures the explosion.
## How it runs
1. An Ultimate Character Controller item, projectile, melee hit, or explosion creates an **Impact Callback Context** for the collision.
2. **Simple Damage** supplies the selected damage data and, when enabled, invokes `OnObjectImpact` on the hit target.
3. `RayFireImpact` receives that event on its GameObject and applies the integration's **Damage Multiplier** to the bridge's RayFire-side result.
4. RayFire remains responsible for activation, accumulated damage, the demolition threshold, fragment generation, physics, fading, and reset behavior.
The documented bridge is an impact adapter, not a second destruction system. Ultimate Character Controller decides that a hit occurred and provides the impact context; RayFire decides what that hit does to the destructible object.
## Damage, force, and destruction ownership
Keep these responsibilities separate while tuning:
| Responsibility | Owner | What to verify |
| --- | --- | --- |
| Hit detection and impact context | Ultimate Character Controller item, projectile, melee, or explosion module | The correct collider, point, direction, strength, and damage data are present. |
| Object-impact notification | Ultimate Character Controller **Simple Damage** | **Invoke On Object Impact** is enabled in the impact group that actually ran. |
| Damage conversion | `RayFireImpact` | One Ultimate Character Controller hit changes RayFire damage once, scaled by **Damage Multiplier**. |
| Activation and demolition | RayFire | The installed RayFire object's damage, simulation, and demolition settings allow the result. |
| Fragment physics and cleanup | RayFire or project code | Fragments move, fade, reset, pool, or unload according to the chosen RayFire workflow. |
Ultimate Character Controller **Simple Damage** can also apply **Impact Force** to an ordinary Rigidbody. RayFire may apply its own motion when it activates or demolishes an object. If fragments launch too far or move twice, reduce the competing force path and retest with one owner at a time.
## Pooling, saving, and networking
The documented integration does not add pooling, saved destruction state, or network replication.
- **Pooling and reset:** RayFire-generated fragments are not automatically Ultimate Character Controller Object Pool objects. Use the installed RayFire version's reset/pooling workflow or replace the entire destructible prefab through project code. Test a second destruction after reset, not just the first one.
- **Saving:** decide whether a save records the object as intact, damaged, or destroyed. Restore that state with a project-specific saver or a supported RayFire snapshot/reset feature. The bridge does not add this data to Ultimate Character Controller saves.
- **Networking:** run destruction on the chosen authority and replicate a stable result or deterministic destruction command. A local `OnObjectImpact` callback does not synchronize RayFire fragments, damage, or cleanup to other clients.
For large destructible scenes, budget fragment count, collider count, runtime fragmentation, and cleanup independently of Ultimate Character Controller. The bridge removes neither RayFire's simulation cost nor the cost of placing a receiver on many fragment colliders.
## Verify in Play Mode
1. Trigger the RayFire object through RayFire alone. Confirm that its demolition type, fragments, physics, and reset work before testing Ultimate Character Controller.
2. Hit the object once with the configured Ultimate Character Controller source. Confirm that the expected **Simple Damage** group runs and invokes `OnObjectImpact`.
3. Inspect RayFire's current damage. It should change once. Record the observed change before tuning **Damage Multiplier** because the unavailable bridge source does not reveal which impact value it consumes.
4. Repeat the hit until the RayFire threshold is reached. The object should remain intact before the threshold and demolish through RayFire when the threshold is met.
5. Hit a child collider and the parent collider separately. Each physical hit should be counted once.
6. Compare a direct weapon hit, projectile, melee hit, and explosion separately when the game supports them. Each path has its own impact configuration.
7. Reset or respawn the object and destroy it again. Check damage reset, fragment cleanup, and receiver registration.
8. Save and load before and after destruction if the game persists world state.
9. In a networked game, repeat on the server/host and every client. All peers should agree on the intact/destroyed state and cleanup.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| `RayFireImpact` is missing | The bridge may not be imported, or it may not compile with the installed RayFire generation | Verify the download is intended for Ultimate Character Controller V3 and that RayFire is installed first. Resolve the first Console error. |
| Importing the bridge produces missing RayFire types | The package may target the obsolete RayFire API while the project uses RayFire 2 | Do not rename types blindly. Obtain a RayFire 2-compatible bridge or write a small receiver against RayFire 2's documented API. |
| The weapon hits and spawns effects, but RayFire receives nothing | The active **Simple Damage** group may not enable **Invoke On Object Impact** | Enable the option on the exact direct-hit, projectile, melee, or explosion group that runs. |
| The object-impact event fires but RayFire damage does not change | The receiver may be on a different GameObject, RayFire damage may not be configured, or the installed bridge may expect different impact data | Place the receiver on the hit collider object, verify RayFire's own damage workflow, and inspect the installed bridge before changing the Ultimate Character Controller impact data. |
| Damage changes but the object never breaks | RayFire's damage feature, threshold, simulation type, or demolition type may prevent demolition | Prove the same object can demolish through RayFire alone, then retest the bridge. |
| One hit adds damage twice | Receivers may exist on both the collider and its attached Rigidbody/parent target | Keep one intended receiver path and test the hierarchy one collider at a time. |
| The object breaks on the first small hit | **Damage Multiplier** may be too high, RayFire's threshold may be too low, or the hit may be processed more than once | Measure the damage change from one hit, correct duplicate receivers, then tune the threshold and multiplier. |
| Fragments move with excessive force | Ultimate Character Controller **Impact Force** and RayFire activation/demolition motion may both contribute | Set one force path to zero or a small value, then add the second only when its effect is understood. |
| A pooled or respawned object starts damaged or no longer reacts | RayFire damage/reset state or the receiver lifecycle may not have been restored | Use the supported RayFire reset workflow, confirm damage returns to its initial value, and run a second destruction test. |
| Destruction disappears after loading or differs across clients | The bridge does not persist or replicate RayFire state | Add project-owned save/network state for the destructible object and run impacts on the chosen authority. |
## Related pages
- [Integrations](https://opsive.com/support/documentation/ultimate-character-controller/integrations/)
- [Impact Actions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/action-modules-groups/impact-actions/)
- [Shootable items](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/shootable/)
- [Melee items](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/melee/)
- [Projectiles](https://opsive.com/support/documentation/ultimate-character-controller/objects/trajectory-object/projectile/)
- [Explosions](https://opsive.com/support/documentation/ultimate-character-controller/objects/explosions/)
- [Object Pool](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/object-pool/)
- [Events](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/)
- [RayFire Unity documentation](https://rayfirestudios.com/category/online-help-unity/)
## Developer reference
In the released Ultimate Character Controller V3 source, `SimpleDamage` defaults **Set Damage Impact Data** to `true`, **Invoke On Object Impact** to `false`, **Damage Amount** to `10`, **Impact Force** to `2`, and **Impact Force Frames** to `15`. Treat those as Ultimate Character Controller defaults only; no RayFire-side default was source-verified for the unavailable bridge.
When object-impact notification is enabled, Ultimate Character Controller invokes the callback on the impact collider GameObject, its attached Rigidbody GameObject when different, and the original impact target when different. This is why receiver placement matters and why duplicating `RayFireImpact` through a hierarchy can process one physical hit more than once.
A project-owned RayFire 2 adapter can register for Ultimate Character Controller's `OnObjectImpact` event with an `ImpactCallbackContext`. Read the hit object, collider, position, direction, and strength from `ImpactCollisionData`; treat `ImpactDamageData` as optional; then call only the API supported by the installed RayFire 2 release. Unregister the handler with the same event signature when the receiver is destroyed.
The legacy bridge source was not available in the released Ultimate Character Controller V3 checkout or public package record inspected for this page. Its exact RayFire method calls, RayFire 2 behavior, **Damage Multiplier** default, pooling hooks, save hooks, and network behavior are therefore intentionally not claimed here.
---
# Realistic Car Controller
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/integrations/realistic-car-controller/)
Use the [Realistic Car Controller](https://assetstore.unity.com/packages/tools/physics/realistic-car-controller-16296?aid=1100lGdc) integration when an Ultimate Character Controller character should enter a standard RCC vehicle, hand driving control to RCC, and return to normal character control after exiting.
The integration supplies `RCCDriveSource`. Ultimate Character Controller's **Drive** ability handles detecting, entering, seating, and exiting the character; RCC remains responsible for vehicle physics, controls, and its optional vehicle camera.
## Compatibility boundary
The released Ultimate Character Controller Version 3 checkout inspected for this page includes `RealisticCarController.unitypackage`. Its source implements `RCCDriveSource` against the `RCC_CarControllerV4` and `RCC_Camera` APIs, but the package does not declare a minimum or maximum RCC version.
[Realistic Car Controller](https://assetstore.unity.com/packages/tools/physics/realistic-car-controller-16296?aid=1100lGdc) is now at `5.0.0`, a major update released in May 2026. The inspected Opsive bridge predates that release, so its presence in the Ultimate Character Controller package and **Integrations Manager** does not by itself prove RCC V5 compatibility. Before updating a working project or starting with RCC V5:
1. Import RCC and the Opsive bridge into a version-controlled test project.
2. Confirm that `RCCDriveSource` compiles without missing RCC types.
3. Confirm that the vehicle still contains `RCC_CarControllerV4` and that an RCC camera, when used, exposes the API expected by the bridge.
4. Complete the enter, drive, camera, and exit tests on this page before moving the setup into the production scene.
Do not rename missing RCC types merely to make the bridge compile. Use a bridge explicitly compatible with the installed RCC release or implement a project-owned `IDriveSource` against that release. Realistic Car Controller Pro uses a different API and the separate [`RCCPDriveSource` integration](https://opsive.com/support/documentation/ultimate-character-controller/integrations/realistic-car-controller-pro/).
## Before you begin
- Create and test a vehicle with RCC alone. It should steer, brake, and use its intended camera before Ultimate Character Controller is connected.
- Create a working Ultimate Character Controller Version 3 character with the [Drive ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/detect-object-ability-base/drive/).
- Add a detection collider or trigger for the vehicle and at least one **Move Towards Location** for entry and exit.
- Create and assign the Physic Material that RCC uses for the vehicle. `RCCDriveSource` reads and changes its bounciness at runtime, so this reference cannot be empty.
- Back up the project before changing RCC or replacing the bridge.
## Install the bridge
1. Install and verify the intended RCC release first.
2. In Unity, select **Tools > Opsive > Ultimate Character Controller > Integrations Manager**.
3. Open **Available Integrations** and locate **Realistic Car Controller**. The **Integration** button opens the setup documentation; it does not import the bridge.
4. Download the Ultimate Character Controller Version 3 Realistic Car Controller integration from [Opsive Downloads](https://opsive.com/downloads/), then import `RealisticCarController.unitypackage`.
5. Allow Unity to compile and resolve the first Console error before continuing.
6. Confirm that **Add Component** offers **RCC Drive Source** and that the component shows **Vehicle Layers**, **Physics Material**, **Driver Location**, **Animator ID**, and **Use Car Camera Controller**.
If the package does not compile with the installed RCC generation, stop at this point. The remaining steps cannot correct an API mismatch.
## Set up the vehicle
1. Select the vehicle GameObject that owns `RCC_CarControllerV4`. Add **RCC Drive Source** to that same GameObject; the bridge searches there rather than through the parent hierarchy.
2. Set **Vehicle Layers** to the RCC physics layers that should ignore Ultimate Character Controller's **SubCharacter** layer. The packaged default contains seven masks for project layers 8 through 14. Check the layer names in the current project instead of assuming those numbers still belong to RCC.
3. Assign **Physics Material**. The bridge stores its starting bounciness, sets bounciness to `0` while the vehicle is inactive, and restores the stored value while the character drives.
4. Create a child Transform at the seated position and rotation, then assign it to **Driver Location**.
5. Set **Animator ID** when this vehicle needs a distinct character entry, seated, or exit animation set. Leave it at `0` only when the character Animator is built for that value.
6. Add one or more [Move Towards Location](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/move-towards-location/) components below the Drive Source GameObject. Place them at valid door-side entry and exit positions.
7. Put the vehicle's detection collider on a layer included by the Drive ability's **Detect Layers** and make sure the Drive Source is on that object or a parent.
8. Finish the character-side entry, exit, animation, visibility, and item choices on the [Drive ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/detect-object-ability-base/drive/) page.
Avoid sharing one mutable Physic Material between independently controlled vehicles until the behavior has been tested. Because the bridge changes the material's bounciness, one vehicle can affect another vehicle that uses the same runtime material instance.
## Choose the camera owner
**Use Car Camera Controller** is enabled by default.
- **Use the RCC camera:** keep the option enabled and place one `RCC_Camera` in the scene. After entry completes, the bridge disables the character's Ultimate Character Controller Camera Controller GameObject, enables the RCC camera, and targets the entered vehicle. When exit begins, it switches back to the Ultimate Character Controller camera.
- **Keep the Ultimate Character Controller camera:** disable the option. The bridge leaves both camera systems alone, so configure the active Ultimate Character Controller view type to follow the moving character and vehicle presentation appropriately.
- **Multiple local vehicles:** the bridge uses the first `RCC_Camera` it finds rather than a per-vehicle camera reference. Use one intentional local RCC camera or replace the camera handoff with project-owned logic.
The bridge temporarily disables the RCC camera's **TPS Auto Focus** while that camera is inactive and restores the previous value when RCC takes camera control.
## Choose character input and item behavior
`RCCDriveSource` does not translate Ultimate Character Controller input into RCC input. It enables the RCC vehicle controller after the character is seated, at which point RCC reads its own configured controls.
- Use the Drive ability's input for entering and exiting, and configure steering, throttle, brake, and other vehicle controls in RCC.
- Use **Allow Equipped Slots**, **Can Aim**, and **Disable Mesh Renderers** on Drive to decide whether the character keeps items, can aim, or remains visible while seated.
- Test overlapping bindings deliberately. An input used both to exit and to operate the vehicle can trigger both systems during the same frame.
## How it runs
At scene start, `RCCDriveSource` collects the vehicle's child colliders, finds `RCC_CarControllerV4`, records the assigned Physic Material's bounciness, configures the requested layer collision ignores, and disables RCC vehicle control. If RCC owns the camera, the bridge also disables the found RCC camera.
The Drive ability moves or teleports the character into place. Once entry completes, `EnteredVehicle` enables the RCC controller, restores the vehicle material's bounciness, and hands the camera to RCC when requested. Ultimate Character Controller keeps the character aligned to **Driver Location** and ignores collisions with the colliders reported by the Drive Source.
When a valid exit begins, `ExitVehicle` disables RCC control, sets the material's bounciness to `0`, restores the Ultimate Character Controller camera when needed, and releases the stored character reference. The Drive ability then completes the character's exit and restores ordinary locomotion, collision, items, and animation ownership.
## Verify in Play Mode
1. Start away from the vehicle. Confirm that RCC does not accept driving input before the character enters.
2. Approach the detection volume and confirm the Drive ability identifies the vehicle.
3. Enter the vehicle. Confirm the character uses the intended Move Towards Location or immediate-entry option and reaches **Driver Location**.
4. After entry completes, confirm that RCC accepts steering, throttle, and brake input and that the character does not push against the vehicle colliders.
5. If RCC owns the camera, confirm that the Ultimate Character Controller camera turns off, the RCC camera turns on, and the RCC camera targets the entered vehicle. If Ultimate Character Controller owns the camera, confirm there is still only one active audio listener and intended gameplay camera.
6. Test the selected item, aiming, and mesh-renderer behavior while seated.
7. Exit at every configured location. Confirm RCC input stops as exit begins, the intended camera returns, and the character can move normally after the exit completes.
8. Enter a second time. Confirm the vehicle material, controls, colliders, and camera reset correctly.
9. Repeat with every supported input device. For split-screen or networking, repeat for each player and authority role rather than treating a single local test as sufficient.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| The bridge produces missing-type compiler errors | The inspected bridge expects `RCC_CarControllerV4` and `RCC_Camera`; the installed RCC release may expose a different API | Use a version-matched bridge or implement `IDriveSource` for the installed RCC release. Do not rename RCC classes blindly. |
| `RCCDriveSource` reports that the RCC controller is missing | **RCC Drive Source** and the RCC controller may be on different GameObjects | Put both components on the same vehicle GameObject. |
| Play Mode throws an error while the bridge starts | **Physics Material** or another required reference may be empty | Assign the vehicle's Physic Material and **Driver Location**, then retry in an isolated scene. |
| The vehicle never moves | Entry may not have completed, RCC input may be unconfigured, or another script may keep the controller disabled | Confirm Drive reaches its seated state, then test RCC's own input setup with the enabled vehicle controller. |
| The vehicle moves before entry | Another component may re-enable RCC after `RCCDriveSource` disables it | Give one system ownership of the RCC controller and disable automatic vehicle activation that bypasses the Drive Source. |
| The character collides with or pushes the vehicle | **Vehicle Layers** may not match the current RCC layer setup | Replace the packaged layer masks with the actual RCC physics layers in this project and retest each collider. |
| The character sits at the origin or faces the wrong way | **Driver Location** is missing or misaligned | Assign a dedicated child Transform and align its position and forward direction to the seat. |
| The camera does not switch to RCC | **Use Car Camera Controller** may be disabled, no `RCC_Camera` may exist, or the bridge may find the wrong camera | Enable the option, keep one intentional local RCC camera, and verify it can target the RCC vehicle without Ultimate Character Controller. |
| The Ultimate Character Controller camera does not return after exit | The exit may have been interrupted before the bridge callback or another script may control the camera GameObjects | Confirm Drive reaches a valid exit, then trace camera ownership so only one handoff controls each camera. |
| Exiting does nothing | Drive requires at least one clear Move Towards Location even for immediate entry and exit | Add or clear an exit location below the Drive Source hierarchy. |
| Another vehicle's grip changes | Several vehicles may share the Physic Material whose bounciness the bridge changes | Give independently controlled vehicles separate runtime material instances or replace the shared-material behavior. |
## Saving, networking, and multiple players
The inspected bridge does not save vehicle state, select network authority, synchronize RCC input, or replicate camera ownership.
- Save the vehicle Transform, RCC-specific state, damage, fuel, and occupied/unoccupied state through the project's save system. Restore the Ultimate Character Controller Drive state and camera only through a tested re-entry workflow.
- Let the chosen server or vehicle owner drive the authoritative RCC simulation, then synchronize it through the networking solution used by the project.
- Apply camera and input handoff only for the owning local player. The bridge's scene-wide `RCC_Camera` lookup and GameObject activation are not a split-screen or multiplayer ownership system.
- Decide what happens when a player disconnects, dies, unloads the scene, or saves while seated. The bridge contains no recovery policy for those cases.
## Related pages
- [Drive ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/detect-object-ability-base/drive/)
- [Move Towards Location](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/move-towards-location/)
- [Camera Controller](https://opsive.com/support/documentation/ultimate-character-controller/camera/)
- [Input](https://opsive.com/support/documentation/ultimate-character-controller/input/)
- [Animator parameters](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/animator-parameters/)
- [Integrations](https://opsive.com/support/documentation/ultimate-character-controller/integrations/)
- [Realistic Car Controller Pro](https://opsive.com/support/documentation/ultimate-character-controller/integrations/realistic-car-controller-pro/)
- [Official Realistic Car Controller documentation](https://www.bonecrackergames.com/realistic-car-controller/)
## Developer reference
The packaged `RCCDriveSource` implements `IDriveSource` and exposes the vehicle GameObject, Transform, child colliders, **Driver Location**, and **Animator ID** to the Drive ability. `EnterVehicle` and `ExitedVehicle` do not add bridge behavior. RCC control is enabled in `EnteredVehicle` and disabled in `ExitVehicle`.
The serialized bridge defaults are:
| Field | Packaged default |
| --- | --- |
| **Vehicle Layers** | Seven masks targeting project layers 8 through 14 |
| **Physics Material** | Unassigned |
| **Driver Location** | Unassigned |
| **Animator ID** | `0` |
| **Use Car Camera Controller** | Enabled |
The bridge calls `Physics.IgnoreLayerCollision` between Ultimate Character Controller's **SubCharacter** layer and every configured vehicle layer. This changes the project-wide runtime layer pair, not only collisions for the selected vehicle.
The current Ultimate Character Controller integration manifest still lists Realistic Car Controller asset ID `16296`, and [Ultimate Character Controller 3.0.10 release notes](https://opsive.com/news/ultimate-character-controller-3-0-10-released/) record an RCC integration update. Neither source declares RCC V5 support. The exact compatibility boundary for a newer RCC release must therefore be proven by compiling the packaged source and completing the runtime checks above.
---
# Realistic Car Controller Pro
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/integrations/realistic-car-controller-pro/)
Use the [Realistic Car Controller Pro](https://assetstore.unity.com/packages/tools/physics/realistic-car-controller-pro-178967?aid=1100lGdc) integration when an Ultimate Character Controller character should enter an RCC Pro vehicle, hand driving control to RCC Pro, and return to normal character control after exiting.
The packaged component is `RCCProDriveSource`. Ultimate Character Controller's **Drive** ability handles detecting, entering, seating, and exiting the character; RCC Pro remains responsible for vehicle physics, input, and its optional vehicle camera.
## Compatibility and availability
The local bridge package inspected for this page is named `RealisticCarControllerPro.unitypackage`. It contains `RCCProDriveSource`, which targets the `RCCP_CarController` and `RCCP_Camera` APIs. The package is dated February 2025 and contains no minimum or maximum RCC Pro version metadata.
Current publisher sources describe newer July 2026 releases: the [Unity Asset Store](https://assetstore.unity.com/packages/tools/physics/realistic-car-controller-pro-178967?aid=1100lGdc) lists `2.55.0.LTS`, while the [RCC Pro publisher page](https://www.bonecrackergames.com/realistic-car-controller-pro/) advertises `2.60.0`. Neither source declares compatibility with this Opsive bridge.
The current Ultimate Character Controller Version 3 **Integrations Manager** manifest does not list RCC Pro, although this documentation page and the inspected local package exist. Before planning around the integration:
1. Sign in to [Opsive Downloads](https://opsive.com/downloads/) and confirm that the Ultimate Character Controller Version 3 RCC Pro package is available to the project.
2. Check any package notes for the RCC Pro release it targets.
3. Import RCC Pro and the bridge into a version-controlled test project.
4. Continue only when `RCCProDriveSource` compiles without missing RCC Pro types and passes the runtime checks below.
Do not substitute the standard RCC integration. It uses different controller and camera classes. If the available bridge does not match the installed RCC Pro release, use a compatible package or implement a project-owned `IDriveSource` against that release.
## Before you begin
- Create and test an RCC Pro vehicle without Ultimate Character Controller. Steering, braking, and the intended RCC Pro camera should work first.
- Create a working Ultimate Character Controller Version 3 character with the [Drive ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/detect-object-ability-base/drive/).
- Add a vehicle detection collider or trigger and at least one **Move Towards Location** for entering and exiting.
- Create and assign the Physic Material used by the vehicle. `RCCProDriveSource` reads and changes its bounciness at runtime, so the reference cannot be empty.
- Back up the project before importing or replacing the bridge.
## Install the bridge
1. Install the intended RCC Pro release and use its setup workflow to create a working vehicle.
2. Confirm that the vehicle has `RCCP_CarController` and can be controlled through RCC Pro alone.
3. Download the Ultimate Character Controller Version 3 RCC Pro integration from [Opsive Downloads](https://opsive.com/downloads/). Do not use the **Integrations Manager** entry for standard **Realistic Car Controller** as a substitute.
4. Import `RealisticCarControllerPro.unitypackage` and allow Unity to compile.
5. Resolve the first Console error before configuring the vehicle. Missing `RCCP` types indicate a package or API mismatch, not an Inspector setup problem.
6. Confirm that **Add Component** offers **RCC Pro Drive Source** and that its Inspector shows **Vehicle Layers**, **Physics Material**, **Driver Location**, **Animator ID**, and **Use Car Camera Controller**.
The old page called the component `RCCPDriveSource`. The inspected packaged class is `RCCProDriveSource`; use the class that actually arrives in the verified package.
## Set up the vehicle
1. Select the vehicle GameObject that owns `RCCP_CarController`. Add **RCC Pro Drive Source** to that same GameObject; the bridge searches there rather than through a parent.
2. Set **Vehicle Layers** to the RCC Pro physics layers that should ignore Ultimate Character Controller's **SubCharacter** layer. The packaged default contains four masks for project layers 15 through 18. Verify the actual layer names in the project instead of assuming those numbers still belong to RCC Pro.
3. Assign **Physics Material**. The bridge stores its starting bounciness, sets bounciness to `0` while the vehicle cannot be controlled, and restores the stored value while the character drives.
4. Create a child Transform at the driver's seated position and rotation, then assign it to **Driver Location**.
5. Set **Animator ID** when this vehicle needs its own character entry, seated, or exit animation set. Leave `0` only when the character Animator is built for that value.
6. Add one or more [Move Towards Location](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/move-towards-location/) components below the Drive Source GameObject. Place them at clear door-side entry and exit positions.
7. Put the detection collider on a layer included by the Drive ability's **Detect Layers**. Ensure the Drive Source is on that object or a parent so Drive can find it.
8. Complete the character's entry, exit, animation, visibility, and item choices on the [Drive ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/detect-object-ability-base/drive/) page.
Avoid sharing one mutable Physic Material between independently controlled vehicles until the behavior has been tested. The bridge changes the material's bounciness, so one vehicle can affect another that uses the same runtime material instance.
## Choose the camera owner
**Use Car Camera Controller** is enabled by default.
- **Use the RCC Pro camera:** keep the option enabled and place one `RCCP_Camera` in the scene. After entry completes, the bridge disables the character's Ultimate Character Controller Camera Controller GameObject, enables the RCC Pro camera, and targets the entered `RCCP_CarController`. When exit begins, it switches back to the Ultimate Character Controller camera.
- **Keep the Ultimate Character Controller camera:** disable the option. The bridge leaves both camera systems unchanged, so configure the active Ultimate Character Controller view type for the desired vehicle framing.
- **Multiple local vehicles:** the bridge uses the first `RCCP_Camera` found in the scene instead of a serialized per-vehicle reference. Use one intentional local camera or replace the handoff with project-owned selection logic.
The bridge temporarily disables the RCC Pro camera's **TPS Auto Focus** while that camera is inactive and restores the previous value when RCC Pro takes camera control.
## Choose character input and item behavior
`RCCProDriveSource` does not translate Ultimate Character Controller input into RCC Pro input. After entry completes it calls `SetCanControl(true)` on `RCCP_CarController`; RCC Pro then reads its own configured controls.
- Use Drive's input for entering and exiting. Configure steering, throttle, brake, camera, and mobile controls in RCC Pro.
- Use **Allow Equipped Slots**, **Can Aim**, and **Disable Mesh Renderers** on Drive to decide whether the character keeps items, can aim, or remains visible while seated.
- Test overlapping bindings. An input assigned both to a vehicle action and to exiting can reach both systems during the same frame.
The bridge does not equip, unequip, hide, save, or synchronize items itself. Those choices remain with the Ultimate Character Controller Drive and item systems.
## How it runs
At scene start, `RCCProDriveSource` collects the vehicle's child colliders, requires `RCCP_CarController` on the same GameObject, records the assigned Physic Material's bounciness, configures the requested layer collision ignores, and calls `SetCanControl(false)`. If RCC Pro owns the camera, the bridge also disables the found RCC Pro camera.
The Drive ability moves or teleports the character into place. Once entry completes, `EnteredVehicle` stores the character, restores the vehicle material's bounciness, calls `SetCanControl(true)`, and hands the camera to RCC Pro when requested. Ultimate Character Controller keeps the character aligned to **Driver Location** and ignores collisions with the colliders reported by the Drive Source.
When a valid exit begins, `ExitVehicle` calls `SetCanControl(false)`, sets the material's bounciness to `0`, restores the Ultimate Character Controller camera when needed, and releases the stored character reference. Drive then completes the character's exit and restores ordinary locomotion, collision, items, and animation ownership.
## Verify compilation and Play Mode behavior
1. Import both products into a clean test project and confirm that Unity compiles with no missing `RCCP_CarController`, `RCCP_Camera`, or other RCC Pro API errors.
2. Start away from the vehicle. Confirm that the vehicle does not accept driving input before the character enters.
3. Approach the detection volume and confirm that Drive identifies the vehicle.
4. Enter the vehicle. Confirm the character uses the intended Move Towards Location or immediate-entry option and reaches **Driver Location**.
5. After entry completes, confirm that RCC Pro accepts steering, throttle, and brake input and that the character does not push against the vehicle colliders.
6. If RCC Pro owns the camera, confirm that the Ultimate Character Controller camera turns off, the RCC Pro camera turns on, and it targets the entered vehicle. With the Ultimate Character Controller camera retained, confirm that only the intended gameplay camera and audio listener remain active.
7. Test the chosen item, aiming, and character visibility behavior while seated.
8. Exit from every configured location. RCC Pro control should stop as exit begins, the intended camera should return, and the character should move normally after exit completes.
9. Enter again and repeat the test. Confirm that control, bounciness, colliders, and camera state reset correctly.
10. Repeat for every supported input device. In split-screen or multiplayer, test each local player and authority role separately.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| Importing the bridge produces missing `RCCP` types | The installed RCC Pro API may not match the February 2025 bridge | Obtain a version-matched bridge or implement `IDriveSource` for the installed RCC Pro release. Do not rename RCC Pro classes blindly. |
| **RCC Pro Drive Source** is absent but **RCCP Drive Source** is expected | The old page used a different class name | Inspect the imported package. The locally inspected class is `RCCProDriveSource`; remove stale or duplicate bridge scripts before retrying. |
| The Console says that the RCC controller is missing | The Drive Source and `RCCP_CarController` may be on different GameObjects | Put both components on the same vehicle GameObject. |
| Play Mode throws an error during bridge startup | **Physics Material** or another required reference may be empty | Assign the vehicle's Physic Material and **Driver Location**, then retry in an isolated scene. |
| The vehicle never responds after entry | Drive may not have reached the seated state, RCC Pro input may be unconfigured, or another script may call `SetCanControl(false)` | Confirm `EnteredVehicle` ran, then test the same RCC Pro controls with the vehicle explicitly controllable. |
| The vehicle responds before entry | Another RCC Pro manager or project script may call `SetCanControl(true)` after bridge initialization | Give one system control ownership and disable automatic activation that bypasses the Drive Source. |
| The character collides with or pushes the vehicle | **Vehicle Layers** may not match the current RCC Pro project layers | Replace the packaged masks with the RCC Pro physics layers actually used by the vehicle and retest its child colliders. |
| The character sits at the origin or faces the wrong way | **Driver Location** is missing or misaligned | Assign and orient a dedicated seat Transform. |
| The camera does not switch to RCC Pro | **Use Car Camera Controller** may be disabled, no `RCCP_Camera` may exist, or the bridge may find the wrong camera | Enable the option, keep one intentional local RCC Pro camera, and prove that camera can target the vehicle without Ultimate Character Controller. |
| The Ultimate Character Controller camera does not return | Exit may be blocked or interrupted, or another script may control the camera GameObjects | Confirm Drive begins a valid exit and trace camera ownership so only one handoff controls each camera. |
| Exit input does nothing | Drive still requires at least one clear Move Towards Location | Add or clear an exit location below the Drive Source hierarchy. |
| Another vehicle's grip changes | Several vehicles may share the Physic Material whose bounciness the bridge changes | Give independently controlled vehicles separate runtime material instances or replace the shared-material behavior. |
## Saving, networking, and multiple players
The inspected bridge contains no save integration, authority check, network messages, player-camera selection, or RCC Pro synchronization code. RCC Pro may supply its own networking add-ons, but importing one does not automatically network the Ultimate Character Controller entry and exit workflow.
- Save the vehicle Transform, RCC Pro-specific state, damage, fuel, and occupied/unoccupied state through the project's save system. Restore the player through a tested Drive re-entry workflow.
- Choose one server or owning client to control the authoritative RCC Pro simulation, then synchronize it through the project's networking solution.
- Apply input and camera handoff only for the owning local player. The bridge's scene-wide `RCCP_Camera` lookup is not a split-screen ownership system.
- Define recovery for disconnecting, dying, unloading the scene, or saving while seated. The bridge has no policy for those cases.
## Related pages
- [Drive ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/detect-object-ability-base/drive/)
- [Move Towards Location](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/move-towards-location/)
- [Camera Controller](https://opsive.com/support/documentation/ultimate-character-controller/camera/)
- [Input](https://opsive.com/support/documentation/ultimate-character-controller/input/)
- [Animator parameters](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/animator-parameters/)
- [Integrations](https://opsive.com/support/documentation/ultimate-character-controller/integrations/)
- [Standard Realistic Car Controller](https://opsive.com/support/documentation/ultimate-character-controller/integrations/realistic-car-controller/)
- [Official Realistic Car Controller Pro documentation](https://www.bonecrackergames.com/realistic-car-controller-pro/)
## Developer reference
The packaged `RCCProDriveSource` implements `IDriveSource` and exposes the vehicle GameObject, Transform, child colliders, **Driver Location**, and **Animator ID** to Drive. `EnterVehicle` and `ExitedVehicle` do not add bridge behavior. RCC Pro control is enabled in `EnteredVehicle` and disabled in `ExitVehicle`.
The serialized bridge defaults are:
| Field | Packaged default |
| --- | --- |
| **Vehicle Layers** | Four masks targeting project layers 15 through 18 |
| **Physics Material** | Unassigned |
| **Driver Location** | Unassigned |
| **Animator ID** | `0` |
| **Use Car Camera Controller** | Enabled |
The bridge calls `Physics.IgnoreLayerCollision` between Ultimate Character Controller's **SubCharacter** layer and every configured vehicle layer. This changes the project-wide runtime layer pair rather than only the colliders on the selected vehicle.
The inspected package was not compiled against the current July 2026 RCC Pro release during this documentation update, and neither the package nor the current Opsive integration manifest provides a supported version range. Compatibility must therefore be established through the clean-project compile check and full entry/drive/exit test above.
---
# Rewired
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/integrations/rewired/)
Use the [Rewired](https://assetstore.unity.com/packages/tools/utilities/rewired-21676?aid=1100lGdc) integration when Rewired should own the player, device, action maps, and runtime rebinding while Ultimate Character Controller continues to request movement, look, ability, and item inputs by name.
The bridge adds **Rewired Input** as an Ultimate Character Controller `PlayerInput` implementation. It does not configure device ownership, UI navigation, touch controls, split-screen cameras, or saved bindings by itself.
## Compatibility boundary
The packaged Ultimate Character Controller Version 3 bridge source was last updated in 2023 and declares no minimum or maximum Rewired version. It uses the longstanding `ReInput.players.GetPlayer`, `Player.GetButton`, `Player.GetAxis`, and Rewired mouse APIs. The current [Rewired documentation](https://guavaman.com/projects/rewired/docs/) identifies version `1.1.62.7`, also listed by the Asset Store in March 2026, but neither source states that this particular Opsive bridge was tested against it.
Rewired supplies different installations for different Unity generations. Install the Rewired branch intended for the project's Unity version, then compile the Opsive bridge in a clean test project before replacing input in the main scene. Rewired's own integration list describes the Ultimate Character Controller package as a third-party integration maintained outside Rewired.
The inspected bridge also calls `UnityEngine.Input` directly for Escape, mouse-button cursor capture, and inherited joystick-connected detection. A Rewired release that can use Unity's newer input backend does not remove those bridge-side calls. Test the project's **Active Input Handling** setting on every target platform, and adapt the bridge if that setting makes the legacy calls unavailable.
## Before you begin
- Set up and test the Ultimate Character Controller character, camera, abilities, and items with one existing input implementation first.
- Install [Rewired](https://assetstore.unity.com/packages/tools/utilities/rewired-21676?aid=1100lGdc) and complete its installer for the current Unity version.
- Decide which Rewired Player owns each local character and which devices that Player may use.
- Make a backup before replacing the Rewired Input Manager or importing a sample configuration into an existing Rewired project.
## Install Rewired and the bridge
1. Import Rewired, then run **Window > Rewired > Setup > Run Installer** if its installer does not start automatically.
2. Open **Window > Rewired > Help > About** and confirm the installed Rewired version and Unity branch before continuing.
3. In Ultimate Character Controller, open **Tools > Opsive > Ultimate Character Controller > Integrations Manager** and select **Available Integrations**.
4. Locate **Rewired**. The **Integration** button opens this documentation and **Asset Store** opens Rewired; neither button imports the Opsive package.
5. Download the Ultimate Character Controller Version 3 Rewired integration from [Opsive Downloads](https://opsive.com/downloads/) and import `Rewired.unitypackage` after Rewired is installed.
6. Resolve the first compiler error. Continue only when **Add Component** offers **Rewired Input** with no missing Rewired types.
The package contains the bridge script, one Ultimate Character Controller **Rewired Input Manager** prefab, and separate **Rewired Input Manager Solo** and **Rewired Input Manager Co-op** prefabs under the Ultimate Inventory System folder. For an Ultimate Character Controller-only setup, use the prefab under `Assets/Opsive/Shared/Integrations/Rewired/UltimateCharacterController`, not an inventory-system prefab chosen only by its name.
## Configure the Rewired Input Manager
### Start from the supplied Ultimate Character Controller configuration
For a new Rewired project, drag **Rewired Input Manager** from the integration's `UltimateCharacterController` folder into the scene. The supplied prefab is marked to persist between scene loads and contains one game Player named `Player0`, plus example keyboard, mouse, and joystick maps for common Ultimate Character Controller action names such as `Horizontal`, `Vertical`, `Mouse X`, `Mouse Y`, `Controller X`, `Controller Y`, `Jump`, `Fire1`, `Reload`, `Action`, item selection, and perspective switching.
Treat this prefab as a starting configuration, not a required source of truth. Keep only one active Rewired Input Manager. Adding the persistent prefab to several scenes can create competing managers when scenes change.
### Keep an existing Rewired configuration
Do not replace a working Rewired Input Manager merely to obtain the Ultimate Character Controller actions. Add the Ultimate Character Controller-requested action names to the existing manager, create keyboard, mouse, joystick, or custom-controller maps, and assign those maps to the intended Players.
Every name requested by Ultimate Character Controller must match a Rewired Action exactly, including spaces and capitalization. Changing a key or controller element through Rewired is safe; renaming the Action without updating the Ultimate Character Controller Inspector is not.
## Replace the character input component
1. In Edit Mode, expand the character and select its input GameObject. A character named `Atlas` commonly starts with an `AtlasInput` child.
2. Remove the existing Opsive input implementation from that GameObject, such as **Unity Input System** or legacy **Unity Input**. Keep the input GameObject.
3. Add **Rewired Input** to the same GameObject.
4. Set **Player ID** to the intended Rewired Player ID. The packaged default is `0`.
5. Select the character root. On **Player Input Proxy**, assign the new **Rewired Input** component to **Player Input**.
6. Keep **Horizontal Look Input Name** and **Vertical Look Input Name** matched to Rewired Actions. The inherited defaults are `Mouse X` and `Mouse Y`.
7. Enter Play Mode once and confirm that the proxy moves the input GameObject beneath Ultimate Character Controller's persistent scheduler while continuing to route input to the original character. Do not use its runtime hierarchy position as the player-ownership rule.
## Assign players and devices
Rewired owns controller assignment; **Player ID** only tells this bridge which Rewired Player to read.
- **Single player:** use one Rewired Player, usually ID `0`, and assign the keyboard, mouse, and desired joysticks to it.
- **Local split-screen:** create one Rewired Player per character, give each character its own **Rewired Input** and **Player Input Proxy** reference, and set a different **Player ID** on each bridge. Complete the matching camera, viewport, and HUD setup on [Split Screen](https://opsive.com/support/documentation/ultimate-character-controller/camera/split-screen/).
- **Shared keyboard:** map distinct keys to the intended Players deliberately. The bridge does not divide a keyboard or prevent the same device from controlling several Players.
- **Connect and reconnect:** configure Rewired's controller assignment and reassignment policy. The bridge keeps reading the selected Player, so device changes must update that Player's controllers rather than silently changing the character's **Player ID**.
The supplied Ultimate Character Controller manager prefab defines only one gameplay Player. It is not a ready-made split-screen configuration.
## Configure Unity UI and touch controls
### Unity UI
**Rewired Input** controls Ultimate Character Controller gameplay, not the EventSystem. To navigate Unity UI through Rewired:
1. Select the scene's **EventSystem**.
2. Disable or remove the ordinary **Standalone Input Module**.
3. Add **Rewired Standalone Input Module**.
4. Create the UI Actions requested by that module, map them to the intended Players, and configure which Player IDs may control the UI.
Use separate menu Actions rather than movement and gameplay Actions when rebinding must not leave a player unable to navigate the menu. See Rewired's [Standalone Input Module guide](https://guavaman.com/projects/rewired/docs/RewiredStandaloneInputModule.html) for multi-player EventSystems and Player Mouse setup.
### Touch controls
Build touch controls through Rewired and its custom-controller workflow. Then enable **Enable Touch Controls** on **Rewired Input**. This field does not create or bind any controls; it makes the bridge report that the pointer is not over UI so Rewired's touch controls can continue driving gameplay.
Remove or disable Ultimate Character Controller virtual controls generated for **Unity Input System** or legacy **Unity Input**. Those controls target different input implementations and do not become Rewired controls when this checkbox is enabled.
Test ordinary menus after enabling the option. Because the bridge bypasses its normal pointer-over-UI check, a gameplay action can also respond while the player touches UI unless the menu disables gameplay input or the Rewired maps are switched appropriately.
## Configure rebinding and persistence
Use Rewired's [Control Mapper](https://guavaman.com/projects/rewired/docs/ControlMapper.html) or a project-owned Rewired mapping screen. The bridge continues requesting the same Action name, so a changed key, button, or axis takes effect without changing Ultimate Character Controller.
The supplied Ultimate Character Controller Rewired Input Manager prefab does not include a `UserDataStore` component. Add an appropriate Rewired [User Data Store](https://guavaman.com/projects/rewired/docs/UserDataStore.html) when mappings, calibration, input behavior, or optional controller assignments must persist. Decide when the game saves and loads this data; the Ultimate Character Controller bridge neither invokes the store nor migrates saved maps after the Rewired manager's defaults change.
## Cursor behavior
The integration-specific defaults are:
| Field | Packaged default | Behavior |
| --- | --- | --- |
| **Player ID** | `0` | Reads that Rewired Player. |
| **Disable Cursor** | Enabled | Locks and hides the cursor while the component is active. |
| **Enable Cursor With Escape** | Enabled | Releases the cursor when the physical Escape key is pressed. |
| **Prevent Look Vector Changes** | Enabled | Stops look updates while the cursor is released. |
| **Enable Touch Controls** | Disabled | Uses the normal pointer-over-UI check. |
Escape and the mouse buttons are read through `UnityEngine.Input`, not a Rewired Action. Rebinding an action named `Unlock Cursor` in the sample manager does not change this code path. Use a project-owned cursor action or bridge extension when cursor release must be fully rebindable.
## How it runs
On `Awake`, **Rewired Input** obtains the Rewired Player identified by **Player ID**. Ultimate Character Controller then asks the component for named buttons and axes through the common `IPlayerInput` interface. The bridge forwards those calls to the selected Rewired Player and obtains the mouse position from that Player's assigned Rewired mouse.
Changing **Player ID** through the component property during Play Mode immediately selects the new Rewired Player. Changing controller ownership within Rewired does not require replacing the bridge because the same Player object receives its new devices and maps.
The inherited Ultimate Character Controller input layer still owns look smoothing, tap and double-press timing, death disabling, gameplay-input events, and the `ConnectedController` state. In the inspected bridge, connected-controller detection comes from the global `UnityEngine.Input.GetJoystickNames` result rather than the selected Rewired Player. Do not use that state as proof that a particular Player owns a joystick.
## Verify compilation and Play Mode behavior
1. Confirm that Rewired and `RewiredInput.cs` compile with no missing types in the target Unity version.
2. Enter Play Mode with one Rewired Input Manager and one character using **Rewired Input**. Confirm that `Horizontal`, `Vertical`, the two look Actions, `Jump`, `Fire1`, `Reload`, and `Action` reach the intended character.
3. Change a keyboard or controller element assignment while keeping the Rewired Action name. The corresponding Ultimate Character Controller behavior should follow the new assignment.
4. Press Escape, then click outside UI. Confirm the cursor releases, look pauses, and the cursor recaptures according to the configured fields.
5. Open a menu. Confirm the Rewired UI module navigates and submits through the intended Player while gameplay input is disabled or its maps are inactive.
6. Disconnect and reconnect each controller. Confirm Rewired restores the intended Player ownership and only that character responds.
7. For split-screen, test one device at a time. Each device should move, look, use items, and navigate only the intended character and UI.
8. Test touch controls on the target device, not only with a mouse in the Editor. Confirm touches do not leak through menus into gameplay.
9. Change a binding, restart the build, and confirm the selected User Data Store restores it.
10. Repeat the test in a development build for every target platform and **Active Input Handling** configuration the project supports.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| Importing the bridge produces missing `Rewired` types | Rewired may be absent, installed for another Unity generation, or incompletely installed | Install the correct Rewired branch first and rerun **Window > Rewired > Setup > Run Installer**, then reimport the bridge. |
| **Rewired Input** cannot find its Player | **Player ID** may not exist or the Rewired Input Manager may initialize incorrectly | Keep one active manager, create that Player in Rewired, and use its exact ID. |
| The character does not respond but Rewired sees the device | An Ultimate Character Controller input name may not match a Rewired Action, its Controller Map may be disabled, or **Player Input Proxy** may reference the old component | Match the Action name, enable the map for the selected Player, and assign **Rewired Input** on the proxy. |
| Two characters respond to one device | They may share **Player ID**, or Rewired may assign the device to both Players | Give each bridge the intended Player ID and correct the device and map ownership in Rewired. |
| The mouse cannot aim or move the cursor | The selected Player may not own the Rewired mouse | Assign the mouse to that Player or provide a Player Mouse workflow appropriate for the game. |
| Gameplay works but menus do not | The EventSystem may still use Unity's input module or its UI Action names may be unmapped | Add **Rewired Standalone Input Module**, create matching UI Actions, and assign their maps to the intended Players. |
| A binding change disappears after restart | The Rewired Input Manager may have no User Data Store, or saved data may not be loaded | Add and configure a `UserDataStore`, save at the required lifecycle points, and test a clean restart. |
| New default mappings do not appear during development | Previously saved Rewired user data may override the manager's changed defaults | Clear the test save or migrate the saved maps according to Rewired's User Data Store guidance. |
| Ultimate Character Controller virtual controls do nothing | They were generated for Unity Input System or legacy Unity Input, not Rewired | Remove them and build the touch layout through Rewired; then enable **Enable Touch Controls**. |
| Touching a menu also triggers gameplay | **Enable Touch Controls** makes the bridge ignore its normal pointer-over-UI block | Disable gameplay input while the menu owns input or switch the selected Rewired map category. |
| The cursor shortcut or controller-connected state behaves differently from Rewired | Those bridge paths still use `UnityEngine.Input` globally | Test **Active Input Handling** and replace the cursor or device-state path when per-player Rewired behavior is required. |
## Saving and networking boundaries
The bridge reads local input only. It does not save Rewired data, assign network authority, transmit input, or distinguish a local owner from a remote character.
- Add **Rewired Input** only for the owning local character, or ensure the networking layer disables the input GameObject for remote characters.
- Keep Player IDs and device assignment as local-session data unless the game's own profile system intentionally persists them.
- Save mappings through Rewired's User Data Store, not the Ultimate Character Controller save system unless a project-specific adapter explicitly connects them.
- In split-screen networking, establish local Rewired ownership before mapping each local character to its network object and camera.
## Related pages
- [Input](https://opsive.com/support/documentation/ultimate-character-controller/input/)
- [Virtual Controls](https://opsive.com/support/documentation/ultimate-character-controller/input/virtual-controls/)
- [Split Screen](https://opsive.com/support/documentation/ultimate-character-controller/camera/split-screen/)
- [Camera Controller](https://opsive.com/support/documentation/ultimate-character-controller/camera/)
- [Events](https://opsive.com/support/documentation/ultimate-character-controller/programming-concepts/events/)
- [Integrations](https://opsive.com/support/documentation/ultimate-character-controller/integrations/)
- [Rewired documentation](https://guavaman.com/projects/rewired/docs/)
## Developer reference
The packaged source is `Assets/Opsive/Shared/Integrations/Rewired/RewiredInput.cs`. `RewiredInput` derives from Ultimate Character Controller's `PlayerInput` and forwards `GetButton`, `GetButtonDown`, `GetButtonUp`, `GetAxis`, and `GetAxisRaw` to the selected `Rewired.Player`. Its `PlayerID` property changes the selected Player immediately during Play Mode.
The component overrides `GetMousePosition` with `m_Player.controllers.Mouse.screenPosition`. It overrides `IsPointerOverUI` only when **Enable Touch Controls** is enabled, returning `false` rather than querying the EventSystem.
The inspected integration package contains no custom rebinding UI, `UserDataStore`, Rewired UI input module, networking implementation, or save adapter. Those responsibilities remain with Rewired and project code. Because no supported Rewired range is encoded in the package, compile and runtime verification remain the compatibility test for the installed Rewired and Unity versions.
---
# State Designer
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/integrations/state-designer/)
Use the [State Designer](https://assetstore.unity.com/packages/tools/visual-scripting/state-designer-dots-powered-finite-state-machines-369152?aid=1100lGdc) integration when a finite state machine should choose an AI or gameplay mode while Ultimate Character Controller owns locomotion, collision, animation, abilities, items, health, attributes, and effects.
## Before you begin
- Install released Ultimate Character Controller Version 3 and State Designer, then verify both products independently.
- Build the character as an **AI Agent** when State Designer will control a non-player character.
- Configure and test navigation, items, health, and the required abilities before requesting them from a State Machine.
- Sign in to [Opsive Downloads](https://opsive.com/downloads/) and download the matching State Designer integration after both products compile. The bridge is not included in either base product's Integrations folder before this download. Importing `UltimateCharacterControllerStateDesigner.unitypackage` creates the integration files in the project.
## Build a first Patrol, Chase, and Attack flow
1. Add a State Machine to the AI character and create Patrol, Chase, and Attack States.
2. Use project sensing Conditions to choose a target. The Ultimate Character Controller bridge does not add sight or hearing.
3. In Chase, set the navigation destination and let Ultimate Character Controller's pathfinding movement ability apply final motion.
4. In Attack, use **Set Aim Target**, then **Start Stop Ability** or **Start Stop Use** for the configured item slot and action.
5. On State exit, stop abilities that should not remain active and clear temporary aim or target data.
6. Use **Is Ability Active**, **Is Effect Active**, **Is Alive**, or other integration Conditions to drive transitions instead of reading Animator state directly.
## Available Ultimate Character Controller nodes
- **Abilities and effects:** Start Stop Ability, Is Ability Active, Start Stop Effect, and Is Effect Active.
- **Items and aiming:** Set Aim Target, Start Stop Use, Reload, Start Equip Unequip, Start Item Set Ability, and Get Item Identifier Amount.
- **Health and state:** Damage, Heal, Is Alive, Has Taken Damage, Get Attribute Value, Set State, and Execute Event.
These nodes call Ultimate Character Controller systems; they do not replace Ultimate Character Controller validation. An Action can fail when a required component is missing or Ultimate Character Controller rejects the requested ability.
## Verify in Play Mode
1. Watch the active State and Ultimate Character Controller's active abilities together.
2. Confirm Patrol and Chase move through one authority and use the expected movement animation.
3. Confirm Attack aims at the intended object and controls the expected item slot and action.
4. Force Ultimate Character Controller to block an ability and confirm the State Machine follows its fallback.
5. Test State exit, interruption, death, respawn, perspective changes, and scene reload.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| Ultimate Character Controller nodes are absent from the State Palette. | Check compilation, both products, and the imported bridge package. | Install both dependencies first, remove duplicate bridge scripts, and reimport the matching package. |
| The character does not move. | Check the navigation owner, baked navigation data, AI Agent setup, and pathfinding movement ability. | Let State Designer choose the destination and let Ultimate Character Controller apply final movement. |
| Use or Reload targets the wrong item. | Check active item set, Slot ID, and Action ID. | Select the exact equipped item action rather than relying on the first available ability. |
| A State exits but an ability remains active. | Check the State exit Actions and the ability's normal Stop Type. | Stop the ability explicitly or configure the intended Ultimate Character Controller stop rule. |
## Related pages
- [State Designer integration guide](https://opsive.com/support/documentation/state-designer/integrations/ultimate-character-controller/)
- [Artificial Intelligence](https://opsive.com/support/documentation/ultimate-character-controller/artificial-intelligence/)
- [Abilities](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/)
- [NavMeshAgent Movement](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/navmeshagent-movement/)
- [Use](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/item-abilities/use/)
---
# Ultimate Inventory System
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/integrations/ultimate-inventory-system/)
Use the [Ultimate Inventory System](https://assetstore.unity.com/packages/tools/game-toolkits/ultimate-inventory-system-166053?aid=1100lGdc) integration when Ultimate Inventory System should own a character's Items, Item Collections, inventory UI, and saved inventory data while Ultimate Character Controller equips, animates, and uses the corresponding Character Items.
For example, an Ultimate Inventory System Iron Sword can move from a Bag into an equipment collection, cause its Ultimate Character Controller Character Item prefab to appear in the correct hand, activate a valid Ultimate Character Controller Item Set, and return to the Bag when unequipped. The integration keeps those two representations synchronized; it is not a second inventory to maintain beside Ultimate Inventory System.
## Compatibility boundary
The checked-in Ultimate Character Controller Version 3 installer inspected for this page identifies itself as integration `3.0.5`. Its Integration Inspector requires:
- Ultimate Character Controller `3.0.10+`
- Ultimate Inventory System `1.2.16+`
The current public releases are [Ultimate Character Controller `3.3.6`](https://opsive.com/news/ultimate-character-controller-3-3-6-released/) and [Ultimate Inventory System `1.3.8`](https://opsive.com/news/ultimate-inventory-system-1-3-8-released/). The [Ultimate Inventory System `1.3.6` release notes](https://opsive.com/news/ultimate-inventory-system-1-3-6-released/) also state that this integration was updated. Because that refreshed package is distributed through Opsive Downloads and may be newer than the checked-in installer, do not treat the `3.0.10` and `1.2.16` minimums as a tested maximum-version guarantee. Recheck the downloaded package's version block under **Tools > Opsive > Ultimate Inventory System > Integrations Manager > Integration Inspectors > Ultimate Character Controller** after updating either product.
Ultimate Character Controller Version 4 and Ultimate Inventory System Version 2 use different development APIs and are outside this page's scope. The exact labels and APIs below were verified against the source-visible `3.0.5` bridge; if a newer downloaded bridge reports different requirements or controls, its Inspector and source take precedence.
The integration is compiled directly against Ultimate Character Controller, Ultimate Inventory System, and Opsive Shared. It does not include compatibility shims for missing products or later major versions, so install both products and let them compile before importing the bridge.
## Understand which system owns each job
| Job | Runtime owner |
| --- | --- |
| Item identity, quantity, mutable attributes, categories, definitions, currencies, and collections | Ultimate Inventory System **Inventory** and its Inventory Database |
| Bag, equipment, hotbar, shop, crafting, and other inventory UI | Ultimate Inventory System UI and Item Actions |
| Translating Ultimate Inventory System equippable Items into Ultimate Character Controller Character Items and Item Sets | **Character Inventory Bridge** and **Inventory Item Set Manager** |
| Visible Character Item prefabs, item slots, equip/use abilities, animation, and item states | Ultimate Character Controller Version 3 |
| Inventory contents and active Item Set indexes across save/load | **Inventory Bridge Saver** with **Inventory System Manager Item Saver** |
An Item in the Ultimate Inventory System **Default** collection is owned but not equipped. An Item in a collection listed under **Bridge Item Collection Names** is available to Ultimate Character Controller and may be soft equipped. It becomes actively equipped only when the corresponding Ultimate Character Controller Item Set is active.
Use the **Equippable** category only for Items that require an Ultimate Character Controller Character Item, such as weapons, shields, usable tools, or a gameplay ability represented by a Character Item. Ordinary ammo, materials, consumables, and Ultimate Inventory System-only armor should not inherit from **Equippable**.
## Before you begin
- Install Ultimate Character Controller Version 3 and Ultimate Inventory System Version 1, then resolve all compiler errors.
- Create and test the Ultimate Character Controller character with **Tools > Opsive > Ultimate Character Controller > Character Manager** before converting it.
- Decide which Ultimate Inventory System Inventory Database and Inventory System Manager the scene will use.
- Save the scene and create a source-control checkpoint. **Setup Character** removes the standard Ultimate Character Controller Inventory and Item Set Manager and replaces them with the integrated components.
- Start with one simple single-slot weapon. Add multi-slot weapons, armor, ammo persistence, and menus only after that first item equips correctly.
## Install the integration
1. Sign in to [Opsive Downloads](https://opsive.com/downloads/) and download the current Ultimate Inventory System integration for Ultimate Character Controller Version 3. 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 `Assets/Opsive/UltimateCharacterController/Integrations/UltimateInventorySystem` in the project. Remove duplicate scripts from an older bridge before importing a replacement.
3. Open **Tools > Opsive > Ultimate Inventory System > Integrations Manager**.
4. Select **Integration Inspectors**, then **Ultimate Character Controller**.
5. Record the integration version and requirements shown by the downloaded package. The inspected `3.0.5` package reports Ultimate Character Controller `3.0.10+` and Ultimate Inventory System `1.2.16+`.
The package includes a reference scene at `Assets/Opsive/UltimateCharacterController/Integrations/UltimateInventorySystem/Demo/Demo.unity`. Use it to inspect collection layouts, Item Set Rules, Item Actions, pickups, bindings, and ammo modules. Copy the pattern into project-owned assets rather than editing the integration demo or database directly.
## Prepare the database and scene
### Duplicate the supplied database
The supplied `EmptyCharacterInventoryDatabase` is the safest starting point because it already contains the bridge's required category and attribute structure.
1. Open **Tools > Opsive > Ultimate Inventory System > Main Manager**.
2. Assign `EmptyCharacterInventoryDatabase` from the integration's `EmptyDatabase` folder to **Database**.
3. Open the options menu beside **Database** and select **Duplicate**.
4. Save the duplicated database in a project-owned folder outside the integration package and keep it selected in the Main Manager.
5. Under **Setup > Scene Setup**, add or update the Ultimate Inventory System scene components.
6. Select the scene's **Inventory System Manager** and confirm that **Database** references the same duplicated asset.
Do not duplicate only the main `.asset` in the Project window. The Main Manager's **Duplicate** command copies the database-owned categories and definitions into a coherent new database.
The supplied database establishes these integration conventions:
| Category | Purpose |
| --- | --- |
| **Equippable** | Abstract parent for every Item that can create an Ultimate Character Controller Character Item. |
| **Single Item** | Inherits **Equippable** and supplies one Item Definition `GameObject` Attribute named `Prefabs`. |
| **Multi Item** | Inherits **Equippable** and supplies a `GameObject[]` Item Definition Attribute named `Prefabs`. |
| **Ammo** | Parent for ammo Item Definitions stored as Ultimate Inventory System quantities. |
| **Item With Ammo** | Supplies a mutable Item Attribute named `AmmoData` for the ammo definition, clip size, and rounds currently loaded. |
You may add more categories and multiple inheritance for the game's organization. Keep the **Equippable** relationship and the `Prefabs` Attribute type intact unless the matching **Character Item Prefabs Attribute Name** on every bridge is deliberately changed.
## Connect a character
1. Put the finished Ultimate Character Controller character in the scene.
2. Ensure the Ultimate Inventory System Main Manager and the scene's Inventory System Manager both reference the intended database.
3. Open **Tools > Opsive > Ultimate Inventory System > Integrations Manager**.
4. Select **Integration Inspectors > Ultimate Character Controller > Character Setup**.
5. Assign the scene object to **Character**. **Setup Character** is enabled only when the object has **Ultimate Character Locomotion**.
6. Select **Setup Character** and wait for the success message.
7. Select the character and inspect every component and collection before creating Items.
Character Setup creates these Ultimate Inventory System Item Collections:
| Collection | Type and purpose |
| --- | --- |
| **Default** | Main Item Collection for owned Items that are not currently equipped. |
| **Equippable Slots** | Equipped Item Slot Collection with generated **Primary**, **Secondary**, and **Tactical** slots. |
| **Equippable** | Additional bridge Item Collection for equippable Items that do not use that slot layout. |
| **Loadout** | Character Loadout Item Collection for Items granted by the configured loadout rather than restored save contents. |
It also adds **Character Inventory Bridge**, **Inventory Item Set Manager**, **Inventory Identifier**, **Item User**, **Currency Owner**, **Inventory Interactor**, and **Inventory Bridge Saver**. Existing Ultimate Character Controller Item Set abilities remain on the character; setup attempts to remap their categories to the selected Ultimate Inventory System database and logs a warning when a match cannot be found.
Review these bridge fields first:
- **Equippable Category** points to the database's **Equippable** category.
- **Character Item Prefabs Attribute Name** is `Prefabs`.
- **Default Item Collection Name** is `Default`.
- **Bridge Item Collection Names** contains every collection that should make Character Items available to Ultimate Character Controller, normally `Equippable Slots` and `Equippable`.
- **Loadout Item Collection Names** contains `Loadout` or the exact project-owned loadout names.
- **Inventory Identifier > ID** is unique for every persistent character Inventory.
- **Item User > Inventory Input** resolves the same Opsive player-input component that controls the Ultimate Character Controller character.
Collection names are exact runtime identifiers. Renaming a collection without updating the bridge, Item Actions, UI, saver assumptions, and Item Set Rules breaks the ownership chain.
## Create the first equippable item
Use a single Iron Sword to prove the full workflow before adding special cases.
1. Open **Tools > Opsive > Ultimate Character Controller > Item Manager** and create the Iron Sword's Ultimate Character Controller Character Item prefab. Configure its slot, perspective objects, Item Actions, Animator IDs, and events as described in [Item Creation](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-creation/).
2. In the Ultimate Inventory System database, create or choose a Sword category that inherits from **Equippable** and **Single Item**. Use **Multi Item** only when one Ultimate Inventory System Item Definition needs more than one Ultimate Character Controller Character Item prefab, such as the same weapon in either hand.
3. Create the **Iron Sword** Item Definition. Under its inherited Item Definition Attributes, assign the Ultimate Character Controller Character Item prefab to `Prefabs`.
4. On **Character Inventory Bridge**, confirm that **Character Item Prefabs Attribute Name** is also `Prefabs`.
5. On **Inventory Item Set Manager**, add a rule that accepts the Iron Sword in the Character Item's Ultimate Character Controller slot.
6. Add the integration's **Character Equip Unequip** Item Action to the Ultimate Inventory System Item Action Set used by the equipment menu.
7. Give the character one Iron Sword in **Default** and complete the Play Mode checks below.
The Ultimate Inventory System Item Definition replaces the old Ultimate Character Controller Item Type as the integrated Item's identity. Do not create a second Ultimate Character Controller Item Type and try to keep it synchronized with the Ultimate Inventory System definition. The Character Item prefab supplies Ultimate Character Controller behavior; the Ultimate Inventory System Item carries identity, amount, and persistent attributes.
## Choose the Item Set Rule
**Inventory Item Set Manager** recomputes Item Sets whenever an Ultimate Inventory System Item enters or leaves a bridge collection. Choose the narrowest rule that expresses the intended loadout:
| Rule | Use it when |
| --- | --- |
| **Item Category Item Set Rule** | Any Item inheriting a category may occupy a slot, such as any one-handed blade in the right hand. It also supports definition and category exceptions. |
| **Item Definition Item Set Rule** | One exact definition or exact combination needs its own Item Set, state, or animation behavior. |
| **Item Slot Collection Item Set Rule** | The Ultimate Inventory System Item Slot Collection itself should map directly to Ultimate Character Controller slots. Its default collection name is `Equippable Slots`. |
Keep separate Item Set groups only when more than one set may be active at the same time. For example, a weapon group and a magic group can combine independently without authoring every weapon-plus-magic permutation.
Set each rule's state deliberately. Ultimate Character Controller applies that state while the generated Item Set is active, so a Bow, Sword and Shield, or Body setup can select its matching Animator and ability presets. Use [Item Set Rules](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-set-rules/) for the underlying Ultimate Character Controller behavior.
### Understand soft and active equipment
- **Unequipped:** the Item is normally in **Default** and has no active Character Item.
- **Soft equipped:** the Item is in a bridge collection, so the bridge can create its Character Item, but its Item Set is not active. This is useful for a holstered weapon.
- **Active equipped:** the Item is in a bridge collection and its Item Set is active, so Ultimate Character Controller equips and can use its Character Item.
The default **Character Equip Unequip** action moves an Item between **Default** and a bridge collection and asks Ultimate Character Controller to equip or unequip it. Its advanced **Not Move Equip** option changes only active versus soft-equipped state; use that option only when another workflow already owns the collection move.
## Bind Item attributes to Character Item behavior
Persistent values should live on the Ultimate Inventory System Item, not only on a spawned Character Item prefab.
- Use Ultimate Inventory System **Item Binding** when a top-level component property should read or write an Item Attribute.
- Use the integration's **Item Object Binding** inside an Ultimate Character Controller State Object binding list when an Item Attribute should drive a property on an Item Action Module, Impact Action, Item Effect, or another bound State Object.
- The Attribute value type and target property type must match.
- The spawned Character Item needs an **Item Object** that resolves the Ultimate Inventory System Item before its bindings can update.
Good binding candidates include damage, impact force, color, durability, or a project-specific modifier. First prove the prefab with fixed values; then move only the values that genuinely need to persist or vary per Ultimate Inventory System Item into Attributes.
## Configure a shootable weapon and ammo
Use Ultimate Inventory System Items for reserve ammunition and the integration's `AmmoData` Attribute when a weapon's loaded rounds and clip size must stay with that individual Item.
1. Create an ammo Item Definition under the **Ammo** category, such as **Rifle Bullet**. Store its reserve quantity in the character's normal Ultimate Inventory System Inventory.
2. Make the weapon's category inherit from both **Single Item** or **Multi Item** and **Item With Ammo** so it remains equippable and its runtime Item has a mutable `AmmoData` Attribute.
3. Set `AmmoData` to the ammo Item Definition, clip size, and starting clip amount.
4. On the Ultimate Character Controller Shootable Action, add **Inventory Item Ammo** to the Ammo Module Group.
5. Enable **Use Ammo Data** and keep **Ammo Data Attribute Name** as `AmmoData`, or assign **Ammo Item Definition** directly when every instance of that weapon uses the same ammo and no per-Item choice is required.
6. Leave **Ammo Item Collection Names** empty to use the Inventory's Main collection, or list the exact collections that may supply reserve ammunition.
7. Add **Inventory Ammo Data Clip** to the Clip Module Group and use the same **Ammo Data Attribute Name**.
8. If the Ultimate Inventory System inventory view shows weapon ammunition, add **Weapon Ammo Item View Module** to the Item View and connect its loaded, clip-size, reserve-count, and optional ammo-icon controls.
**Inventory Item Ammo** consumes Ultimate Inventory System ammo Items. **Inventory Ammo Data Clip** writes the changing loaded count back to the weapon Item's `AmmoData` Attribute. Together they allow a partially loaded weapon to keep its own clip when it is unequipped, transferred, saved, and restored.
## Configure pickups and drops
Choose one interaction model for each pickup:
- Use the integration's **Inventory Item Pickup** when the object should be collected through Ultimate Character Controller's Pickup ability.
- Use an ordinary Ultimate Inventory System pickup or Inventory Interactable when Ultimate Inventory System interaction should own the collection step.
To create an integration pickup:
1. Open **Tools > Opsive > Ultimate Inventory System > Integrations Manager**.
2. Under **Ultimate Character Controller > Item Pickup Setup**, assign the Ultimate Character Controller prefab to **Character Item** and an optional visible object to **Pickup Model Object**.
3. Select **Setup Item Pickup** and save the generated prefab in a project-owned folder.
4. On **Inventory Item Pickup**, choose whether to **Equip On Pickup**, **Pickup Item Copies**, and **Remove Items On Pickup**.
5. Confirm that the pickup's Ultimate Inventory System Inventory contains the intended Item and amount.
The setup creates the required collider, trigger, Ultimate Inventory System Inventory, **Inventory Item Pickup**, and Ultimate Character Controller trajectory support. When a Character Item was supplied, it also assigns the generated prefab to that Character Item's **Drop Prefab** and seeds the pickup Inventory with its Item Definition.
For character-driven dropping, configure **Character Inventory Bridge > Item Drop**:
- **Inventory Item Pickup Prefab** is the generic drop prefab and must contain an Ultimate Inventory System Inventory and **Inventory Item Pickup**.
- **Drop Using Character Item When Possible** uses the active Character Item's **Drop Prefab** when available; otherwise the generic prefab is used.
- **Item Drop Position Offset** controls the spawn offset from the character.
Use the integration's **Character Drop** or **Character Quantity Drop** Item Action so the bridge can unequip, remove, and create the correct pickup in one workflow.
## Equip clothes and skinned armor
Pure clothing and armor should normally remain an Ultimate Inventory System equipment workflow rather than becoming Ultimate Character Controller Character Items.
1. Create a separate Ultimate Inventory System Item Slot Collection such as `Armor Equipped` with purpose **Equipped** and an Item Slot Set for Head, Chest, Legs, or the slots the game needs.
2. Do not make those armor categories inherit from the bridge's **Equippable** category unless the item genuinely needs Ultimate Character Controller Item Actions and abilities.
3. Add Ultimate Inventory System **Equipper** to the character and point **Equipment Item Collection ID** to `Armor Equipped`.
4. Use the same Item Slot Set on the collection, Equipper, and equipment UI.
5. Assign the armor visual through `EquipmentPrefab`. Add `UsableItemPrefab` only when the Ultimate Inventory System Equipper workflow also needs a functional Item Object.
6. Enable **Skinned Equipment** for deforming armor and verify its bones against the character rig.
7. Use Ultimate Inventory System **Move To Collection Item Action** for armor. Reserve **Character Equip Unequip** for bridge Items that must activate an Ultimate Character Controller Item Set.
This separation prevents a shirt or helmet from accidentally becoming an active weapon while still allowing Ultimate Inventory System to display, save, and rebuild the equipped visuals. Follow [Equipping Items](https://opsive.com/support/documentation/ultimate-inventory-system/item-objects/equipping-items/) for the complete Equipper workflow.
## Configure inventory actions, UI, and input
Build the Bag, equipment, hotbar, and menu with Ultimate Inventory System. Use integration actions only where the operation must pass through Ultimate Character Controller:
| Ultimate Inventory System Item Action | Result |
| --- | --- |
| **Character Equip Unequip** | Moves and equips, unequips, or changes active versus soft-equipped state through the bridge. |
| **Character Use** | Equips an Item when necessary and starts its Ultimate Character Controller Use ability. If the action had to equip the Item first, it unequips it after use completes. |
| **Character Drop** | Drops the selected Item through the character bridge. |
| **Character Quantity Drop** | Opens the quantity picker when needed, then drops that amount through the bridge. |
| **Character Modify Attribute** | Changes one named Ultimate Character Controller Attribute from Ultimate Inventory System Item Attribute values and can consume the Item. |
| **Character Modify Attributes** | Applies multiple configured Ultimate Inventory System-to-Ultimate Character Controller Attribute changes in one use. |
Use ordinary Ultimate Inventory System actions for Ultimate Inventory System-only operations such as moving armor between Bag and an armor Item Slot Collection.
The integration also supplies **Character Equipped Select Item View Module** to distinguish unequipped, soft-equipped, and active-equipped Item Views, and **Weapon Ammo Item View Module** to display current shootable ammo.
Character Setup assigns the detected Opsive player input to **Item User > Inventory Input**. Verify that reference after conversion, particularly when the project uses Unity's Input System or a third-party input integration. Do not leave two active `IPlayerInput` implementations on one player.
For a full-screen menu:
1. Use Ultimate Inventory System **Enable Disable Inventory Input** to disable gameplay inventory handlers while the menu is enabled and restore them when it closes.
2. Keep the menu's EventSystem, UI input module, and close action active.
3. Use **Display Panel Manager Handler** for the panel shortcuts and cursor behavior.
4. Test that Ultimate Character Controller movement and Item Actions stop while the menu owns input and resume after it closes.
See [Ultimate Inventory System Input](https://opsive.com/support/documentation/ultimate-inventory-system/input/) for backend, EventSystem, action-map, and local-player ownership setup.
## Apply Item-driven character states
Use **Item To Character State Binding** when owning or equipping an Item should activate one or more Ultimate Character Controller states without creating a custom script.
1. Add a string Item Attribute such as `State` to the relevant Ultimate Inventory System category or definition.
2. Add **Item To Character State Binding** to the character.
3. Assign **Inventory Bridge**, set **Item Collection Name** to the collection to watch, and set **State Attribute Name** to `State`.
4. Put one or more Ultimate Character Controller state names in the Item Attribute. Separate multiple names with commas.
The component reevaluates the watched collection whenever it changes, activates states named by current Items, and deactivates states that are no longer present. Use a dedicated collection when a state should apply only while equipped rather than merely owned. See [State System](https://opsive.com/support/documentation/ultimate-character-controller/state-system/) for state and preset behavior.
## Save the integrated Inventory
Use **Inventory Bridge Saver** on the converted character. Do not also add the standard Ultimate Inventory System **Inventory Saver** to that Inventory; it does not preserve the bridge's active Item Set state and is not compatible with this character workflow.
1. Set up the Ultimate Inventory System **Save System Manager**.
2. Add **Inventory System Manager Item Saver** so mutable and unique Ultimate Inventory System Items are serialized once.
3. Keep **Inventory Bridge Saver** on the same GameObject as the bridged Ultimate Inventory System Inventory and Ultimate Character Controller character.
4. Give every saved character a unique **Inventory Identifier > ID**.
5. Keep the Item Collection order and Item Set group structure stable after shipping save files.
6. Save with an Item equipped, change both its collection and active Item Set, then load the same slot.
**Inventory Bridge Saver** records each non-Loadout collection by index and the active Item Set index for each group. During loading it unequips and clears the previous bridge state, restores the saved Items, waits one frame for Character Items to initialize, and then restores the active Item Sets. Loadout collections are deliberately handled as loadout rather than saved inventory contents.
Follow [Ultimate Inventory System Save System](https://opsive.com/support/documentation/ultimate-inventory-system/save-system/) for save slots, UI, and custom save-system nesting.
## Migrate an existing Ultimate Character Controller item setup
Treat migration as a change of inventory ownership, not a field-for-field conversion.
1. Make every existing Ultimate Character Controller Item a tested Character Item prefab using the current [Item Creation](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-creation/) workflow.
2. Record its slot, Animator IDs, Item Actions, Item Set rules, loadout, pickup prefab, and state dependencies.
3. Create a project checkpoint, select the Ultimate Inventory System database, and run **Setup Character**.
4. Create one Ultimate Inventory System Item Definition per inventory identity and assign the corresponding Character Item prefab through `Prefabs`.
5. Rebuild or review the rules on **Inventory Item Set Manager**. Resolve every category-remapping warning from Character Setup.
6. Replace direct Ultimate Character Controller inventory grants with Ultimate Inventory System loadouts, pickups, shops, crafting, or project code.
7. Replace UI equip/drop/use actions with the integration actions where Ultimate Character Controller must participate.
8. Validate saving with **Inventory Bridge Saver** before removing the old scene or prefab setup.
Do not copy an old Item's scene instance into the Ultimate Inventory System pickup **Drop Prefab**. An Ultimate Character Controller Character Item prefab runs on the character; a pickup prefab is a world object with its own Inventory and pickup component.
## Editor checkpoint
Before entering Play Mode, confirm that:
- the Integration Inspector's version and requirement block has been reviewed and the bridge has no compile errors;
- the Main Manager and scene Inventory System Manager use the same project-owned database;
- the character has Ultimate Inventory System **Inventory**, **Character Inventory Bridge**, **Inventory Item Set Manager**, **Item User**, and **Inventory Bridge Saver**;
- **Default**, **Equippable Slots**, **Equippable**, and **Loadout** exist in the expected order and match the bridge's names;
- **Equippable Category** and every Item Set group category belong to the current database;
- every equippable definition inherits from **Single Item** or **Multi Item** and its `Prefabs` value has the correct type;
- each Character Item prefab has the intended Ultimate Character Controller slot and a matching Item Set Rule;
- the Ultimate Inventory System Item Action Set uses **Character Equip Unequip** for weapons;
- **Item User > Inventory Input** points to the correct local player's Opsive input;
- each **Inventory Identifier** ID is unique;
- ammo Attribute and module names match exactly when a shootable weapon uses Ultimate Inventory System ammo; and
- the Save System Manager has **Inventory System Manager Item Saver**, with no standard **Inventory Saver** on the bridged character.
## Verify in Play Mode
1. Start with one Iron Sword in **Default**. Confirm that the Ultimate Inventory System Bag shows it and no sword is active on the character.
2. Invoke **Character Equip Unequip**. Confirm that the Item moves into the intended bridge collection, the correct Character Item appears in its Ultimate Character Controller slot, and the expected Item Set becomes active.
3. Use the sword through normal character input. Confirm that Ultimate Character Controller owns the Use ability and animation while the Ultimate Inventory System Item remains available to UI and bindings.
4. Unequip the sword. Confirm that it returns to **Default** and the Character Item and active Item Set change as intended.
5. Put the weapon in a bridge collection without activating its set. Confirm that the UI reports soft equipped and that it cannot be used as the active Item.
6. For a shootable weapon, fire and reload. Confirm that reserve Ultimate Inventory System ammo decreases and `AmmoData` keeps the loaded count after unequipping and re-equipping the weapon.
7. Pick up and drop one equippable Item. Confirm that the world object, Ultimate Inventory System quantity, bridge collection, Character Item, and Item Set each change once.
8. Equip Ultimate Inventory System-only armor. Confirm that Equipper creates the visual without activating an Ultimate Character Controller weapon Item Set.
9. Open the inventory menu. Confirm that gameplay input stops, UI input and the close action remain available, and the cursor follows the menu state.
10. Save with an Item equipped and a partially loaded clip, change the Inventory, then load. Confirm that collection contents, mutable Item data, and active Item Set return together.
11. Repeat equip, UI, pickup, and save checks for every local player. Each player's input, Inventory Identifier, UI owner, and Inventory must remain separate.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| The integration is missing or reports unresolved types | Bridge version, installed product versions, and duplicate old integration files | Install the product versions required by the downloaded bridge, remove the old copy, then reimport after both products compile. For the inspected `3.0.5` bridge, the minimums are Ultimate Character Controller `3.0.10` and Ultimate Inventory System `1.2.16`. |
| **Setup Character** is disabled | The assigned object may not be a scene object with **Ultimate Character Locomotion** | Build or update the Ultimate Character Controller character, place it in the scene, and assign its root. |
| Character Setup warns that **Ammo** or **Equippable** cannot be found | The selected database lacks the expected categories or the scene uses another database | Duplicate `EmptyCharacterInventoryDatabase`, assign that database to both managers, or add the exact categories before converting. |
| Character Setup stops while configuring input | The packaged setup path may not resolve the character's current Opsive input implementation | Do not add a second input backend merely to hide the error. Keep the existing player input, verify which conversion components were added, assign it to **Item User > Inventory Input**, and use a bridge update or project fix for the setup path. |
| An Item exists in Ultimate Inventory System but no Character Item appears | Category inheritance, `Prefabs` spelling and type, assigned prefab, and bridge Attribute name | Inherit from **Single Item** for `GameObject` or **Multi Item** for `GameObject[]`, assign the prefab, and keep the bridge name synchronized. |
| The Character Item appears but never becomes active | Bridge collection, Character Item slot, Item Set group category, and rule | Put the Item in a listed bridge collection and make the rule, category, and slot agree. |
| The UI changes equipment but the character does not | The UI may use ordinary **Move To Collection** instead of the integration action | Use **Character Equip Unequip** for Ultimate Character Controller weapons and confirm the target collection is listed under **Bridge Item Collection Names**. |
| A holstered Item is treated as unequipped or active at the wrong time | Collection membership and the **Not Move Equip** choice may not match the intended soft-equip flow | Keep the Item in a bridge collection for soft equipment and change only its active Item Set when appropriate. |
| The wrong hand or weapon combination activates | Character Item slot and Item Set Rule slots or exceptions | Correct the prefab slot and use a category, definition, or slot-collection rule that permits only the intended combination. |
| Ammo never decreases or reload finds no reserve | Ammo Item Definition, source collection names, and **Inventory Item Ammo** configuration | Put the correct ammo Item in a searched collection and match the definition or `AmmoData` Attribute. |
| A weapon loses its loaded rounds when switched or loaded | Missing mutable `AmmoData`, missing **Inventory Ammo Data Clip**, or wrong Attribute name | Add the Item-level Attribute and clip module, use the same name, and save mutable Items with **Inventory System Manager Item Saver**. |
| Dropping logs that the pickup prefab is missing or has no Inventory | **Inventory Item Pickup Prefab**, Character Item **Drop Prefab**, and required pickup components | Assign a generated integration pickup or another prefab containing Ultimate Inventory System Inventory and **Inventory Item Pickup**. |
| Armor enters the weapon bridge or activates an Item Set | Armor category or UI action may use the Ultimate Character Controller bridge workflow | Remove the **Equippable** inheritance, use a separate Ultimate Inventory System Item Slot Collection and Equipper, and use **Move To Collection**. |
| Item Actions or menu shortcuts do not respond | **Item User > Inventory Input**, active input backend, panel owner, and gameplay-input state | Assign the correct local `IPlayerInput`, remove competing input owners, and restore gameplay input when the menu closes. |
| Loading duplicates Items or restores the wrong active set | Standard **Inventory Saver**, missing manager Item saver, changed collection order, or non-unique identifier | Keep only **Inventory Bridge Saver** on the character, add **Inventory System Manager Item Saver**, preserve order, and use a unique ID. |
## Related pages
- [Ultimate Inventory System-side character-controller workflow](https://opsive.com/support/documentation/ultimate-inventory-system/integrations/opsive-character-controllers/)
- [Ultimate Character Controller Item Creation](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-creation/)
- [Ultimate Character Controller Character Items](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/)
- [Ultimate Character Controller Item Set Rules](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-set-rules/)
- [Ultimate Inventory System Item Categories](https://opsive.com/support/documentation/ultimate-inventory-system/editor-window/item-category/)
- [Ultimate Inventory System Item Definitions](https://opsive.com/support/documentation/ultimate-inventory-system/editor-window/item-definition/)
- [Ultimate Inventory System Item Collections](https://opsive.com/support/documentation/ultimate-inventory-system/inventory/item-collections/)
- [Ultimate Inventory System Item Actions](https://opsive.com/support/documentation/ultimate-inventory-system/item-actions/)
- [Ultimate Inventory System Item Pickups](https://opsive.com/support/documentation/ultimate-inventory-system/item-objects/item-pickups/)
- [Ultimate Inventory System Equipper](https://opsive.com/support/documentation/ultimate-inventory-system/item-objects/equipping-items/)
- [Ultimate Inventory System Input](https://opsive.com/support/documentation/ultimate-inventory-system/input/)
- [Ultimate Inventory System Save System](https://opsive.com/support/documentation/ultimate-inventory-system/save-system/)
- [Ultimate Character Controller State System](https://opsive.com/support/documentation/ultimate-character-controller/state-system/)
- [Ultimate Character Controller Integrations](https://opsive.com/support/documentation/ultimate-character-controller/integrations/)
## Developer reference
The current runtime types use different `Item` and `Inventory` names across the two products. Alias them explicitly in integration code:
```csharp
using InventoryItem = Opsive.UltimateInventorySystem.Core.Item;
using Inventory = Opsive.UltimateInventorySystem.Core.InventoryCollections.Inventory;
using ItemCollection = Opsive.UltimateInventorySystem.Core.InventoryCollections.ItemCollection;
using CharacterItem = Opsive.UltimateCharacterController.Items.CharacterItem;
```
`CharacterInventoryBridge` exposes the main project extension points: `MoveItemToEquippable`, `MoveItemToDefault`, `MoveEquip`, `Equip`, `IsItemActive`, `GetActiveInventoryItem`, `GetInventoryItem`, and `DropItem`. Use `MoveEquip` when code owns both the collection move and active equip request. Use `Equip` only when the Item is already in a bridge collection.
The bridge source is under `Assets/Opsive/UltimateCharacterController/Integrations/UltimateInventorySystem/Scripts`. Important extension types include:
- `CharacterInventoryBridge` and `InventoryItemSetManager`
- `ItemCategoryItemSetRule`, `ItemDefinitionItemSetRule`, and `ItemSlotCollectionItemSetRule`
- `CharacterEquipUnequipItemAction`, `CharacterUseItemAction`, `CharacterDropItemAction`, and `CharacterQuantityDropItemAction`
- `ItemObjectBinding` and `ItemToCharacterStateBinding`
- `InventoryItemAmmo` and `InventoryAmmoDataClip`
- `InventoryItemPickup`
- `CharacterEquippedSelectItemViewModule` and `WeaponAmmoItemViewModule`
- `InventoryBridgeSaver`
The integration-specific save lifecycle events are `OnInventoryBridgeSaverWillLoad` and `OnInventoryBridgeSaverLoaded`, declared in `IntegrationEventNames`. The bridge does not add network replication or authority. In a multiplayer project, make the Ultimate Inventory System inventory transaction authoritative, replicate Item and collection state through the networking layer, and let each owning client rebuild the local Ultimate Character Controller Character Item and Item Set representation.
---
# UMA
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/integrations/uma/)
Use the [UMA](https://assetstore.unity.com/packages/tools/uma-2-unity-multipurpose-avatar-35611?aid=1100lGdc) 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](https://github.com/umasteeringgroup/UMA/releases). 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](https://opsive.com/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](https://opsive.com/support/documentation/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
1. Download the UMA integration from [Opsive Downloads](https://opsive.com/downloads/).
2. Import the downloaded package after both UMA and Ultimate Character Controller compile. Importing it creates `Assets/Opsive/UltimateCharacterController/Integrations/UMA` in the project.
3. Remove an older copy of `Assets/Opsive/UltimateCharacterController/Integrations/UMA` before importing a replacement package.
4. In **Add Component**, confirm that **UMA Character Builder**, **UMA Ability Builder**, **UMA Item Pickup**, and **UMA First Person Base Object** are available.
5. 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.
1. Place the UMA **Dynamic Character Avatar** prefab in the scene.
2. Open UMA's **Bone Builder** from the UMA toolbar.
3. Assign the scene avatar to **UMA GameObject** and select **Generate Bones**.
4. Open **Tools > Opsive > Ultimate Character Controller > Character Manager** and build the character with the generated UMA model.
5. Select the child that contains **Dynamic Character Avatar**.
6. In **Dynamic Character Avatar**, set **Additional Utility Recipes** to an empty list.
7. Under **Race Animation Controllers**, assign the Ultimate Character Controller controller to **Default Animator Controller**.
8. Under **Advanced Options**, enable **Keep Avatar** and **Keep Animator Controller**, then assign the same controller to **Animation Controller**.
9. On the child's **Animator**, assign the same asset to **Controller**.
10. Finish the character through the Ultimate Character Controller Character and Item Managers, then save the configured prefab or scene object.
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.
1. Place the UMA **Dynamic Character Avatar** prefab in the scene.
2. 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.
3. Add **UMA Character Builder** to the same GameObject as **Dynamic Character Avatar**.
4. 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.
5. Assign the Ultimate Character Controller **Animator Controller**.
6. Enable **Add Items** only when **Item Collection** and **Item Set Rule** reference project assets intended for this character.
7. Choose whether the builder should add **Health**, **Unity IK**, **Foot Effects**, and **Standard Abilities**.
8. For an AI character, enable **AI Agent** and optionally **Add Nav Mesh Agent**. For a player, leave **AI Agent** disabled.
9. If both perspectives are enabled, choose **Start First Person Perspective**.
10. Enable **Assign Camera** only for a player that should take ownership of the existing Ultimate Character Controller Camera Controller.
11. Add a listener to **Character Created** for setup that must use the newly created Ultimate Character Controller root.
When UMA raises `DynamicCharacterAvatar.CharacterCreated`, the bridge:
1. removes a Capsule Collider directly on the generated avatar because Ultimate Character Controller creates its own collider structure;
2. creates a new GameObject at the avatar's position and rotation;
3. reparents the UMA-generated avatar beneath that new object;
4. uses Ultimate Character Controller's runtime Character Builder to add locomotion, movement types, the Animator Monitor, colliders, optional systems, and input or AI support;
5. assigns an existing Camera Controller when requested; and
6. 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](https://opsive.com/support/documentation/ultimate-character-controller/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:
1. Place a second **Dynamic Character Avatar** in the scene for the arms or first-person body.
2. Add **UMA First Person Base Object** to it.
3. Set **Local Position**, **Local Rotation**, and its **Animator Controller**.
4. Add child paths to **Item Slot Locations** for each hand or other Item attachment point.
5. 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](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/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
1. 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.
2. Confirm that the Ultimate Character Controller root has one intended Rigidbody and collider hierarchy. The model should not retain a competing root Capsule Collider.
3. 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.
4. Confirm that the camera follows the new root for a player and remains unassigned for an AI agent.
5. If Items are enabled, equip and use one Character Item. Confirm that hand slots, Item Sets, Item abilities, and Animator parameters update.
6. If both perspectives are enabled, switch perspectives. Confirm that the hidden model paths, shadow material, first-person base object, and Item Slots behave correctly.
7. Damage and respawn a character when **Add Health** is enabled. Test ragdoll only after a separate ragdoll setup has been added.
8. Change the UMA wardrobe and then perform any supported avatar rebuild. Confirm that the Animator, IK, feet, collider, and Items still reference valid objects.
9. 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. |
## Related pages
- [Character Creation](https://opsive.com/support/documentation/ultimate-character-controller/character/character-creation/)
- [Item Creation](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-creation/)
- [Animator Controller](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/animator-controller/)
- [First Person Arms](https://opsive.com/support/documentation/ultimate-character-controller/animation/animator/first-person-arms/)
- [Input](https://opsive.com/support/documentation/ultimate-character-controller/input/)
- [Camera](https://opsive.com/support/documentation/ultimate-character-controller/camera/)
- [Artificial Intelligence](https://opsive.com/support/documentation/ultimate-character-controller/artificial-intelligence/)
- [Inverse Kinematics](https://opsive.com/support/documentation/ultimate-character-controller/inverse-kinematics/)
- [Ragdoll](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/included-abilities/ragdoll/)
- [Layer Manager](https://opsive.com/support/documentation/ultimate-character-controller/layer-manager/)
- [Ultimate Character Controller Integrations](https://opsive.com/support/documentation/ultimate-character-controller/integrations/)
## 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`. 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.
---
# Universal Render Pipeline
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/integrations/universal-render-pipeline/)
Use the Universal Render Pipeline support package when the Ultimate Character Controller project runs URP and first-person objects, materials, camera stacking, post processing, decals, or shaders must use the URP path.
## Import URP support
1. Install the intended Unity Universal Render Pipeline package and assign the URP Render Pipeline Asset in Project Settings.
2. Let Unity finish converting the project and confirm an ordinary scene renders correctly.
3. Open **Tools > Opsive > Ultimate Character Controller > Setup Manager** and select **Project**.
4. Under **Render Pipeline**, choose **URP** and select **Import**. The manager enables the Ultimate Character Controller URP scripting symbol for the active build target and imports the matching support package.
5. Resolve material or shader errors before configuring the character camera.
## Configure first-person rendering
1. Select the first-person View Type and set **Overlay Render Type** to **Render Pipeline**.
2. Configure the main/overlay camera relationship required by the installed Ultimate Character Controller and URP versions.
3. Put first-person objects on the intended layer and confirm the camera renderer/layer masks include that layer only where expected.
4. Configure post processing on the correct camera or volume route; do not duplicate it across cameras without testing the combined result.
5. Verify Object Fader, decals, particles, transparent materials, shadows, and the invisible shadow-caster material used by the character setup.
## Verify in Play Mode
1. Switch between first and third person and confirm cameras render the intended layers.
2. Aim an item close to a wall and check clipping, transparency, shadows, and post processing.
3. Spawn a decal, particle, projectile, and explosion and confirm each uses a URP-compatible material.
4. Change quality level and target platform, then repeat in a Development Build.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| Materials are pink. | Check the active URP Asset and whether Ultimate Character Controller URP support was imported after URP. | Activate URP first, then import the matching support package and convert project materials deliberately. |
| First-person objects are missing or render twice. | Check Overlay Render Type, camera stack, renderer, and layer masks. | Use one intended URP overlay route and remove the duplicate camera/layer ownership. |
| Post processing differs by perspective. | Check which camera and volume layer owns the effect. | Configure the effect on the camera path active for both perspectives or explicitly mirror the intended settings. |
| The integration works in Editor but not after a build-target switch. | Check the Ultimate Character Controller URP scripting symbol for the current target. | Reopen Setup Manager after switching targets and reimport/refresh the pipeline support when required. |
## Related pages
- [Quick Setup](https://opsive.com/support/documentation/ultimate-character-controller/getting-started/quick-setup/)
- [Camera](https://opsive.com/support/documentation/ultimate-character-controller/camera/)
- [Post Processing](https://opsive.com/support/documentation/ultimate-character-controller/camera/post-processing/)
- [High Definition Render Pipeline](https://opsive.com/support/documentation/ultimate-character-controller/integrations/high-definition-render-pipeline/)
---
# Videos
[View this page online](https://opsive.com/support/documentation/ultimate-character-controller/videos/)
Use the video library to watch complete Ultimate Character Controller workflows, then use the written documentation beside each topic for the exact fields, menu paths, prerequisites, and supported behavior in the current Version 3 package.
## Start here
For a new project, follow this compact route:
1. Read [Importing](https://opsive.com/support/documentation/ultimate-character-controller/getting-started/importing/) before adding UCC to an existing project.
2. Complete [Quick Setup](https://opsive.com/support/documentation/ultimate-character-controller/getting-started/quick-setup/) once without customization.
3. Open the [Ultimate Character Controller video library](https://opsive.com/videos/?pid=25992) and choose the video that matches the task, keeping the related written page open as the current reference.
The external library is maintained separately from these docs, so individual titles, destinations, and recording versions can change. The written UCC documentation is the source of truth for current labels and Version 3 behavior.
## Find a route by task
### Project and scene setup
The video library currently includes **Project & Scene Setup**. Use it for the overall sequence, then confirm the current steps in:
- [Importing](https://opsive.com/support/documentation/ultimate-character-controller/getting-started/importing/) for package and project prerequisites.
- [Quick Setup](https://opsive.com/support/documentation/ultimate-character-controller/getting-started/quick-setup/) for managers, camera, and a playable character.
- [Demo Scene](https://opsive.com/support/documentation/ultimate-character-controller/getting-started/demo-scene/) for learning from the supplied example.
- [Input](https://opsive.com/support/documentation/ultimate-character-controller/input/) when the video and the project's input backend differ.
### Character and camera
The library currently groups **First Person Character Creation**, **Third Person Character Creation**, and **Character Templates** around character setup. Pair them with:
- [Character Creation](https://opsive.com/support/documentation/ultimate-character-controller/character/character-creation/) for the current manager workflow.
- [Character Common Setups](https://opsive.com/support/documentation/ultimate-character-controller/character/character-creation/common-setups/) for common body and perspective choices.
- [Camera](https://opsive.com/support/documentation/ultimate-character-controller/camera/) and [View Types](https://opsive.com/support/documentation/ultimate-character-controller/camera/view-types/) for camera ownership, perspective, and framing.
- [Movement Types](https://opsive.com/support/documentation/ultimate-character-controller/character/movement-types/) for how player input becomes character movement.
Choose the character perspective first, then configure its camera View Type and Movement Type. A creation video may demonstrate all three, but they remain separate runtime choices.
### Abilities and items
The current external index includes item-type and first-/third-person item creation, assault-rifle, sword, basic and advanced grenade, and item-set-rule videos. Use these written routes for their current configuration:
- [Abilities](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/) and [Creating a New Ability](https://opsive.com/support/documentation/ultimate-character-controller/character/abilities/new-ability/) for character behavior.
- [Item Creation](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-creation/) for the shared creation workflow.
- [Item Creation Common Setups](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-creation/common-setups/) for perspective and item-shape decisions.
- [Item Set Rules](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/item-set-rules/) for what can be equipped together.
- [Item Actions](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/) for the modular runtime action model.
- [Shootable](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/shootable/), [Melee](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/melee/), and [Throwable](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/character-item/item-actions/usable/throwable/) for the current action-specific fields.
Treat a weapon video as an end-to-end example, not as a substitute for the current action-module reference. Stop at each major checkpoint and verify the item in both the intended perspective and Play Mode before adding optional effects.
### Systems and integrations
The video index currently includes a two-part Ultimate Inventory System integration walkthrough. For that integration and other project systems, start with:
- [Integrations](https://opsive.com/support/documentation/ultimate-character-controller/integrations/) for the current integration catalog and prerequisites.
- [Ultimate Inventory System Integration](https://opsive.com/support/documentation/ultimate-character-controller/integrations/ultimate-inventory-system/) for the UCC-to-UIS connection.
- [Surface System](https://opsive.com/support/documentation/ultimate-character-controller/surface-system/) for material-specific footsteps and impacts.
- [State System](https://opsive.com/support/documentation/ultimate-character-controller/state-system/) for conditional property changes.
- [Animation](https://opsive.com/support/documentation/ultimate-character-controller/animation/) for Animator and animation-event requirements.
- [Input](https://opsive.com/support/documentation/ultimate-character-controller/input/) for input backend and control setup.
Integration recordings are especially sensitive to package-version and third-party UI changes. Follow the current integration page for supported versions and import steps before reproducing a video's Inspector settings.
## Troubleshooting
| Symptom | Check | Fix |
| --- | --- | --- |
| A menu item from the video is missing | The recording targets an earlier UCC release or a different installed controller package | Open the matching written page and use its current manager or asset-creation path. |
| A component or field has a different name | The recording predates the Version 3 modular workflow | Configure the current component or action module; do not add a legacy duplicate. |
| The scene does not match the recording | The render pipeline, input backend, sample version, or perspective differs | Return to Importing and Quick Setup, align those prerequisites, and repeat only the relevant section. |
| A character moves but the camera does not follow correctly | Character perspective, Camera View Type, and Movement Type do not form the intended combination | Review Character Creation, View Types, and Movement Types together, then retest in a clean Play Mode session. |
| An item works in only one perspective | The first- or third-person visible object and perspective properties are incomplete | Use Item Creation Common Setups and the relevant usable-action page to finish the intended perspective. |
| An integration option or installer is absent | The installed integration or third-party version differs from the recording | Use the current Integrations page and that integration's written prerequisites; do not reuse an archived package. |
| The basic result works but effects or animations do not | The video moved past a missing Animator, event, State, Surface, audio, or prefab reference | Verify the base action first, then add one optional system at a time from its written page. |
## Related documentation
- [Getting Started](https://opsive.com/support/documentation/ultimate-character-controller/getting-started/)
- [Component Overview](https://opsive.com/support/documentation/ultimate-character-controller/component-overview/)
- [Character](https://opsive.com/support/documentation/ultimate-character-controller/character/)
- [Camera](https://opsive.com/support/documentation/ultimate-character-controller/camera/)
- [Items and Inventory](https://opsive.com/support/documentation/ultimate-character-controller/items-inventory/)
- [Integrations](https://opsive.com/support/documentation/ultimate-character-controller/integrations/)