Shield

Export

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 use third person unless the network character is a spectator; spectators follow the selected perspective.

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:

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. A positive Durability Attribute satisfies the durability test, but the built-in Melee recoil path can still miss a child Shield Collider because it checks the resolved damage-target GameObject. Use a custom recoil test based on the actual Impact Collider and the intended durability rule; see Melee.
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<Collider>() 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 non-spectators, while spectators follow the selected perspective, 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.

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