Block

Export

The Block item ability plays a block or parry reaction when an equipped Shield Item Action is struck. The Shield Action and its collider decide whether damage is absorbed; Block supplies the reaction’s item Animator values and ends it at the configured completion point.

Before you begin

The defending Character Item needs a Shield Item Action and a correctly sized Shield Collider on each visible first-person or third-person object that should receive hits. Its Animator also needs states for the Block Item State Index and Parry Item State Index values used by the character.

Creating or updating an item with a Shield action through Tools > Opsive > Ultimate Character Controller > Item Manager performs most of this setup. The builder adds a Shield Action, an Attribute Manager with a Durability Attribute, and perspective-specific Shield Collider components. When the item is built directly on a character, it also adds a Block item ability if the character does not already have one. Resize each generated collider to cover the intended defensive surface.

Configure the shield and Block

  1. Open the Item Manager, create or select the Character Item, and add Shield to its Actions list. Select Build Item for a new item or Update Item for an existing one.
  2. Select each visible shield object. Confirm its Shield Collider references the Character Item’s Shield Action, and keep Disable On Unequip enabled unless the holstered object should continue receiving hits.
  3. On the Shield Action, decide whether protection Require Aim. This is disabled by default.
  4. Set Absorption Factor. The default of 1 absorbs all eligible damage; 0 passes all damage through to the character, and values between them split the damage.
  5. Configure Impact Animator Audio State Set with the impact substate and any audio or State that should accompany the reaction.
  6. Keep Apply Impact enabled when the shield should start Block and play its impact state or audio. Damage absorption still works when this option is disabled, but no Block reaction is requested.
  7. Configure Impact Complete Event. Its default uses a 0.2 second duration. Use a duration or the shared OnAnimatorItemImpactComplete animation event for reliable completion; the nonzero-slot event limitation is described below.
  8. Select the character, expand Item Abilities on Ultimate Character Locomotion, and select Block. Its Start Type and Stop Type are both Manual because Shield impacts control the lifecycle.
  9. Set Slot ID to -1 to respond to Shield Actions in every slot, or enter one slot ID to limit this Block ability. Keep Block Item State Index at 8 and Parry Item State Index at 9 when using the supplied Animator.
  10. Place Block above Aim when the reaction animation should replace the aim pose. List order controls which active item ability supplies the Animator values for a slot.

Block does not filter by Action ID or Item Category. It listens for any Shield Action impact, then uses only Slot ID to decide whether to react. Item Definition and category choices still control how the item enters the inventory and equipment set, but they do not select the Block ability.

Choose the protection behavior

Require deliberate aiming

Enable Require Aim when the collider should protect the player only while they are actively aiming. For a player character, an input-started Aim satisfies this requirement; passive first-person Aim does not. AI characters using a local look source can update the shield from their programmatically controlled Aim state.

When Require Aim is disabled, an equipped shield can absorb any eligible hit that contacts its enabled Shield Collider.

Use durability or an invincible shield

Leave Durability Attribute Name set to Durability to use the Attribute Manager created by the Item Manager. The shield removes only the amount it actually absorbs from that Attribute. When the Attribute reaches its minimum, later damage passes through to the character.

Leave the name empty for a shield that does not degrade. Drop When Durability Depleted is disabled by default; enable it when reaching the minimum should remove and drop one copy of the Character Item.

Absorb Explosions is disabled by default. An Explosion therefore bypasses both shield absorption and the Block reaction unless this option is enabled.

Choose block or parry animation

For a single reaction, a Shield-only defending item selects Block Item State Index 8; a defending item with both Shield and Melee actions selects Parry Item State Index 9. One Block ability stores one shared parry choice, however. With simultaneous mixed impacts, its latest accepted hit selects block or parry for every active slot. Use separate slot-specific Block rows when those reactions need independent state choices.

The attacking item affects the more detailed Item Substate Index, not the block-versus-parry choice. A melee attack can contribute its Animator Item ID and current use substate so different weapons or attack directions select different reaction clips.

Block and parry use the same Shield Action damage calculation. Parry changes the selected animation state; it does not grant a different absorption factor by itself.

Complete one slot or all slots

With Slot ID -1, one Block ability tracks multiple impacts and remains active until they complete, but their block/parry state choice is shared. Use the shared OnAnimatorItemImpactComplete event or a duration for completion.

The current slot-specific callback is unsafe for Slot ID greater than 0: a specific-slot Block stores one array entry, but the callback indexes it with the actual slot ID. For a nonzero slot, use a duration or the shared event, with slot-event waiting disabled. A slot-specific event requires a corrected callback before it can safely complete those reactions.

How it runs

  1. An impact hits the enabled Shield Collider for the current camera perspective.
  2. The Shield Action checks Require Aim and Absorb Explosions, then applies Absorption Factor and any available durability before the remaining damage reaches the character.
  3. When Apply Impact is enabled, the Shield Action selects its next impact Animator/audio state and sends OnShieldImpact.
  4. Block ignores a mismatched slot or a character currently using an item. Otherwise it starts and updates the Animator; the latest accepted impact supplies the shared block/parry choice for every active slot in that Block row.
  5. The Shield Action’s impact substate is used directly for a non-melee source. For a melee source, Block combines the attacker’s Animator Item ID, attack use substate, and shield impact substate.
  6. A configured duration or the shared impact-complete event ends the reaction. Block stops after no impacts remain; avoid nonzero-slot completion callbacks in the current implementation.

Block and damage protection are related but separate. A shield can absorb damage with Apply Impact disabled, and an active Block row only indicates that a visual impact reaction is in progress.

Understand ability order

Block does not use list priority to decide whether the shield may absorb damage. It explicitly declines a new reaction while any Use item ability is active, because the character cannot start a block reaction while using an item.

List order still controls animation when Block and another item ability are active together. Put Block above Aim or another persistent pose when the impact reaction should win. Decide its position relative to Reload or other short actions according to which animation should remain visible; the first active item ability with a valid value for that slot supplies the Animator parameter.

Verify in Play Mode

  1. Equip the Shield item and keep Ultimate Character Locomotion, the character’s health, and the shield’s Durability Attribute visible.
  2. Strike the Shield Collider with a non-explosion attack. Confirm Block (Active) appears briefly, the slot uses Item State Index 8, and only unabsorbed damage reaches the character.
  3. Confirm the reaction ends after 0.2 seconds or after the configured impact-complete Animator event.
  4. Enable Require Aim, repeat the hit without aiming, and confirm all damage passes through. Hold the Aim input and repeat the hit; confirm the shield now absorbs it.
  5. Add or test a defending item that contains both Shield and Melee actions. Confirm the reaction uses Item State Index 9 for parry.
  6. Test an Explosion with Absorb Explosions off and on, confirming that only the enabled case is absorbed.
  7. If using durability, repeat impacts until the Attribute reaches its minimum. Confirm further damage reaches the character and, when enabled, the shield item is dropped.

Troubleshoot Block

  • The character takes damage and Block never starts: check that the hit collider has Shield Collider, its Shield Action reference is assigned, and the collider is enabled for the active perspective. Resize the collider so the attack actually contacts it.
  • The shield absorbs damage but no reaction plays: enable Apply Impact, add at least one Impact Animator Audio State Set entry, and confirm the Block Slot ID accepts the shield’s Character Item slot.
  • Block becomes active but the aim or reload pose remains visible: check Item Abilities order. Move Block above the active pose that should yield, then confirm state indexes 8 and 9 exist in the Animator.
  • A hit during an attack does not start Block: the built-in ability declines shield reactions while Use is active. Finish or stop Use before testing the block.
  • Require Aim never protects the player in first person: press the Aim input. Passive first-person Aim intentionally does not satisfy Require Aim for a player character.
  • Durability never decreases: verify an Attribute Manager exists on the Character Item and that Durability Attribute Name exactly matches the Attribute. An empty or unresolved name behaves as a non-degrading shield.
  • Block remains active or a nonzero-slot event throws: use a duration or the shared OnAnimatorItemImpactComplete event and disable slot-event waiting. The current specific-slot callback indexes a one-entry array with the actual slot ID.
  • The wrong parry animation plays: confirm the defending item’s Melee Action and the attacking item’s Animator data. An all-slot Block shares its block/parry flag, so simultaneous Shield-only and Shield-plus-Melee impacts need separate slot-specific Block rows for independent state choices.
  • Shield Item Action covers damage absorption, durability, and impact presentation.
  • Item Creation explains how to build or update a Character Item through the Item Manager.
  • Aim explains input-started aiming and why passive first-person Aim is different.
  • Use explains the item ability that prevents a new Block reaction while active.
  • Animator Parameters describes Item State Index and Item Substate Index.
  • Default Animator Values lists the supplied item state conventions.

Developer reference

Block exposes SlotID, BlockItemStateIndex, ParryItemStateIndex, and the read-only ImpactSources array. StartBlock(ShieldAction, ImpactCallbackContext) is public, while GetItemStateIndex and GetItemSubstateIndex provide the per-slot Animator values.

For a melee impact, the substate is calculated as:

(attacker Animator Item ID * 1,000,000)
+ (attacker melee use substate * 1,000)
+ shield impact substate

For example, Animator Item ID 22, melee use substate 3, and shield impact substate 1 produce 22003001. Keep each component below 1000 if the Animator decodes the value as three groups.

The built-in Event System coordinates the reaction:

  • OnShieldImpact (ShieldAction, ImpactCallbackContext) is sent by Shield Action when Apply Impact is enabled. Block receives it and calls StartBlock.
  • OnAnimatorItemImpactComplete ends every active reaction that does not require a slot event.
  • OnAnimatorItemImpactCompleteSlot<slotID> is the slot-event name, but the current specific-slot callback is only safe at slot 0. Use shared completion or a duration for nonzero slots.
  • OnCharacterItemAbilityActive (ItemAbility, bool) is the standard item-ability lifecycle event and reports Block starting and stopping.

The Shield Action separately exposes Damage, StopBlockImpact, DurabilityValue, and WaitingForImpactCompleteEvent for custom damage or UI integrations.