Pickup

Export

Pickup lets the character play a deliberate reach or collect animation before adding a detected pickup to its inventory. Use it when pressing an input should collect an item from the ground or a surface instead of collecting it immediately on contact.

Before you begin

The character needs Ultimate Character Locomotion and an enabled Inventory. An animated equippable-item workflow also needs an Item Set Manager and the appropriate Equip Unequip item abilities.
The pickup needs an Item Pickup component and a trigger collider on a layer included by the character’s Detect Layers.
The character Animator needs the Pickup state for Ability Index 11, or a project-specific replacement, when an animation should play.
Decide whether the action is timed by animation events or fixed durations. Custom clips need OnAnimatorPickup and OnAnimatorPickupComplete when their corresponding event modes are enabled.

Add Pickup to the character

Select the character GameObject.
In Ultimate Character Locomotion, expand Abilities and use the plus button to add Pickup.
Keep the default Start Type set to Button Down, Input Names set to Action, and Ability Index set to 11 when using the included pickup animation.
Keep Object Detection set to Trigger for a proximity pickup and set Detect Layers to include the pickup’s trigger layer.
Set Allowed Pickups to Item for the standard inventory-item workflow.
Leave Slot ID at -1 when the inventory may choose the slot. Enter a specific slot ID only when every item handled by this ability belongs in that slot.
Leave Pickup Item Definitions empty when every detected Item Definition should use the animation. Add definitions when only selected items should animate; other detected items are collected immediately rather than rejected.
Set Max Trigger Object Count high enough for the greatest number of Item Pickup triggers that can overlap the character at once.
Configure Pickup Event and Pickup Complete Event as described below.
Place Pickup high enough in the ability list to start over lower-priority actions, while keeping critical interrupts such as death or ragdoll above it.

Create an animated item pickup

Open Tools > Opsive > Ultimate Character Controller > Object Manager.
In Object Builder, enter a Name, set Object Type to Item Pickup, and assign the item’s visible model to GameObject. Use the model rather than an already created Character Item.
Select Build Object and save the prefab.
On the created Item Pickup component, disable Pickup On Trigger Enter. Leaving it enabled collects the item on contact and bypasses the Pickup ability.
In the Item Definition and Amount list, add each Item Definition the object supplies and enter its quantity.
Enable Equip when the picked-up item should become active. Set Item Set Group and, when needed, Item Set Name to select the intended item set.
Confirm the pickup has a trigger Collider on a layer included by the character’s Detect Layers. Size it to the area in which the prompt and input should be available.
Optionally set Pickup Message Text, Pickup Message Icon, Pickup Audio Clip Set, rotation, destruction delay, and Respawner behavior on the pickup prefab.
Place the prefab in the scene and position its model for the character’s pickup animation.

See Item Pickup for the world-object fields and inventory-item setup.

Choose the pickup behavior

Animated input or immediate contact

Disable Pickup On Trigger Enter and use Pickup’s Action input for a deliberate animated collection.
Enable Pickup On Trigger Enter when walking through the trigger should collect the item immediately. This path does not start the character’s Pickup ability.
Set Ability Index to -1 when the ability should perform its pickup immediately without entering an Animator state.
Always Pickup controls whether a direct Item Pickup is consumed when the inventory cannot accept its contents. The animated path reserves the world pickup before its delayed inventory event, so test limited-capacity inventories explicitly.

Which objects may start the ability

Allowed Pickups contains three flags:

Item accepts a non-depleted Item Pickup whose Pickup On Trigger Enter option is disabled.
Health accepts a Health Pickup.
Other accepts a component that implements IObjectPickup; it does not make an arbitrary GameObject collectible.

Use a separate Pickup ability entry for each type when the objects need different detection, inputs, animations, or timing. In the current Version 3 runtime, the Item path takes precedence whenever that flag is included, so combining Item with Health or Other does not create a general-purpose mixed pickup action.

A standard Health Pickup performs its own pickup when the character enters its trigger. Use cast detection or a custom IObjectPickup when a health or other pickup must wait for the character animation instead of responding on contact.

Item filtering and overlapping pickups

An empty Pickup Item Definitions list gives every eligible item the animated path. A nonempty list is an animation filter: a pickup containing a listed definition may use the animation, while an unlisted pickup falls back to immediate inventory collection.

To include the selected object’s text in the prompt, put {0} in Pickup’s inherited Ability Message Text. The first tracked Item Pickup’s Pickup Message Text replaces that placeholder and can also be shown by the Message Monitor after collection.

When several Item Pickup triggers overlap, Pickup processes the first available entry in its tracked queue rather than choosing the nearest model. Keep interaction volumes distinct when the player needs predictable selection.

The animated item path is designed around items that an Equip Unequip ability can equip. A pickup that adds only a consumable definition may be added immediately without playing the reach animation. Test equippable items and consumable-only pickups as separate cases.

Animation timing

Pickup Event controls when the item definitions are added:

Enable Wait For Animation Event and send OnAnimatorPickup at the hand-contact frame.
Disable it and set Duration for fixed timing. A newly added ability defaults to event mode.

Pickup Complete Event controls when the ability stops after collection:

Enable Wait For Animation Event and send OnAnimatorPickupComplete near the end of the clip.
Disable it and set Duration for a timed finish. Its default is duration mode at 0.4 seconds.

These are independent triggers. The first changes the inventory; the second releases the ability. See Animation Event Trigger for the exact Unity event setup.

How it runs

When the character enters a valid Item Pickup trigger, Pickup records that object and exposes it through the inherited detection workflow. Pressing Action starts the ability, takes the first tracked available pickup, prepares the character’s Equip Unequip abilities, and reserves that world pickup for the sequence.

At Pickup Event, the Item Pickup adds its configured Item Definitions and amounts to the Inventory, using Slot ID when one was specified. The item may then be equipped according to the Item Pickup and item-set configuration. At Pickup Complete Event, Pickup stops and ordinary ability control resumes.

The world pickup is marked as picked up when the animated sequence is prepared, before the delayed inventory event. Its destruction delay or Respawner then controls its visible lifecycle. Verify inventory-capacity rules before using this flow for a limited inventory so a reserved pickup cannot disappear before the inventory accepts its contents.

Pickup can receive another start while already active, allowing queued overlapping item pickups to be processed, but separate trigger volumes produce a clearer player choice.

Verify in Play Mode

Enter the Item Pickup trigger. In the Pickup Inspector, confirm Detected Object shows the pickup and the expected ability message appears.
Press Action and confirm (Active) appears beside Pickup and the Animator receives AbilityIndex 11.
Before OnAnimatorPickup or the configured Pickup Event duration, confirm the item amount has not yet been added.
At the pickup event, confirm the Inventory amount increases by the Item Pickup’s configured amount and the intended item equips when Equip and its item-set settings allow it.
At OnAnimatorPickupComplete or the configured Pickup Complete Event duration, confirm Pickup stops and normal control resumes.
Test an unlisted Item Definition when Pickup Item Definitions is populated. Confirm it is collected immediately without the animation.
Test two nearby triggers separately, then overlap them deliberately and confirm the first tracked pickup is selected.
If a Respawner is configured, wait for its interval and confirm the pickup returns with its trigger active again.

Troubleshoot Pickup

Symptom	Check	Fix
The item disappears as soon as the character touches it.	Pickup On Trigger Enter is enabled on the Item Pickup.	Disable it when collection should wait for the Pickup ability and input.
Detected Object remains empty.	Check Object Detection, Detect Layers, the trigger Collider, Allowed Pickups, inherited Object ID, and whether the Item Pickup is already depleted.	Use Trigger detection, include the trigger layer, correct the optional ID, and reinitialize or respawn the pickup.
The prompt appears but `Action` does not start Pickup.	Check Input Names, ability priority, the Inventory and Item Set Manager, Equip Unequip abilities, and whether another nonconcurrent ability has higher priority.	Restore the required character components, correct input, or move Pickup above the actions it should interrupt.
One item is collected without its animation.	Its definition may not be in Pickup Item Definitions, it may not be equippable through an Equip Unequip ability, or Ability Index may be `-1`.	Add the definition to the animation filter, complete its item-set setup, and use the intended Animator index.
Pickup starts but the inventory never changes.	Pickup Event may be waiting for a missing `OnAnimatorPickup` event.	Add the exact event to every active pickup clip or disable event mode and set a duration.
The inventory changes but Pickup never stops.	Pickup Complete Event may be waiting for a missing `OnAnimatorPickupComplete` event.	Add the exact completion event or use duration mode.
The item is added but does not equip.	Check Equip, Item Set Group, Item Set Name, the character’s item sets, and whether Use or Reload is active.	Correct the item-set selection and retry when the conflicting item ability is inactive.
The wrong pickup is selected in an overlap.	Pickup uses its first tracked available item, not distance from the character.	Separate or resize the trigger volumes so only one candidate is available at a time.
The Console warns that the maximum trigger-object count is too small.	More Item Pickups overlap than Max Trigger Object Count can track.	Increase the count or reduce overlapping pickup volumes.
A Health Pickup is collected before the Pickup animation.	The built-in Health Pickup responds directly to trigger entry.	Use an appropriate cast or a custom externally controlled `IObjectPickup` for animation-gated health collection.

Item Pickup configures the world object, Item Definitions, quantities, equipping, and pickup presentation.
Inventory explains the character-side storage and loadout.
Detect Object Ability Base explains inherited trigger, layer, Object ID, message, and diagnostic fields.
Equip Unequip controls which item set becomes active during the animated item path.
Item Equip Verifier coordinates equipped items when another character ability starts.
Animation Event Trigger explains event-versus-duration timing.
Animator Parameters explains AbilityIndex and the character Animator values.
Health Pickup covers the built-in health object used by the Health option.

Developer reference

Pickup derives from DetectObjectAbilityBase. It exposes AllowedPickup, SlotID, PickupItemDefinitions, PickupEvent, and PickupCompleteEvent. It returns true from CanReceiveMultipleStarts and ImmediateStartItemVerifier.

The ability registers OnAnimatorPickup to perform the inventory or IObjectPickup action and OnAnimatorPickupComplete to stop. For item pickups it maintains a queue sized from Max Trigger Object Count, coordinates each Equip Unequip ability through the item-pickup lifecycle events, and calls ItemPickupBase.DoItemIdentifierPickup at the pickup event.

For a non-item path, the detected GameObject must provide IObjectPickup and its DoPickup(GameObject target) implementation owns the result. A custom Object Pickup should also define how trigger entry differs from an externally requested pickup; the base Pickup On Trigger Enter value is not enforced centrally for every derived implementation.