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
- Two-Hand Targeting: Associates two collision traces with a character’s hands for targeting during punching/grabbing skills.
- Projectile Detection: Creates trace instances based on Projectile shapes to detect hits during flight.
- Dynamic Shape Adjustment: Adjusts trace shapes dynamically over activation time (e.g., radius changes).
Basic Setup
Trace System Component
Add the GCS_TraceSystemComponentto any Actor requiring collision detection to manage runtime states of associated Trace instances.
- 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
API Overview
APIs are categorized under GCS|TraceSystem:
Loading Blueprint
Initializing BlueprintUE renderer...
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:
Console Commands | Purpose |
|---|---|
gcs.debug.EnableTraceDebugging true/false | Globally enable/disable Trace debugging (true/false) |
gcs.debug.OverrideTraceDebuggingLifeTime 0.2 | Control Trace debug draw duration (>0) |
Draw Debug Colors
Trace Color
For better debugging:
Server Side:The trace color will be Red, The hit color will be Green.
Client Side: The trace color will be White, The hit color will be Black.
In this setup, you can know the different between server and client trace differences.
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.
1 virtual FCollisionShape GetDynamicCollisionShape(const UPrimitiveComponent* SourceComponent, const float& Time) const;
GCS provides multiple built-in TraceShape implementations, typically sufficient for most needs.
Note
Before you overt-thinking the "dynamic shape over time", try use trace system and bullet sysytem together first! Sometimes, compositing simple tools can deliver complex results.
Multiplayer Considerations
- Independent Systems: Each client has an independent Trace subsystem.
- Independent Instances: Trace instances on each client are unrelated, producing only events and hits.
- Server/Client Separation: Identical objects have separate Trace instances on server and client.
Weapon Example:
- Server and client weapon versions each have their own Trace. During swings, hit events trigger separately:
- Server: Executes critical gameplay logic (e.g., applying GameplayEffect).
- Client: Handles local visual logic without server delay for hit feedback.
- Client Prediction: Enables HitReaction prediction.
- Flexibility: Optionally create Trace only on the server; control is up to the developer.