PrimalHit Documentation

System Overview

Unreal Engine’s native line and shape sweeps are incredibly powerful but inherently rigid for advanced combat design. Modern action RPGs require multi-stage, terrain-conforming, and mathematically complex hit detection.

PrimalHit abstracts complex spatial mathematics away from scattered character blueprints and deep timeline loops, centralizing them into a highly optimized, Tickable World Subsystem. With a single Blueprint node or C++ call, designers can execute frame-synced, multi-phase hitboxes that scale predictably without clogging the main game thread.

Core Architecture

The framework relies on a triad of core modules to separate data, execution, and actor attachment:

Integration Guide

Option A: Gameplay Ability System (GAS) Blueprint

PrimalHit integrates seamlessly with GAS using a unified FPrimalTracePreset struct. No complex Custom C++ Thunks or wildcard pins are needed. Simply construct a preset and pass it into the task. The system automatically routes the correct geometric data at runtime, immediately canceling traces if the ability is interrupted.

1. Inside your Gameplay Ability Graph, search for Launch Primal Trace.
2. Drop a Make Primal Trace Preset node and configure your specific trace type and parameters.
3. Connect the preset into the Preset pin on the ability task.
4. Supply an Origin (or define an Origin Socket on the Avatar's Skeletal Mesh).
5. Bind execution logic to the OnHit and OnExpired pins.

Option B: Actor Component (Non-GAS) C++ Blueprint

If a specific weapon or boss governs its own traces outside of GAS, attach the UPrimalHitTraceComponent to your Actor.

1. Add the Primal Hit Trace component to your blueprint.
2. Drag off the component and call specific trace launchers like Launch Dragon Breath.
3. Bind events to the component's OnTraceHit delegate. The component automatically handles cleanup in EndPlay.

Custom Hit Resolution (FCustomHitResult)

Because PrimalHit calculates complex volumes, a standard FHitResult is insufficient. The system returns an FCustomHitResult containing advanced geometric metadata for damage scaling and physics application.

Trace Query Parameters

Every trace accepts an FPrimalTraceQueryParams struct that controls its foundational rules.

• bAllowMultiHitPerActor:
  • If False, the trace deduplicates hits internally. An enemy hit by wave 1 of a Shockwave will gracefully ignore wave 2.
  • If True, the trace fires continuous hits every tick (Ideal for continuous damage fields like Pulse Aura or Dragon Breath).
• IgnoredActors: A TArray<AActor*> to specifically ignore during sweeps. The Instigator is ignored automatically.
• bDebugDraw: Overrides the visualizer to render the 3D geometry of the trace.

Physical Traces (Kinetic)

These traces mimic physical impacts, structural disruptions, and rapid ground expansion. They are designed for grounded, heavy combat mechanics.

Shockwave

Propagates outward along the floor. Creates a primary impact, followed by expanding geometric rings (configurable as Spheres, Boxes, or Capsules) over time. Perfect for heavy slam attacks and boss terrain disruptions.

Seismic Wave

Casts a fan of directional capsules that rush forward in a V-formation. Features configurable WaveSpeed and FanHalfAngle.

Grid Sweep

Executes an NxN lattice of box traces in a flat grid pattern. Designed for tactical AoE hazards, minefield detonations, or precise boss grid attacks.

Tunnel Trace

A capsule that sweeps along a defined spline, expanding in radius as it reaches its destination. Built for burrowing enemies and subterranean charges.

Volumetric Traces (Magical)

These traces utilize advanced spatial mathematics, rotation, and continuous frame interpolation to simulate physics-defying abilities.

Black Hole

A sustained concentric gravity well. Actors inside the InnerRadius receive maximum gravity. Actors caught between the inner and outer radius receive gravity interpolated exponentially by a FalloffExponent. Outputs frame-synced force data directly to Blueprint.

Orbital Ring

Spawns multiple physical spheres that orbit a center point at a fixed radius, matching a defined rotational speed. Ideal for defensive satellite shields or rotating blade barriers.

Pulse Aura

A sustained volume attached to a moving target that performs periodic full-sphere overlap checks on a set interval. Useful for aura damage or persistent debuff fields that move with characters.

Frost Nova

Expands rapidly to a MaxRadius, then fires PulseCount repeat sweeps at a defined interval, simulating waves of freezing energy.

Projectile & Utility Logic

Lightning Chain

Resolves an instantaneous initial hit, then eagerly calculates N subsequent jumps to nearby targets based on distance parameters, decreasing the NormalizedFalloff with each jump.

Homing Spiral

Sweeps a tightening corkscrew pattern toward a designated target actor, testing for physical collision prior to reaching the target. Perfect for projectiles that must respect level geometry.

Bounce Pierce

A single sphere that reflects off surfaces N times, tracking bounce normals. Built for ricochet mechanics and mirror magic.

Wall Crawl

A sphere trace that strictly follows a surface normal, crawling along walls and ceilings.

Debug Visualization

The framework includes the PrimalHitTraceVisualizer—an editor-only Tickable Subsystem.

When bDebugDraw is toggled true inside your trace query, the visualizer intercepts the active trace and renders an accurate 3D wireframe. Colors are customized globally via FPrimalTraceDebugSettings.

// Example Debug Configuration mapped internally
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Debug")
FLinearColor ShockwaveColor = FLinearColor(1.f, 0.4f, 0.f); // Kinetic Amber

UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Debug")
FLinearColor BlackHoleColor = FLinearColor(0.4f, 0.f, 1.f); // Volumetric Violet

UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Debug")
FLinearColor OrbitalRingColor = FLinearColor(0.8f, 0.9f, 1.f); // Silver