Trace and bullet definitions

This page covers the collision shapes used by melee windows and bullet hits, and how a bullet row overrides the instance, chains, and emitters. Concepts are in Traces and hit windows and Bullet runtime.

`FGCS_TraceDefinition`

A Data Table row, also commonly inlined on a weapon or bullet definition. UGCS_TraceSystemComponent creates the instance; UGCS_TraceSubsystem submits async sweeps on the tick policy. One definition is one shape + one query mode + one sample cadence. Start and stop come from a melee request’s TracesToControl, weapon activation, or a bullet lifetime.

IsValidDefinition() requires a valid TraceTag and a usable shape instance. Invalid rows warn during weapon validation and never register at runtime.

Field	Purpose	When to change	Misconfiguration
`TraceTag`	Instance identity. Categories=`GGF.Combat.Trace`.	Blade, tip, and bullet body each get their own tag.	A tag that does not match `TracesToControl` never starts.
`CollisionShape`	Instanced shape based on `FGCS_CollisionShape`. Default Static.	See the next section.	Attached / Socket Based with a missing socket fails initialization.
`SweepSetting`	Query source: channel, object types, or profile.	See the table below.	A channel the target ignores looks like a clean miss.
`TraceTickType`	Sample policy. Default `FixedFrameRate`.	Fast swings use a distance threshold; normal melee uses a fixed rate.	A large `DistanceBased` threshold misses fast cuts.
`FixedTickFrameRate`	Fixed rate. Default 30. `FixedFrameRate` only.	Denser blade samples.	Very high rates flood async sweeps.
`DistanceTickThreshold`	Move at least this far before sampling. Default 30. `DistanceBased` only.	Weapons that travel quickly.	The old name `DistanceTickInterval` redirects here. New tables should use Threshold.
`AngleTickThreshold`	Also sample after this many degrees of rotation. Default 15. `DistanceBased` only.	Twisting in place with little translation.	A tiny value sweeps almost every frame.

There is also a Default tick type that uses the subsystem default. New tables should pick Fixed or Distance explicitly.

`FGCS_TraceSweepSetting`

Field	Purpose	When to change	Misconfiguration
`SweepType`	`ByChannel` / `ByObject` / `ByProfile`. Default channel.	Pick one scheme for the project and stay with it.	`ByProfile` with an empty `ProfileName` queries nothing.
`TraceChannel`	Channel query. Default `ECC_Visibility`.	Characters on Pawn or a custom weapon channel.	Visibility misses bodies set to Ignore.
`ObjectTypes`	Object-type array. `ByObject` only.	Only Pawn and WorldStatic.	An empty array hits nothing.
`ProfileName`	Collision profile name. `ByProfile` only.	Reuse an existing weapon profile.	A typo fails the query.
`bTraceComplex`	Trace against complex collision.	A blade that must hug the weapon mesh.	Expensive, and usually unnecessary on characters.

Collision shapes

CollisionShape excludes the base struct and samples in SourceComponent space. Four built-ins:

Shape	Display name	Role	When to use	Misconfiguration
`FGCS_CollisionShape_Static`	Collision Shape (Static)	A fixed Sphere / Box / Capsule in source-component space.	Fists, a staff of fixed length.	Forgetting Orientation on Box/Capsule sweeps off-axis.
`FGCS_CollisionShape_ShapeBased`	Collision Shape (Shape Based)	Binds a Box/Sphere/Capsule on the source component and copies its size.	The weapon already has a collision component.	A non-shape source never receives dimensions.
`FGCS_CollisionShape_Attached`	Collision Shape (Attached)	Static shape that follows `SocketOrBoneName`.	The edge hangs on a tip socket.	A wrong socket name parks the shape at the component origin.
`FGCS_CollisionShape_SocketBased`	Collision Shape (Socket Based)	A capsule between `MeshSocketStart` / `MeshSocketEnd` (defaults TrailStart / TrailEnd).	Blade trails, two-socket weapons.	Missing sockets collapse half-height and the blade looks short.

Static / ShapeBased show Radius, HalfHeight, and HalfSize from ShapeType. Socket Based also has MeshSocketLengthOffset to lengthen the capsule.

`FGCS_TraceHandle`

Runtime identity: TraceTag + Guid + SourceObject. The component uses it to start, stop, remove, and correlate hit callbacks. Weapons store handles in TraceHandles after activation; bullets store them on FGCS_BulletState.TraceHandles. Do not author the Guid. SourceObject is typically the weapon or bullet instance, so two swords on the same pawn can share a tag without colliding.

`FGCS_BulletDefinition`

A Data Table row (display name GCS Bullet Definition). UGCS_BulletSystemComponent uses the row to spawn a batch, build GEs, and handle penetration, chains, and emitters. The bullet Actor only presents and moves. The component applies authoritative GEs on hit. Predicted bullets never Apply a GE.

Field	Purpose	When to change	Misconfiguration
`BulletActorClass`	Soft-referenced bullet Actor. It must implement `IGCS_BulletInterface` and cannot be Abstract.	Spherical shots subclass `AGCS_SphereBulletInstance`.	A missing interface or an Abstract class never leaves the pool.
`Duration`	Lifetime in seconds. Default 3. `-1` means infinite.	Lasers, lingering orbs.	Infinite bullets need a reliable hit or cancel path, or the pool fills up.
`ExplosionDelay`	Delay after a terminal hit before settlement (effects, chains, impact presentation, end). `0` settles immediately.	Grenades that explode after landing.	This does not add radial damage. AoE still comes from a GE / EffectContainer or project logic.
`bCancellableByParent`	Cancel this bullet when the parent expires.	Child scatter should not outlive the parent.	Enabling it on a chain can tear down an explosion early.
`BulletCount`	Shots per launch. Minimum 1.	Shotguns.	A large count plus a shared hit list means later pellets cannot hit the same pawn.
`LaunchAngle` / `LaunchAngleInterval` / `LaunchElevationAngle`	Yaw, yaw interval, and pitch.	Fan scatter, arcs.	A zero interval stacks every shot.
`AttenuationRange`	Horizontal distance (cm) where gravity scale switches. Default 800.	Bolts that fly flat, then drop.	Read it with the two gravity scales; changing only this does not show an arc.
`GravityScaleInRange` / `GravityScaleOutRage`	Gravity scale inside / outside the range. The latter is a historical spelling; Details shows Gravity Scale Out Range.	No gravity up close, drop at range.	Searching Blueprint for “OutRange” misses the field. Use `GravityScaleOutRage`.
`InitialHitRadius` / `FinalHitRadius`	Initial / final hit radius. Final `-1` keeps the initial radius.	Growing or shrinking shots.	A zero radius almost never hits.
`InitialSpeed` / `MaxSpeed`	Initial and max speed. Both default 1500.	Accelerating or constant shots.	Max below Initial clamps the movement component immediately.
`AttackDefinition`	`FGCS_AttackDefinition` row used on hit.	One settlement per ammo type.	An empty handle means an authoritative hit has no GE.
`TraceDefinitions`	Hit-detection definitions. They override the instance class.	A larger sphere or a different channel than the Actor default.	An empty array falls back to the instance. One invalid entry means no detection.
`ProjectileFX` / `ProjectileFX_Cascade` / `ImpactFX` / `ImpactFX_Cascade`	Flight and impact Niagara / Cascade. `AGCS_BulletInstance` spawns them on activate and settlement.	Presentation only.	An unloaded soft reference skips FX and does not affect settlement.
`ProjectileFXModifer` / `ImpactFXModifer`	Niagara parameter overrides (Modifer is a historical spelling).	Recolor or resize one FX asset.	User parameter names must match the Niagara asset.
`ProjectileSFX` / `ImpactSFX` / `SpawnSFX`	Attached flight, impact, and spawn audio.	Presentation only.	`SpawnSFX` plays on every pool activation.
`bPenetrateCharacter` / `MaxPenetrationCount`	Whether the bullet penetrates pawns, and the max count. `0` means unlimited.	AP rounds.	Without penetrate, the first pawn ends the bullet.
`bPenetrateMap`	Whether the bullet penetrates world geometry.	Wall-piercing shots.	Still limited by the Trace channel.
`HitBulletDefinition`	Row spawned on hit or expiry. Cannot be this row.	Split on explode, residue on land.	Pointing at itself is rejected to stop recursion.
`HitChainType`	Chain spawn pose. Categories=`GGF.Combat.Bullet.ChainType`.	See native tags.	An empty tag uses Default: parent location and rotation.
`LaunchCondition`	When the chain fires. Categories=`GGF.Combat.Bullet.LaunchCond`.	See native tags.	Do not assume an empty tag always launches. Check the condition you authored.
`bUseSharedHitList`	Share hit history across the batch (keyed by EntryId). Default true. Pawn hits only.	Shotgun pellets should not all land on one person.	Off allows the same pawn to be hit by every shot in the batch.
`DamageHitDuration`	Per-pawn hit cooldown in seconds. `0` means no cooldown.	Continuous lasers.	`0` plus penetration can register the same target repeatedly.
`EmitterBulletDefinition`	Row emitted periodically when this bullet is an emitter.	An aerial circle dropping shots.	A child that is also an emitter can loop if you wire a cycle.
`EmitterSourceType`	How the emitter picks a spawn. Categories=`GGF.Combat.Bullet.EmitterType`.	See native tags.	`TargetingSystem` with no targeting component and no `EmitterTargetingPreset` never fires.
`EmitterTargetingPreset` / `EmitterSourceRadius`	Preset and radius (cm) used to pick a target.	Random around the shooter, or the nearest enemy.	Radius 0 means no random offset.
`EmitterInitialWaitTime` / `EmitterMinShootInterval` / `EmitterMaxShootInterval`	First wait and a randomized interval. Min is ClampMin=1.	Circle cadence.	Keep Min<=Max. Min>Max depends on scheduler details you should not rely on.
`NativeExtension` / `Extension`	Same C++ / Blueprint split as attack definitions.	Project fields on the ammo type.	Same pitfalls as attack-definition extensions.

FGCS_BulletSpawnParameters and FGCS_BulletState are runtime spawn parameters and instance state. Do not author them in the table. Chain and emitter bullets spawn on the authority only.

Native bullet tags

Namespaces live in GCS_GameplayTags.h. The GameplayTag values hang under GGF.Combat.Bullet.*.

`GCS_BulletLaunch` (`LaunchCondition`)

Tag	Value	Behavior
`Always`	`GGF.Combat.Bullet.LaunchCond.Always`	Spawn a follow-up whenever a hit happens.
`DidNotHitPawn`	`GGF.Combat.Bullet.LaunchCond.DidNotHitPawn`	Spawn only when the parent missed every pawn (explode on ground).
`HitPawn`	`GGF.Combat.Bullet.LaunchCond.HitPawn`	Spawn only when the parent hit a pawn (split on contact).

`GCS_BulletEmitter` (`EmitterSourceType`)

Tag	Value	Behavior
`Default`	`GGF.Combat.Bullet.EmitterType.Default`	Reuse the parent bullet transform.
`ShooterWithRandomRadius`	`GGF.Combat.Bullet.EmitterType.ShooterWithRandomRadius`	Offset randomly around the shooter by `EmitterSourceRadius`.
`TargetingSystem`	`GGF.Combat.Bullet.EmitterType.TargetingSystem`	Ask `UGCS_TargetingSystemComponent` or `EmitterTargetingPreset` for a target.

`GCS_BulletChain` (`HitChainType`)

Tag	Value	Behavior
`Default`	`GGF.Combat.Bullet.ChainType.Default`	Spawn at the parent location and rotation.
`FromHitResult`	`GGF.Combat.Bullet.ChainType.HitResult`	Spawn at the hit, aimed along TraceEnd−TraceStart.
`FromSourceRequest`	`GGF.Combat.Bullet.ChainType.SourceRequest`	Use the original attack-request transform.
`HitLocWithOwnerFwdDir`	`GGF.Combat.Bullet.ChainType.HitLocWithOwnerFwdDir`	Hit location + owner forward.
`ParentLocWithOwnerFwdDir`	`GGF.Combat.Bullet.ChainType.ParentLocWithOwnerFwdDir`	Parent location + owner forward.

Custom instances and interfaces are in Interfaces and custom instances.

Table of contents