Use ordered Impact Action Groups to turn a reported hit into damage, force, surface feedback, states, or callbacks. The reporting melee/shootable/magic module owns detection; this group owns the selected result.

Configure ordering and context

Select the hit-producing module, open Impact Actions, add rows, and order gameplay changes before presentation and callbacks. Use Fail Impact Actions for a condition-rejected result. A typical firearm uses Simple Damage, Spawn Surface Effect, optional particle/audio, then Impact Event.

Impact Action Group containing Simple Damage, Spawn Surface Effect, State Impact, and Impact Event, all enabled with zero delay

The image is an example rather than the newly created default group.

Shared field Default Behavior
Enabled On Skip disabled actions.
Delay 0 Immediate, or independently scheduled when positive.
Allow Multi Hits Off Source-ID repeat tracking when the caller permits it.
Bindings / States Empty/default Property bindings and State overrides.

Immediate rows share mutable ImpactCallbackContext; later rows see earlier changes. Delayed rows snapshot when reached, and the group continues without waiting. Populate explicit damage data before scheduling; keep optional-null-sensitive actions immediate. Destroy owned groups to cancel outstanding schedules; resetting a Source ID clears repeat tracking without cancelling schedules.

Control standard weapon repeat hits through module detection/cooldown. Generic weapon impact modules force invocation; custom/receiver/nested flows can pass forced impact false to enforce action repeat maps.

Damage and character results

Simple Damage

Supply a valid Impact Collider and either local values or source-provided ImpactDamageData.

Field Default Purpose
Use Context Data Off Read damage, processor, force/frames, and radius from supplied data; otherwise use local values.
Damage Processor None Use the selected/source processor or default processing.
Damage Amount 10 Local damage before optional strength/shield adjustment.
Impact Force / Impact Force Frames 2 / 15 Strength-scaled force and character duration.
Impact Radius 0 Positive radius selects Rigidbody explosion force.
Scale Damage By Impact Strength Off Apply source strength, such as explosion falloff, to damage.
Invoke On Object Impact Off Notify collider/Rigidbody/resolved target paths. Prefer one Impact Event target callback for exactly-once receiver delivery.

Populate shared damage data in the source/custom context when downstream actions need it. The selected processor applies damage through IDamageTarget, with a source DamageProcessorModule taking precedence. Shields can adjust damage. Without a damage target, force can reach a parent IForceObject or reported non-kinematic Rigidbody. A damage-data Layer Mask is not a Simple Damage filter; apply detection/conditions separately.

Other character actions

Action Configuration
Heal Parent Health lookup; Amount 10, Interrupt Impact On Null Health on. Select failure behavior with conditions/custom branching or put Heal last; later group rows continue independently.
Modify Attribute Parent Attribute Manager; Attribute Name empty, Amount 0, Auto Update off. Use immediate changes here; use a project timed workflow for duration/cleanup. Serialized timing starts at delay 1, interval 0.1, duration -1.
State Impact Character root or target State; Use Context Data off, Impact State Name empty, timer 10 seconds (-1 for manual release). Context mode uses both supplied name and timer, including an empty name.
Character Knock Back Parent locomotion’s installed Impact Knock Back, selected by ID 0 initially.

Motion and feedback actions

Action Configuration and ownership
Add Force Amount zero, Frames 5, Mode > Force, Use Source Direction off, Add Force At Position off. Prefer parent locomotion, then IForceObject, then non-kinematic Rigidbody.
Add Torque Zero Amount, Mode > Force. Requires Rigidbody directly on Impact GameObject; provide a custom reported-Rigidbody action for child-target layouts. No impact-strength scaling.
Spawn Surface Effect Use Context Data off, Surface Impact None. In context mode, a non-null surface overrides the local asset. Supply valid RaycastHit and collider, including zero-damage shield checks.
Spawn Particle ParticleSystem prefab, zero position/rotation offsets, Parent To Impacted Object off. Use nonzero direction; looping instances track Source ID and stop on reset.
Play Audio Clip Audio Config/clip set, initially empty; random clip at RaycastHit.point. For manually constructed contexts, supply a valid hit or use position-based project audio.
Generic Item Effects Initialized Effect Group on the owning Character Item Action. Effects receive item context rather than impact context.

For Add Force, source-direction mode transforms Amount through the source; otherwise Amount is component-wise scaled by Impact Direction. Impact Strength scales both. Frames applies to character/IForceObject. Ordinary Rigidbody mode uses Mode/position choices; a positive context radius uses the squared magnitude of the scaled Amount for explosion force instead.

Surface effects use the hit, source gravity/time scale, and visible item/source as originator. Zero context damage suppresses non-shield surface feedback. Avoid duplicating Simple Damage’s force with Add Force unless the extra push is intentional.

Callbacks, branches, and reuse

Action Configuration
Impact Event Originator callback on by default: OnObjectImpactSourceCallback to source. Target callback on: OnObjectImpact to Impact GameObject. Originator runs first; receiver-based conditions need the target callback.
Impact Unity Event Initially empty On Impact Event, carrying the full context.
Debug Impact Context Empty Message, followed by context logging. Use temporarily before/after a suspicious row.
Conditional Impact Action ANDed Conditions select one pass/fail group. Reset Damage Data On Fail is off; when selected, reset happens after the fail group. See Conditions.
Use Impact Action Object Assign a reusable group asset. Configure enabled/timing/repeat controls inside the asset and isolate runtime instances for concurrent owners.
Ricochet Radius 10, chain limit 1 (-1 unlimited), collision capacity 50, Merge Data Layers on, Detect Layers > Nothing.

Create reusable groups through Assets > Create > Opsive > Impact > Impact Action Group Object. Defaults are Simple Damage, Spawn Surface Effect, and Impact Event, with the first two reading context. Give stateful delayed/bound groups independent runtime instances when several characters can use them simultaneously.

Ricochet ORs local/context layers when merging, ignores triggers, and searches around RaycastHit.point. It raises C# OnRicochet data rather than generating another shot. Use it with a Character Item Action owner; Magic’s Ricochet Impact is a built-in subscriber, while firearms need their own subscriber/module.

Verify and extend

Test a damageable character, plain Rigidbody, and missing-component target. Check firearm damage/feedback/callback order, sword State/knock-back requirements, explosion radius/falloff, and explicit heal/attribute failure branching. Test delayed rows after immediate rows, source reset, group destruction, overlapping owners, and exactly-once receiver delivery.

ImpactCallbackContext contains collision data and optional IImpactDamageData. Provide source/target, collider/Rigidbody, hit/position/direction, strength, Source ID, layers, and optional surface/state data deliberately. See Damage Processor, Surface System, and Attributes.

Custom actions derive from ImpactAction; its base supplies gating, timing, and repeat handling:

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

[Serializable]
public class LogImpactTarget : ImpactAction
{
    [SerializeField] private string m_Label = "Impact";

    protected override void OnImpactInternal(ImpactCallbackContext ctx)
    {
        var collision = ctx.ImpactCollisionData;
        Debug.Log($"{m_Label}: {collision.ImpactGameObject} at {collision.ImpactPosition}");
    }
}

Initialize a custom-owned group, call OnImpact(context, forceImpact) with false when repeat maps should apply, Reset(sourceID) at cycle end, and OnDestroy() for schedules/nested resources. Preserve those responsibilities in custom wrappers.