Item Pickup

Export

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. 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

Open Tools > Opsive > Ultimate Character Controller > Object Manager.
In Object Builder, enter a Name.
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.
Assign the visible model to GameObject.
Select Build Object, choose a path under the project’s Assets folder, and open the generated prefab.
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.
Size the trigger around the collection area. Keep it on the same GameObject as Item Pickup.
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

Add the Iron Sword Item Definition with an amount of 1.
Leave Equip enabled when the sword should become active after collection.
Leave Item Set Group at -1 to search all groups, or enter the group that owns the sword.
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.

Add the Pickup ability to the character.
Keep Allowed Pickups set to Item, and include the pickup layer in Detect Layers.
Leave Pickup Item Definitions empty to animate every Item Definition, or add the definition that should use this animation.
Configure Pickup Event to use OnAnimatorPickup, or use its duration mode when the animation has no matching event.
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

Build the prefab with Object Type set to Dropped Item.
Assign it to the Character Item’s Drop Prefab field.
Add and configure the Drop ability.

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

Item Pickup ignores colliders that do not resolve to an enabled Inventory on the character’s main layer.
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.
Inventory limits the accepted amount according to the Item Type and raises its pickup events for amounts that were added.
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.
A successful result marks the object depleted and sends OnObjectPickedUp on the collecting character.
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

Keep the character’s Inventory and the pickup’s Item Pickup component visible.
Enter an automatic Iron Sword pickup. Confirm the amount increases once, the object depletes, and Equip selects the intended Item Set when enabled.
Test a firearm-and-ammunition pickup. Confirm both amounts change and the ammunition entry does not create an unwanted held object.
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.
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.
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.
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.

Object Pickup explains the shared trigger, feedback, depletion, pooling, and lifetime behavior.
Complete Item Pickup workflow covers the Inventory and Character Item side in more depth.
Inventory configures capacities and runtime item ownership.
Item Creation creates the Item Definition and Character Item used by an equippable pickup.
Character Item configures the held object and its Drop Prefab.
Item Set Rules determine which collected items form valid loadouts.
Pickup ability configures detection, input, filters, and animation timing.
Drop removes an item and initializes its dropped prefab.
Trajectory Object controls dropped-object motion.
Respawner controls when a scene pickup returns.
Object Manager 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 for registration and cleanup patterns.