Impact Action Conditions

Export

Impact Action Conditions let an item accept, reject, or branch an impact before it applies damage, effects, or target reactions. Use them when an Iron Sword should affect only particular targets, a firearm should react differently to projectile and non-projectile impacts, or the target should own the rule.

Choose where the rule belongs

Goal Use Why
Choose different actions on the attacking item Conditional Impact Action The source evaluates one condition list, then runs either its pass or fail actions.
Let each target decide whether the source may affect it Impact Condition Behaviour on the target plus Check Target Impact Condition Behaviour on the source One sword or firearm can respect different target-owned rules without listing every target on the item.
Let the target run its own pass or fail response Conditional Impact Receiver on the target The target receives the impact callback, evaluates its rules, and owns both result branches.
Gate an entire impact module The module’s Conditions list Melee, shootable, throwable, and magic impact modules use the same condition-group behavior.

Conditions in one list are combined with AND. Put the cheapest, most general test first so a failed test can stop the remaining checks.

Branch actions on the source

Add Conditional Impact Action to an Impact Actions list when the item should choose what happens next.

  1. Add the required entries to Conditions.
  2. Add damage or other successful results to Impact Actions On Pass.
  3. Add feedback for a rejected impact to Impact Actions On Fail. This list may be empty.
  4. Enable Reset Damage Data On Fail only when later actions in the surrounding list must not reuse damage data prepared before this branch. It is disabled by default.

Conditional Impact Action with Check Target Impact Condition Behaviour, Simple Damage on pass, and Play Audio Clip on fail

The fail branch is invoked before Reset Damage Data On Fail clears the damage data. With the Conditional Impact Action’s default Delay of 0, the reset therefore affects later sibling Impact Actions, not the actions already invoked inside the fail branch. If the Conditional Impact Action itself has a delay, outer actions can run before the delayed branch and reset. A failed condition selects the fail branch; it does not stop later actions in the outer Impact Actions list.

Put reusable rules on the target

Use Impact Condition Behaviour when a target should describe what is allowed. For example, a reinforced crate can accept only an Iron Sword definition while another crate accepts the broader weapon category.

  1. Add Impact Condition Behaviour to the hit GameObject or its Rigidbody GameObject.
  2. Add one or more entries to Impact Action Conditions.
  3. On the weapon’s condition list, add Check Target Impact Condition Behaviour.

The released Version 3 Inspector below shows the definition condition before its Item Definitions list is populated. Add at least one definition before testing a whitelist.

Impact Condition Behaviour with an enabled Check Weapon Source Definition condition and an empty Item Definitions list

Check Target Impact Condition Behaviour first looks on the reported impact GameObject, then on the impact Rigidbody GameObject. If neither has an ImpactConditionBehaviourBase, the check passes. It does not require every target to have the component and it does not search an arbitrary parent or child hierarchy.

Let the target own the result

Use Conditional Impact Receiver when the target should run the result instead of merely approving a source-owned action.

  1. Add Conditional Impact Receiver to the target.
  2. Leave Get Impact Conditions On Object enabled to include other IImpactCondition components on the same GameObject. Add external components to Impact Conditions Behaviours only when needed.
  3. Add local entries to Impact Action Conditions.
  4. Configure Impact Actions On Pass, On Object Impact Success, Impact Actions On Fail, and On Object Impact Fail.
  5. Make the attacking item send the target callback. An Impact Event does this when Call Impact Callback On Target is enabled; Simple Damage does it only when Invoke On Object Impact is enabled.

Conditional Impact Receiver running Simple Damage on pass and separate success and fail events

All discovered, assigned, and local conditions must pass. Do not assign the same behavior explicitly when Get Impact Conditions On Object already discovers it on the receiver GameObject, or the receiver will evaluate it twice.

Built-in condition catalog

Every built-in condition has Enabled, Bindings, and States. Enabled defaults to on; turning it off makes that entry pass so the group ignores it.

Respect target-owned rules

Check Target Impact Condition Behaviour has no additional fields. It evaluates an ImpactConditionBehaviourBase on the impact GameObject or, as a fallback, the impact Rigidbody GameObject. If no behavior is found, it returns true.

Use it on an Iron Sword or firearm when each target should define its own accepted weapon categories, definitions, or custom rules.

Match a target by Object Identifier

Object Identifier Impact Condition accepts an impact only when it finds an ObjectIdentifier with the configured Target ID:

  • Target ID defaults to -1, which matches nothing.
  • Search In Children defaults to enabled. It searches the reported target and its children, including inactive children. Disable it to search the target and its parents instead.

This condition identifies the target, not the weapon or projectile source. In released Version 3 it forces an ID search, so assigning only the object-reference half of Target ID does not satisfy the condition. Add an ObjectIdentifier, give it the matching numeric ID, and choose the correct search direction.

Filter by the source item

Check Weapon Source Category compares the source Character Item with Item Categories. Membership includes definitions inherited by a selected category.

  • Allow Non Weapon Impact defaults to disabled. Enable it when impacts without a Character Item Action should pass.
  • Exclude Category defaults to disabled. Disabled makes the list a whitelist: a matching category passes. Enabled makes it a blacklist: a matching category fails and a nonmatching category passes.
  • Item Categories starts empty. With the default whitelist behavior, an empty serialized list accepts no weapon item.

Use a category rule when several definitions should share the result, such as every item in a melee-weapon category.

Check Weapon Source Definition applies the same logic to Item Definitions and inherited definition membership. Use it for a precise rule such as accepting Iron Sword but not every melee weapon.

  • Allow Non Weapon Impact defaults to disabled.
  • Exclude Category defaults to disabled and controls include-versus-exclude behavior.
  • Item Definitions starts empty.

In released Version 3 the definition condition’s include/exclude field is labeled Exclude Category even though it filters definitions. Treat that label as Exclude Definition; this is an Inspector-label mismatch, not a category filter.

Filter projectile impacts

Projectile Impact Action Condition checks for a Projectile component directly on the impact context’s source GameObject.

Desired result Allow Non Projectile Impact Allow Projectile Impact
Projectiles only Off On
Non-projectile impacts only On Off
Both On On
Neither Off Off

Both fields default to off, so an unconfigured condition rejects every impact. The built-in check does not search the source’s parents or children.

Filters that need a different setup

Released Version 3 has no built-in Impact Action Condition for a layer, attribute, or surface. Use the closest source-owned setting when it expresses the rule, or add a custom condition when the decision must occur in this list.

Filter Practical choice
Target layer Prefer the attack module’s collision/detection layer controls so unwanted objects are never reported. A custom condition can instead inspect the layer of ImpactGameObject. DetectLayers in the context is the mask used for detection, not the target’s layer.
Target attribute Use a custom condition to find the target’s attribute component from ImpactGameObject and evaluate the required value.
Surface Use a custom condition to inspect ImpactCollisionData.SurfaceImpact. Surface-based effects do not by themselves accept or reject an impact.
Target identity Use Object Identifier Impact Condition and a matching ObjectIdentifier.
Source category or definition Use Check Weapon Source Category or Check Weapon Source Definition.

How evaluation runs

For every impact, the group checks its entries from top to bottom:

  1. A disabled condition returns true and is skipped in practice.
  2. The first enabled condition that returns false stops the group.
  3. If every enabled condition passes, the group returns true. An empty condition list passes.
  4. Conditional Impact Action runs one branch. Conditional Impact Receiver checks same-GameObject conditions first, then assigned behaviors, then its local condition group. It invokes the selected UnityEvent before the corresponding action branch.

There is no built-in OR mode within one group. To express OR, write one custom condition that owns the alternatives or restructure the outcome with separate conditional branches or receivers.

Firearm example

To let a firearm run one impact result only for projectiles, add Projectile Impact Action Condition, enable Allow Projectile Impact, and leave Allow Non Projectile Impact disabled. Put the damage and surface effects in the pass branch and optional rejection feedback in the fail branch.

Iron Sword example

To let each target decide whether Iron Sword may damage it, add Check Target Impact Condition Behaviour to the sword’s condition list. On the protected target, add Impact Condition Behaviour with Check Weapon Source Definition, leave Exclude Category disabled, and add Iron Sword to Item Definitions. Targets without a behavior still pass, so add behaviors to every target that needs this policy or use an Object Identifier/custom requirement when the component must be present.

Editor checkpoint

Before entering Play Mode, confirm that:

  • every condition row is enabled and ordered from broad checks to specific checks;
  • whitelist lists contain at least one category or definition;
  • a projectile condition has at least one allow toggle enabled;
  • target-owned rules are on the reported hit object or its Rigidbody GameObject; and
  • a Conditional Impact Receiver has a source action that sends OnObjectImpact to the target.

Verify in Play Mode

Test one passing and one failing case without changing the configuration between runs.

Test Expected result
Iron Sword hits a target whose definition whitelist includes it Pass actions run; fail actions do not.
A different definition hits that target The first failing definition condition stops the list and the fail result runs.
A projectile hits a projectiles-only branch The projectile pass result runs.
A melee collider hits the same branch The non-projectile fail result runs.
A source checks a target that has no Impact Condition Behaviour Check Target Impact Condition Behaviour passes.
An Impact Event reaches a Conditional Impact Receiver Exactly one of the receiver’s success or fail events and action lists runs.

When debugging a longer list, temporarily disable later entries. A disabled entry is ignored, so this isolates the first unexpected result without changing the list order.

Troubleshooting

Symptom Check Fix
Every impact takes the fail branch A projectile condition may still have both allow toggles off, or a source whitelist may be empty. Enable the intended projectile result or populate the category/definition list.
A definition filter appears to use categories Released Version 3 labels the definition condition’s toggle Exclude Category. Interpret it as include/exclude definition; leave it off for a whitelist.
Object Identifier never passes The condition requires a numeric ID match and forces a hierarchy search. Add ObjectIdentifier, match Target ID, and set Search In Children for the actual hierarchy direction. Do not rely only on the mapped object field.
A target-owned rule is ignored Check Target Impact Condition Behaviour only checks the reported target and its Rigidbody GameObject. Move the behavior to one of those objects or use a custom hierarchy-aware condition.
Conditional Impact Receiver never runs The source may not invoke the target impact callback. Add Impact Event with Call Impact Callback On Target, or enable Invoke On Object Impact on Simple Damage.
A receiver evaluates a rule twice The same behavior may be auto-discovered and listed in Impact Conditions Behaviours. Keep only one route to that behavior.
Damage data remains available after rejection Reset Damage Data On Fail may be off, or a fail action is reading the data before the reset. Enable the field when later outer actions must not reuse the data; remember that fail-branch actions run before it is cleared.

Developer reference

Create a serializable class derived from ImpactActionCondition and override CanImpactInternal. The context supplies the reported target, source, collider, Rigidbody, detection mask, surface data, Character Item Action, and any prepared damage data. Returning false stops the remaining conditions in that group.

This example adds the missing target-layer filter:

using System;
using Opsive.UltimateCharacterController.Items.Actions.Impact;
using UnityEngine;

[Serializable]
public class TargetLayerImpactCondition : ImpactActionCondition
{
    [SerializeField] private LayerMask m_AllowedLayers = ~0;

    protected override bool CanImpactInternal(ImpactCallbackContext ctx)
    {
        var target = ctx.ImpactCollisionData?.ImpactGameObject;
        return target != null &&
               (m_AllowedLayers.value & (1 << target.layer)) != 0;
    }
}

Derive a reusable target component from ImpactConditionBehaviourBase when the rule belongs to the target rather than an item condition list. Implement CanImpact(ImpactCallbackContext ctx) and place the component where Check Target Impact Condition Behaviour can find it.