Collision Trace System

Overview

The Collision Trace System enhances Unreal Engine’s Trace system, serving as the primary method for hit detection in weapons, projectiles, and spells within the Generic Combat System (GCS).

Core Features:

• Supports stable frame rates and distance/angle-based collision detection.
• Offers flexible collision detection methods and shapes.
• Manages Trace instances in a high-performance, multi-threaded manner for efficiency.

This document covers basic usage; refer to related documentation for upper-layer systems (e.g., weapons, spells).

Example Use Case

1. Two-Hand Targeting: Associates two collision traces with a character’s hands for targeting during punching/grabbing skills.
2. Projectile Detection: Creates trace instances based on Projectile shapes to detect hits during flight.
3. Dynamic Shape Adjustment: Adjusts trace shapes dynamically over activation time (e.g., radius changes).

Basic Setup

Trace System Component

Add UGCS_TraceSystemComponent to any Actor that needs collision detection. The component owns Trace handles and events; the world-level UGCS_TraceSubsystem owns TraceState and runs asynchronous sweeps. Trace state itself is not replicated.

• Function: Automatically creates and adds trace instances on initialization, with the SourceComponent set to the Actor’s primary Mesh component.
• Configuration: Supports a default set of trace definitions.

Trace Definition

TraceDefinition provides static data for TraceInstance.

Key Configuration: TraceTag (trace identifier).

Sweep Settings

Standard Sweep settings of Unreal Engine's trace system.

Collision Shapes

By default provide 4 type of collision shapes:

Static

Defines a static shape in the SourceComponent’s component space, with Offset and Orientation specifying relative position and rotation.

Socket-Based

Requires SourceComponent to be a MeshComponent, dynamically constructs a capsule shape and orientation from Start/End sockets, with Radius controlling size.

Shape-Based

Requires SourceComponent to be a ShapeComponent (e.g., Box, Sphere, Capsule), driving the collision shape.

Attached

Similar to static mode, but the shape’s Transform is based on a specified socket/bone’s world space.

Tick Types

Three Tick types supported:

Default Tick

Uses the game’s native frame rate; may miss targets at low frame rates.

Fixed Frame Rate

Specifies a target frame rate, reducing frames at high rates or adding frames at low rates to ensure hits.

Distance-Based

Performs hit detection based on SourceComponent position and angle change intervals.

Managing Trace Definitions

TraceDefinition inherits from FTableRowBase, allowing management of multiple Trace instances via DataTable. TraceSystemComponent accepts TableRowHandle instead of direct TraceDefinition.

Gameplay Integration

Melee Ability Integration

A melee Ability can create UGCS_AbilityTask_CollisionTrace with HandleCollisionTraces, then submit a UGCS_AttackRequest_Melee and SourceObject with AddMeleeRequest. The task requests and manages traces through TraceSystem using the request's TracesToControl tags, then reports hits to the Ability through OnTargetsFound (request, TraceHandle, and HitResult). RemoveMeleeRequest stops that request's traces. When the task is destroyed, it unbinds its callback and stops remaining traces.

The animation notify UGCS_ANS_AttackTrace only stores an editable melee request instance; it does not execute traces. Let the AbilityTask manage the trace lifecycle. See Combat Attack/Defense.

API Overview

APIs are categorized under GCS|TraceSystem:

Adding Trace Instances

To add a trace instance, you need to provide:

• Trace Definition: Includes TraceTag, collision shape, scan method, and Tick type.
• Source Component: The associated component (e.g., weapon Mesh, projectile Sphere).
• Source Object: Distinguishes similar Trace instances (e.g., primary/secondary weapon with Weapon tag). Returns a TraceHandle for further operations.

Adding a trace instance will returns a TraceHandle for further operations.

Example: When activating a weapon, its Mesh is the source component, and the weapon Actor is the source object, added to the TraceSystem.

Querying Trace Instances

Construct a TraceHandle using TraceTag, source component, and source object to query trace status.

Activating Trace Instances

Control trace activation with a TraceHandle. When active, traces execute collision detection based on Tick type, sweep settings, and shape type, returning HitResults. Example: Activate weapon trace instances during attack Montage weapon swings.

Debugging

Draw Debug Commands

The following commands assist with collision detection debugging:

Draw Debug Colors

Note: In editor multiplayer client mode, If you only see white Trace indicate server-side traces are not executing (e.g., SkeletalMeshComponent may disable Tick on dedicated servers).

Extensions

C++ users can create new collision shapes by inheriting from FGCS_CollisionShape and overriding relevant functions.

Example: Dynamic sphere radius based on trace activation duration.

	virtual FCollisionShape GetDynamicCollisionShape(const UPrimitiveComponent* SourceComponent, const float& Time) const;

GCS provides multiple built-in TraceShape implementations, typically sufficient for most needs.

Multiplayer Considerations

• Trace subsystems and instances are not replicated. Each World executes the local instances created and started there; hit results are not automatically synchronized to another machine.
• The same weapon can have separate Trace instances on server and client. Which machines actually run traces depends on the calling Actor, Ability, and network execution policy.
• The server should own authoritative hit and GameplayEffect settlement. Trace itself does not confirm a client hit.

Local predicted hit feedback requires a separate Ability / GameplayEffect path that supports prediction; for example, a predicted instant GameplayEffect can use UGCS_GEComponent_PredictivelyExecute. This capability does not come from Trace hit replication. Bullet prediction is narrower: only the trajectory and visual presentation of the first player-initiated batch are predicted; the server still handles hits and effects. See Bullet System.

You may create and start traces only on the server; choose the caller according to your authoritative hit and local presentation requirements.