Health Pickup

Export

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

Open Tools > Opsive > Ultimate Character Controller > Object Manager.
In Object Builder, enter a Name.
Set Object Type to Health Pickup.
Assign the visible health-pack model to GameObject.
Select Build Object, save the prefab under the project’s Assets folder, and open the generated prefab.
On the root Sphere Collider, enable Is Trigger. Released Version 3 adds the Collider but does not enable this option for Health Pickup.
Size the trigger around the intended collection area and confirm it remains on the same GameObject as Health Pickup.
Configure Health Amount, Always Pickup, feedback, and lifetime.
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

On enable, Object Pickup clears its depleted state and prepares the trigger. First activation is immediate; reuse honors Trigger Enable Delay.
When a Collider enters, Health Pickup searches that object and its parents for IDamageTarget.
It rejects a missing or dead target.
It calls Heal(Health Amount) on a living target.
If Heal returns true, or Always Pickup is enabled, the object marks itself depleted and sends OnObjectPickedUp on the target owner’s GameObject.
The pickup optionally plays audio and supplies its message text/icon to Message Monitor.
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

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.
Reduce both Health and Shield. Confirm Health fills first and only the remainder restores Shield.
Start with both attributes full and Always Pickup disabled. Confirm the pickup remains available.
Repeat at full values with Always Pickup enabled. Confirm the living target consumes the pickup even though no value changes.
Test a dead target. Confirm it does not consume the pickup in either Always Pickup mode.
Confirm OnHealthHeal reports the amount actually restored and OnObjectPickedUp runs only after the object is consumed.
Verify audio and Message Monitor feedback, then wait for Respawner and confirm the trigger can collect again.
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.

Object Pickup explains shared trigger, feedback, pooling, and lifetime behavior.
Health configures Health, Shield, healing order, events, death, and respawn behavior.
Attributes configures starting values, limits, and regeneration.
Respawner controls when and where a scene pickup returns.
Pickup ability explains detection, input, and the custom IObjectPickup route.
Item Pickup covers inventory collection instead of healing.
Object Manager creates the starting prefab.
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.