🗡️ DamageBehaviorsSystem

Complex damage behaviors built from multiple capsule hit registrators, driven by UDamageBehavior assets and invoked via UANS_InvokeDamageBehavior.

Support: UE5.4 - UE5.6

✨ Features

• Damage Behaviors: Compose attacks from multiple capsules with filtering, per-source activation, payloads, and auto-damage handling.
• Anim Notify State: UANS_InvokeDamageBehavior to activate/deactivate behaviors over montage windows, with editor preview drawing.
• Hit Registrators: UCapsuleHitRegistrator capsules supporting ByTrace and ByEntering detection modes, ignore lists, and debug visualization.
• Sources System: Evaluate and target multiple sources (e.g., ThisActor, RightHand, LeftHand) via UDamageBehaviorsSourceEvaluator.
• Blueprint Events: Override behavior decisions in Blueprints (ProcessHit, CanBeAddedToHittedActors, etc.) or bind to delegates.
• Settings: Project settings for trace channel and default source evaluators; debug actors to preview capsules in editor.

🚀 Install & ⬆️ Update

From source (recommended)

# install as git submodule to your plugins folder
git submodule add https://github.com/Ciberusps/DamageBehaviorsSystem.git ./Plugins/DamageBehaviorsSystem

# to update plugin
git submodule update --remote

📄 Documentation

• Components
  • UDamageBehaviorsComponent
• Behaviors
  • UDamageBehavior
• Hit Registrators
  • UCapsuleHitRegistrator
• Anim Notify State
  • UANS_InvokeDamageBehavior
• Settings
  • UDamageBehaviorsSystemSettings
• Blueprint Library
  • UDamageBehaviorsSystemBlueprintLibrary

UDamageBehaviorsComponent

Attach to an actor to host and control UDamageBehavior instances.

• Properties

  • DamageBehaviors (Instanced): list of behaviors; each has a Name used to invoke.

• Delegates

  • OnHitAnything(DamageBehavior, DamageBehaviorName, HitRegistratorHitResult, CapsuleHitRegistrator, Payload)

• Key Functions

  • InvokeDamageBehavior(Name, bShouldActivate, DamageBehaviorsSourcesToUse, Payload)
  • GetDamageBehavior(Name)
  • GetDamageBehaviors()

Usage: Place capsules (UCapsuleHitRegistrator) on your actor or its equipment, configure sources (e.g., ThisActor, RightHand, LeftHand), and call InvokeDamageBehavior to start/stop windows.

UDamageBehavior

Defines how hits are detected and processed while active.

• Fields

  • Name: identifier used by notify/component.
  • HitDetectionSettings: EDamageBehaviorHitDetectionType = ByTrace or ByEntering, plus overlap options and collision profile for entering mode.
  • bAutoHandleDamage: auto call into your damage pipeline (AI-friendly).
  • bInvokeDamageBehaviorOnStart: utility for ability-driven flows.
  • bAttachEnemiesToCapsuleWhileActive: optional attach behavior during active window.
  • HitRegistrators to Activate: per-Source list of capsule names to enable.
  • Comment: free text.

• Blueprint Events

  • MakeActive(bShouldActivate, Payload)
  • ProcessHit(HitRegistratorHitResult, CapsuleHitRegistrator, inout Payload_Out) -> bool
  • CanBeAddedToHittedActors(HitRegistratorHitResult, CapsuleHitRegistrator) -> bool
  • GetHitTarget(HitActor, HitRegistratorHitResult, CapsuleHitRegistrator) -> AActor*
  • AddHittedActor(Actor, bCanBeAttached, bAddAttachedActorsToActorAlso)
  • ClearHittedActors()

• Delegates

  • OnHitRegistered(HitRegistratorHitResult, DamageBehavior, CapsuleHitRegistrator, Payload)

Behavior lifecycle: when activated, it enables configured capsules by Source; hits are filtered (deduped per target) and surfaced via delegate or ProcessHit.

UCapsuleHitRegistrator

Capsule component that registers hits for behaviors.

• Key Functions

  • SetIsHitRegistrationEnabled(bEnabled, HitDetectionSettings)
  • AddActorsToIgnoreList(Actors)

• Delegate

  • OnHitRegistered(HitRegistratorHitResult, CapsuleHitRegistrator)

Hit modes:

• ByTrace: traces along movement each tick.
• ByEntering: uses overlaps; supports bCheckOverlappingActorsOnStart and a configurable CollisionProfileName (e.g. VolumeHitRegistrator).

UANS_InvokeDamageBehavior

Anim notify state to open/close behavior windows.

• Name: behavior name to invoke.
• TargetSources: map of SourceName -> enabled; if empty, defaults to ThisActor.
• Payload: FInstancedStruct passed into behavior for custom data.

Editor Preview: in Animation editors the notify can spawn configured DebugActors and draw capsules for fast authoring.

UDamageBehaviorsSystemSettings

Project Settings -> DamageBehaviorsSystemSettings:

• HitRegistratorsTraceChannel: channel to trace in ByTrace mode.
• DamageBehaviorsSourcesEvaluators: list of UDamageBehaviorsSourceEvaluator classes to provide actors per source name.
• DebugActors: per-mesh list of debug actors for editor preview.
• Fallback Debug Mesh: debug actors used when no specific mesh entry exists.

UDamageBehaviorsSystemBlueprintLibrary

• GetTopmostAttachedActor(Actor) -> Actor*: utility used in target resolution.

💡 Use

1. Add UDamageBehaviorsComponent to your character/weapon blueprint.
2. Add UDamageBehavior entries in DamageBehaviors and configure:
   • Name, HitDetectionSettings
   • HitRegistrators to Activate per Source (names must match your capsule component names)
3. Place UCapsuleHitRegistrator components on your actor/equipment and set their collision profile.
4. In your attack montage, add UANS_InvokeDamageBehavior spanning the hit window and set Name + TargetSources.
5. Optionally handle OnHitAnything on the component or OnHitRegistered on the behavior to apply damage/effects.

Tips:

• If no TargetSources are specified, the system uses ThisActor.
• Use payload to pass per-attack parameters (e.g., damage scalars, tags).

🧪 Debugging

• Enable capsules visualization via project settings DebugActors and Fallback Debug Mesh.
• UCapsuleHitRegistrator will draw traces/overlaps when the debug cvar is enabled.
• Common checks:
  • Ensure capsule collision profile allows overlaps/hits for the chosen channel.
  • Verify HitRegistrators to Activate names match actual component names.
  • Confirm TargetSources are enabled for your notify instance.

🧩 Notes

• The plugin registers a runtime module DamageBehaviorsSystem and an editor module DBSEditor.
• Integrates well with GameplayAbilities for ability-driven attack windows.

TODO:

• debug actors presets - for Sword + Shield, Axe + Shiled quick swap

• debug actors presets that works by Animation name, e.g. for sword anim s Sword + Shield, for axe - Axe + shield

• when we pause in ANS it should show CapsuleHitRegistrator shapes

• split DamageBehaviorsSystemSettings, DebugActors should be in separate settings for EditorOnly

• move Debug from ANS to DBSEditor module completly