skilld
All skills
quodsoler avatar

/ue-physics-collision

@f3742d7
by Quod Solerquodsoler/unreal-engine-skills352 stars
59

Use when setting up collision channels and profiles, running line/sweep/overlap queries, wiring hit and overlap events, or simulating rigid bodies in Unreal Engine C++. Also use when the user mentions 'collision channel', 'collision profile', 'LineTraceSingleByChannel', 'SweepSingleByChannel', 'OverlapMultiByObjectType', 'FHitResult', 'FCollisionQueryParams', 'FCollisionShape', 'OnComponentHit', 'OnComponentBeginOverlap', 'SetCollisionProfileName', 'SetSimulatePhysics', 'AddRadialImpulse', 'ragdoll', 'Chaos solver', 'ECC_GameTraceChannel1', or 'my overlap never fires'. For component attachment, see ue-actor-component-architecture; for capsule floor checks, see ue-character-movement.

Ask your Agent

Use this Skill: https://skilld.dev/gh/quodsoler/unreal-engine-skills/ue-physics-collision

This session only. Nothing lands on disk.

SKILL.md

≈178 tokens always: the name and description. ≈7.8k when used: this file. ≈8.6k more on demand in 2 files.

UE Physics & Collision

Target engine: UE 5.8. APIs below are verified against the 5.8 headers; older forms are listed under "Deprecated — do not use".

Collision and physics live in the Engine module (UPrimitiveComponent, UWorld queries, FHitResult, UCollisionProfile) and the PhysicsCore module (FCollisionShape, UPhysicalMaterial, FBodyInstanceCore, ECollisionTraceFlag, EPhysicalSurface). The simulator itself is Chaos (Chaos / ChaosSolverEngine modules); destruction adds GeometryCollectionEngine and FieldSystemEngine. Most gameplay code only needs "Engine" and "PhysicsCore" in Build.cs.

Context

Read .agents/ue-project-context.md if it exists (module names, conventions, enabled plugins, GAS/networking setup). Do not stop if it is missing.

Identify the area from the request and the codebase. Ask only when two plausible readings would produce different code.

Request is about… Go to
Channels, profiles, DefaultEngine.ini, responses Collision Channels and Profiles
Line traces, sweeps, overlap queries, async traces Trace Sweep and Overlap Queries
Reading what a query hit FHitResult
OnComponentHit, OnComponentBeginOverlap, wake/sleep Collision Events
Rigid bodies, impulses, forces, mass, damping, sleeping Physics Bodies and Forces
Joints, radial force fields, ragdolls Constraints Radial Force and Ragdolls
Friction, restitution, surface types Physical Materials
Solver settings, substepping, CVars, physics-thread ticks Chaos Solver and Async Physics
Replicated physics, resimulation, predictive interpolation Network Physics

Collision Channels and Profiles

ECollisionChannel (Engine/EngineTypes.h:1098) has 8 engine channels, 6 hidden engine slots and 50 game slots (64 total; ECC_GameTraceChannel50 at :1168):

ECC_WorldStatic, ECC_WorldDynamic, ECC_Pawn, ECC_PhysicsBody,
ECC_Vehicle, ECC_Destructible                 // object channels (what a component IS)
ECC_Visibility, ECC_Camera                    // trace channels (what a query LOOKS FOR)
ECC_GameTraceChannel1 ... ECC_GameTraceChannel50  // project slots, either kind
  • Object channel — every component has exactly one, set with SetCollisionObjectType. Matched by *ByObjectType queries.
  • Trace channel — never an object type; a query passes it to *ByChannel and each component's response to that channel decides block/overlap/ignore.
  • ECollisionResponse (Engine/EngineTypes.h:1346): ECR_Ignore, ECR_Overlap, ECR_Block.
  • ECollisionEnabled::Type (Engine/EngineTypes.h:1805): NoCollision, QueryOnly, PhysicsOnly, QueryAndPhysics, ProbeOnly, QueryAndProbe.
#include "Components/PrimitiveComponent.h"

MyMesh->SetCollisionProfileName(TEXT("BlockAllDynamic"));   // preferred: one call sets everything
MyMesh->SetCollisionEnabled(ECollisionEnabled::QueryAndPhysics);
MyMesh->SetCollisionObjectType(ECC_PhysicsBody);
MyMesh->SetCollisionResponseToAllChannels(ECR_Block);
MyMesh->SetCollisionResponseToChannel(ECC_Pawn, ECR_Overlap);
MyMesh->SetCollisionResponseToChannel(ECC_Camera, ECR_Ignore);

FCollisionResponseContainer Responses(ECR_Ignore);
Responses.SetResponse(ECC_Visibility, ECR_Block);
MyMesh->SetCollisionResponseToChannels(Responses);

SetCollisionProfileName overwrites every manual response, so apply the profile first and the per-channel overrides after.

Engine profiles shipped in Config/BaseEngine.ini under [/Script/Engine.CollisionProfile]: NoCollision, BlockAll, OverlapAll, BlockAllDynamic, OverlapAllDynamic, IgnoreOnlyPawn, OverlapOnlyPawn, Pawn, Spectator, CharacterMesh, PhysicsActor, Destructible, InvisibleWall, InvisibleWallDynamic, Trigger, Ragdoll, Vehicle, UI, WaterBodyCollision.

Custom channels and profiles are config-only — there is no runtime API to create one:

[/Script/Engine.CollisionProfile]
+DefaultChannelResponses=(Channel=ECC_GameTraceChannel1,DefaultResponse=ECR_Block,bTraceType=True,bStaticObject=False,Name="Weapon")
+DefaultChannelResponses=(Channel=ECC_GameTraceChannel2,DefaultResponse=ECR_Block,bTraceType=False,bStaticObject=False,Name="Interactable")
+Profiles=(Name="MyInteractable",CollisionEnabled=QueryAndPhysics,ObjectTypeName="Interactable",CustomResponses=((Channel="Weapon",Response=ECR_Ignore),(Channel="Visibility",Response=ECR_Block)),HelpMessage="Interactable props")
+EditProfiles=(Name="Pawn",CustomResponses=((Channel="Weapon",Response=ECR_Block)))

bTraceType=True declares a trace channel, False an object channel. +Profiles= adds or replaces a whole profile; +EditProfiles= only patches responses on an existing one (Engine/CollisionProfile.h:160-190). UCollisionProfile::Get() reads the table and UCollisionProfile::LoadProfileConfig(bool bForceInit) (Engine/CollisionProfile.h:237) re-reads it after a config change.

See collision-channel-setup.md for full profile sets, the ini reference and a debugging checklist.

Trace Sweep and Overlap Queries

All world queries are const members of UWorld (Engine/World.h:2128-2441). Three families, each in Test / Single / Multi form:

Suffix Selects by Extra parameter
ByChannel the querier's trace channel vs each component's response ECollisionChannel TraceChannel, optional FCollisionResponseParams
ByObjectType the target component's object channel const FCollisionObjectQueryParams&
ByProfile the channel and responses stored in a named profile FName ProfileName 
#include "Engine/World.h"
#include "Engine/HitResult.h"
#include "CollisionQueryParams.h"
#include "CollisionShape.h"

FCollisionQueryParams Params(TEXT("MyWeaponTrace"), /*bTraceComplex=*/false, GetOwner());
Params.bReturnPhysicalMaterial = true;   // fills Hit.PhysMaterial
Params.bReturnFaceIndex        = false;  // fills Hit.FaceIndex; expensive
Params.bIgnoreTouches          = true;   // discard ECR_Overlap results (bIgnoreBlocks is the inverse)
Params.bFindInitialOverlaps    = true;   // report shapes already overlapping at Start
Params.MobilityType            = EQueryMobilityType::Any;  // Any | Static | Dynamic
Params.AddIgnoredActor(GetOwner());
Params.AddIgnoredComponent(MyMesh.Get());   // .Get(): a TObjectPtr member is ambiguous (CollisionQueryParams.h:267-269)

FHitResult Hit;
GetWorld()->LineTraceSingleByChannel(Hit, Start, End, ECC_Visibility, Params);

TArray<FHitResult> Hits;
GetWorld()->LineTraceMultiByChannel(Hits, Start, End, ECC_GameTraceChannel1, Params);

FCollisionObjectQueryParams ObjParams(ECC_Pawn);
ObjParams.AddObjectTypesToQuery(ECC_PhysicsBody);
GetWorld()->LineTraceSingleByObjectType(Hit, Start, End, ObjParams, Params);

GetWorld()->LineTraceSingleByProfile(Hit, Start, End, TEXT("BlockAll"), Params);

const bool bAnythingThere = GetWorld()->LineTraceTestByChannel(Start, End, ECC_Visibility, Params);

TraceTag is the first constructor argument; it also drives the TraceTagAll / named-tag debug drawing in the console.

Sweeps take a rotation and an FCollisionShape (PhysicsCore/Public/CollisionShape.h:284-316):

const FCollisionShape Sphere  = FCollisionShape::MakeSphere(30.f);                  // radius
const FCollisionShape Box     = FCollisionShape::MakeBox(FVector(50.f, 30.f, 80.f));// half-extents
const FCollisionShape Capsule = FCollisionShape::MakeCapsule(34.f, 88.f);           // radius, half-height

GetWorld()->SweepSingleByChannel(Hit, Start, End, FQuat::Identity, ECC_Pawn, Capsule, Params);
GetWorld()->SweepMultiByChannel(Hits, Start, End, FQuat::Identity, ECC_Pawn, Sphere, Params);
GetWorld()->SweepSingleByObjectType(Hit, Start, End, FQuat::Identity, ObjParams, Box, Params);
GetWorld()->SweepSingleByProfile(Hit, Start, End, FQuat::Identity, TEXT("Pawn"), Capsule, Params);

GetCapsuleHalfHeight() includes the end radius; GetCapsuleAxisHalfLength() is the shaft only.

Overlaps are stationary shape tests returning FOverlapResult (Engine/OverlapResult.h:12):

#include "Engine/OverlapResult.h"

TArray<FOverlapResult> Overlaps;
GetWorld()->OverlapMultiByObjectType(Overlaps, Center, FQuat::Identity,
    FCollisionObjectQueryParams(ECC_Pawn), FCollisionShape::MakeSphere(500.f), Params);
GetWorld()->OverlapMultiByChannel(Overlaps, Center, FQuat::Identity, ECC_Pawn,
    FCollisionShape::MakeSphere(500.f), Params);

const bool bBlocked = GetWorld()->OverlapAnyTestByChannel(Center, FQuat::Identity,
    ECC_WorldStatic, FCollisionShape::MakeBox(FVector(40.f)), Params);

for (const FOverlapResult& Result : Overlaps)
{
    AActor* Actor = Result.GetActor();
    UPrimitiveComponent* Comp = Result.GetComponent();
}

OverlapAnyTestByChannel stops at the first block or touch; OverlapBlockingTestByChannel ignores touches. When the query is "what is my own component already touching", use UPrimitiveComponent::GetOverlappingActors or ComponentOverlapComponent instead of a world query.

Async traces queue this frame and are readable next frame (Engine/World.h:2522, WorldCollision.h:148):

#include "WorldCollision.h"

// EAsyncTraceType: Test | Single | Multi
FTraceHandle Handle = GetWorld()->AsyncLineTraceByChannel(
    EAsyncTraceType::Single, Start, End, ECC_Visibility, Params);

FTraceDatum Datum;
if (GetWorld()->QueryTraceData(Handle, Datum) && Datum.OutHits.Num() > 0)
{
    const FHitResult& First = Datum.OutHits[0];
}

Passing a FTraceDelegate* (DECLARE_DELEGATE_TwoParams(FTraceDelegate, const FTraceHandle&, FTraceDatum&)) instead calls you back when the batch completes.

See trace-patterns.md for hitscan, melee sweep, interaction, ground check, AoE, line-of-sight and async sensor patterns, plus the Blueprint-layer UKismetSystemLibrary wrappers and performance guidance.

FHitResult

Engine/HitResult.h. Actor is no longer a member — the actor is reached through an accessor.

Hit.bBlockingHit;        // :107  false for a touch-only result
Hit.bStartPenetrating;   // :116  query began already overlapping; PenetrationDepth :91
Hit.Time;                // :33   0..1 along Start->End;  Distance :37 in cm
Hit.Location;            // :45   where the swept shape's origin ended up
Hit.ImpactPoint;         // :53   surface contact point
Hit.Normal;              // :61   normal opposing movement at Location
Hit.ImpactNormal;        // :69   geometric surface normal at ImpactPoint
Hit.TraceStart;          // :76;  TraceEnd :83
Hit.Item;                // :99   instance index (ISM/HISM); ElementIndex :103 shape index
Hit.FaceIndex;           // :26   needs Params.bReturnFaceIndex
Hit.BoneName;            // :141  bone hit;  MyBoneName :145 our own bone
Hit.PhysMaterial;        // :123  TWeakObjectPtr, needs bReturnPhysicalMaterial

AActor* HitActor = Hit.GetActor();                 // :211
UPrimitiveComponent* HitComp = Hit.GetComponent(); // :227
FActorInstanceHandle Handle = Hit.GetHitObjectHandle(); // :216, lightweight instances

For a Multi query only the last element can be a blocking hit; every earlier element is a touch.

Collision Events

Delegates are sparse dynamic multicast, so handlers must be UFUNCTION()-declared in the header with exactly the delegate's parameter list, or AddDynamic fails to bind at runtime. Signatures from Components/PrimitiveComponent.h:274-282 and GameFramework/Actor.h:194-196:

Delegate Parameters
FComponentHitSignature UPrimitiveComponent* HitComponent, AActor* OtherActor, UPrimitiveComponent* OtherComp, FVector NormalImpulse, const FHitResult& Hit
FComponentBeginOverlapSignature UPrimitiveComponent* OverlappedComponent, AActor* OtherActor, UPrimitiveComponent* OtherComp, int32 OtherBodyIndex, bool bFromSweep, const FHitResult& SweepResult
FComponentEndOverlapSignature UPrimitiveComponent* OverlappedComponent, AActor* OtherActor, UPrimitiveComponent* OtherComp, int32 OtherBodyIndex
FComponentWakeSignature / FComponentSleepSignature UPrimitiveComponent* WakingComponent (SleepingComponent), FName BoneName
FActorBeginOverlapSignature / FActorEndOverlapSignature AActor* OverlappedActor, AActor* OtherActor
FActorHitSignature AActor* SelfActor, AActor* OtherActor, FVector NormalImpulse, const FHitResult& Hit 
// MyPickup.h
#pragma once

#include "CoreMinimal.h"
#include "GameFramework/Actor.h"
#include "Engine/HitResult.h"
#include "MyPickup.generated.h"

UCLASS()
class MYGAME_API AMyPickup : public AActor
{
	GENERATED_BODY()

public:
	AMyPickup();

protected:
	virtual void BeginPlay() override;

	UPROPERTY(VisibleAnywhere, Category = "Collision")
	TObjectPtr<class USphereComponent> Trigger;

	UPROPERTY(VisibleAnywhere, Category = "Collision")
	TObjectPtr<class UStaticMeshComponent> Mesh;

	UFUNCTION()
	void OnBeginOverlap(UPrimitiveComponent* OverlappedComponent, AActor* OtherActor,
		UPrimitiveComponent* OtherComp, int32 OtherBodyIndex, bool bFromSweep, const FHitResult& SweepResult);

	UFUNCTION()
	void OnEndOverlap(UPrimitiveComponent* OverlappedComponent, AActor* OtherActor,
		UPrimitiveComponent* OtherComp, int32 OtherBodyIndex);

	UFUNCTION()
	void OnHit(UPrimitiveComponent* HitComponent, AActor* OtherActor,
		UPrimitiveComponent* OtherComp, FVector NormalImpulse, const FHitResult& Hit);
};
// MyPickup.cpp
#include "MyPickup.h"
#include "Components/SphereComponent.h"
#include "Components/StaticMeshComponent.h"

AMyPickup::AMyPickup()
{
	Trigger = CreateDefaultSubobject<USphereComponent>(TEXT("Trigger"));
	SetRootComponent(Trigger);
	Trigger->SetSphereRadius(120.f);
	Trigger->SetCollisionProfileName(TEXT("OverlapAllDynamic"));
	Trigger->SetGenerateOverlapEvents(true);

	Mesh = CreateDefaultSubobject<UStaticMeshComponent>(TEXT("Mesh"));
	Mesh->SetupAttachment(Trigger);
	Mesh->SetCollisionProfileName(TEXT("PhysicsActor"));
	Mesh->SetSimulatePhysics(true);
	Mesh->SetNotifyRigidBodyCollision(true);   // "Simulation Generates Hit Events"
}

void AMyPickup::BeginPlay()
{
	Super::BeginPlay();

	Trigger->OnComponentBeginOverlap.AddDynamic(this, &AMyPickup::OnBeginOverlap);
	Trigger->OnComponentEndOverlap.AddDynamic(this, &AMyPickup::OnEndOverlap);
	Mesh->OnComponentHit.AddDynamic(this, &AMyPickup::OnHit);
}

void AMyPickup::OnBeginOverlap(UPrimitiveComponent* OverlappedComponent, AActor* OtherActor,
	UPrimitiveComponent* OtherComp, int32 OtherBodyIndex, bool bFromSweep, const FHitResult& SweepResult)
{
	if (OtherActor && OtherActor != this)
	{
		Destroy();
	}
}

void AMyPickup::OnEndOverlap(UPrimitiveComponent* OverlappedComponent, AActor* OtherActor,
	UPrimitiveComponent* OtherComp, int32 OtherBodyIndex)
{
}

void AMyPickup::OnHit(UPrimitiveComponent* HitComponent, AActor* OtherActor,
	UPrimitiveComponent* OtherComp, FVector NormalImpulse, const FHitResult& Hit)
{
	const float ImpactStrength = NormalImpulse.Size();
}

Requirements: overlaps need ECR_Overlap on at least one side, a non-ECR_Ignore pair, and SetGenerateOverlapEvents(true) on both components (bGenerateOverlapEvents is private — Components/PrimitiveComponent.h:429). Simulation hits need ECR_Block on both, QueryAndPhysics or PhysicsOnly, and SetNotifyRigidBodyCollision(true) on the simulating component; a swept move (SetActorLocation(..., true), movement components) fires OnComponentHit on any blocking hit without that flag (PrimitiveComponent.cpp:3540-3550). OnComponentWake / OnComponentSleep need bGenerateWakeEvents on the body (PhysicsCore/Public/BodyInstanceCore.h:59).

Physics Bodies and Forces

MyMesh->SetSimulatePhysics(true);                          // PrimitiveComponent.h:1661
MyMesh->SetEnableGravity(true);                            // :2801
MyMesh->SetMassOverrideInKg(NAME_None, 50.f, true);        // :2857;  GetMass() :2861
MyMesh->SetLinearDamping(0.1f);                            // :2825;  SetAngularDamping :2833
MyMesh->SetUseCCD(true);                                   // :2894 swept collision for fast bodies
MyMesh->SetConstraintMode(EDOFMode::XYPlane);              // :1682 lock to a plane
const bool bSimulating = MyMesh->IsSimulatingPhysics();    // :2644

MyMesh->AddImpulse(FVector(0.f, 0.f, 1000.f), NAME_None, /*bVelChange=*/false);  // :1692
MyMesh->AddImpulseAtLocation(FVector(500.f, 0.f, 0.f), Hit.ImpactPoint);         // :1725 adds spin
MyMesh->AddRadialImpulse(Center, 500.f, 2000.f, RIF_Linear, /*bVelChange=*/false); // :1748
MyMesh->AddForce(FVector(0.f, 0.f, 9800.f), NAME_None, /*bAccelChange=*/false);  // :1759 every tick
MyMesh->AddRadialForce(Center, 500.f, 3000.f, RIF_Constant, false);              // :1793

MyMesh->SetPhysicsLinearVelocity(FVector(0.f, 0.f, 300.f));  // :1825 teleports velocity; use sparingly
const FVector Velocity = MyMesh->GetPhysicsLinearVelocity(); // :1832
MyMesh->WakeRigidBody();                                     // :1938;  PutRigidBodyToSleep() :1945

bVelChange=true / bAccelChange=true ignore mass. ERadialImpulseFalloff is RIF_Constant or RIF_Linear (PhysicsCore/Public/Chaos/ChaosEngineInterface.h:90).

MyMesh->GetBodyInstance() reaches the body. FBodyInstanceCore flags (PhysicsCore/Public/BodyInstanceCore.h): bSimulatePhysics (:30), bOverrideMass (:35), bEnableGravity (:39), bUpdateKinematicFromSimulation (:43), bAutoWeld (:51), bStartAwake (:55), bGenerateWakeEvents (:59). FBodyInstance adds bUseCCD (:418), bNotifyRigidBodyCollision (:440), LinearDamping (:629), MassScale (:645), InertiaTensorScale (:653), SleepFamily (:410) and CustomSleepThresholdMultiplier (:696). ESleepFamily (Chaos/ChaosEngineInterface.h:101) is Normal, Sensitive or Custom; only Custom reads the multiplier.

Collision complexity comes from ECollisionTraceFlag (PhysicsCore/Public/BodySetupEnums.h:13-20): CTF_UseDefault, CTF_UseSimpleAndComplex, CTF_UseSimpleAsComplex, CTF_UseComplexAsSimple. Complex-as-simple bodies cannot simulate.

Constraints Radial Force and Ragdolls

UPhysicsConstraintComponent (PhysicsEngine/PhysicsConstraintComponent.h:24) wraps an FConstraintInstance (:73) — the same struct a Physics Asset stores per joint.

#include "PhysicsEngine/PhysicsConstraintComponent.h"

UPhysicsConstraintComponent* Joint = NewObject<UPhysicsConstraintComponent>(this);
Joint->SetupAttachment(RootComponent);
Joint->RegisterComponent();
Joint->SetConstrainedComponents(MeshA, NAME_None, MeshB, NAME_None);  // :134
Joint->SetLinearXLimit(ELinearConstraintMotion::LCM_Locked, 0.f);     // :270
Joint->SetAngularSwing1Limit(EAngularConstraintMotion::ACM_Limited, 45.f); // :291
Joint->SetAngularTwistLimit(EAngularConstraintMotion::ACM_Free, 0.f);      // :305
Joint->SetAngularVelocityDriveTwistAndSwing(true, false);             // :199
Joint->SetAngularDriveParams(500.f, 50.f, 0.f);                       // :262
Joint->SetDisableCollision(true);                                     // :374
Joint->BreakConstraint();                                             // :142

Motion enums are ELinearConstraintMotion (LCM_Free, LCM_Limited, LCM_Locked) and EAngularConstraintMotion (ACM_Free, ACM_Limited, ACM_Locked). Editor presets are only combinations of these: Fixed locks all six, Hinge frees one angular axis, Prismatic frees one linear axis, Ball-and-Socket frees all angular. URadialForceComponent (PhysicsEngine/RadialForceComponent.h:16) is the drop-in explosion/vacuum component: Radius, Falloff, ImpulseStrength, bImpulseVelChange, bIgnoreOwningActor, ForceStrength, then FireImpulse() (:50) for a one-shot and AddObjectTypeToAffect(EObjectTypeQuery) (:54) to filter targets.

Ragdolls run through the skeletal mesh's Physics Asset (UPhysicsAsset::SkeletalBodySetups, ConstraintSetup — PhysicsEngine/PhysicsAsset.h:213-220):

GetMesh()->SetCollisionProfileName(TEXT("Ragdoll"));
GetMesh()->SetAllBodiesSimulatePhysics(true);                  // SkeletalMeshComponent.h:2344
GetMesh()->SetAllBodiesBelowSimulatePhysics(TEXT("spine_01"), true); // :2376 partial ragdoll
GetMesh()->SetPhysicsBlendWeight(1.f);                         // :2353 blend animation <-> sim

Physical Materials

PhysicsCore/Public/PhysicalMaterials/PhysicalMaterial.h:103.

float Friction;                 // :115 kinetic;  StaticFriction :119
float Restitution;              // :131 0 dead, 1 elastic
float Density;                  // :147 g/cm^3, drives mass from shape volume
float SleepLinearVelocityThreshold;   // :151;  SleepAngularVelocityThreshold :155
int32 SleepCounterThreshold;          // :159;  RaiseMassToPower :167
TEnumAsByte<EPhysicalSurface> SurfaceType;  // :181
// FrictionCombineMode / RestitutionCombineMode are EFrictionCombineMode::Type and only
// apply when bOverrideFrictionCombineMode / bOverrideRestitutionCombineMode is set.

MyMesh->SetPhysMaterialOverride(MyPhysMaterial);   // PrimitiveComponent.h:3008

if (UPhysicalMaterial* PhysMat = Hit.PhysMaterial.Get())   // needs bReturnPhysicalMaterial
{
	const EPhysicalSurface Surface = UPhysicalMaterial::DetermineSurfaceType(PhysMat); // :242
}

EPhysicalSurface (PhysicsCore/Public/Chaos/ChaosEngineInterface.h:20) is SurfaceType_Default plus SurfaceType1..SurfaceType62, named in Project Settings > Physics.

Chaos Solver and Async Physics

Chaos is the only physics backend in 5.8. FChaosScene (PhysicsCore/Public/Chaos/ChaosScene.h:84) owns the solver and is driven by SetUpForFrame (:141), StartFrame (:140), EndFrame (:142); WaitPhysScenes (:122) blocks for results.

Project settings live on UPhysicsSettings / UPhysicsSettingsCore under [/Script/Engine.PhysicsSettings]:

Setting Header Meaning
DefaultGravityZ PhysicsSettingsCore.h:25 world gravity, -980 default
BounceThresholdVelocity :79 below this, restitution is skipped
MaxDepenetrationVelocity :95 caps push-out speed; 0 = unlimited
bSimulateSkeletalMeshOnDedicatedServer :114 off saves ragdoll cost on servers
DefaultShapeComplexity :119 project-wide ECollisionTraceFlag
SolverOptions :123 FChaosSolverConfiguration
bSubstepping / MaxSubstepDeltaTime / MaxSubsteps PhysicsSettings.h:325,341,345 fixes tunnelling and jitter for small fast bodies
bTickPhysicsAsync / AsyncFixedTimeStepSize :333,337 fixed-rate physics thread
PhysicsPrediction :267 FPhysicsPredictionSettings, gates resimulation

FChaosSolverConfiguration (Chaos/Public/ChaosSolverConfiguration.h:51) exposes PositionIterations, VelocityIterations, ProjectionIterations, CollisionMarginFraction, CollisionCullDistance, CollisionMaxPushOutVelocity.

Diagnostic CVars that exist in 5.8:

p.Chaos.DebugDraw.Enabled 1                              ChaosDebugDrawComponent.cpp:29
p.Chaos.DebugDraw.Radius 3000 / p.Chaos.DebugDraw.MaxLines 20000   capture limits
p.Chaos.Solver.Iterations.Position|Velocity|Projection   PBDRigidsSolver.cpp:337,340,343
p.Chaos.Solver.Deterministic :346   p.Chaos.Solver.UseCCD :406 (global CCD switch)
p.Chaos.DedicatedThreadEnabled                           ChaosSolversModule.cpp:23

With bTickPhysicsAsync on, gameplay code that must run in lockstep with the solver uses the async tick instead of Tick: set bAsyncPhysicsTickEnabled in an actor constructor (protected, GameFramework/Actor.h:699) or call SetAsyncPhysicsTickEnabled(true) on a component (ActorComponent.h:1435; the component field at Components/ActorComponent.h:407 is private) and override AsyncPhysicsTickActor(float DeltaTime, float SimTime) (Actor.h:2930) or AsyncPhysicsTickComponent(float DeltaTime, float SimTime) (ActorComponent.h:985). Feed inputs across the boundary with UAsyncPhysicsInputComponent (Engine/Public/Physics/AsyncPhysicsInputComponent.h:10).

Below FBodyInstance, bodies are addressed as Chaos::FPhysicsObject. UPrimitiveComponent implements IPhysicsComponent and exposes GetPhysicsObjectById, GetPhysicsObjectByName and GetAllPhysicsObjects (Components/PrimitiveComponent.h:3248-3250); FHitResult::PhysicsObject and PhysicsObjectOwner (Engine/HitResult.h:134-137) identify what a query hit when no actor owns it.

Network Physics

Physics simulates on the server. Hit and overlap events fire wherever the simulation runs, so clients see nothing unless the actor also simulates locally or you replicate the result.

  • AActor::SetPhysicsReplicationMode(EPhysicsReplicationMode) / GetPhysicsReplicationMode() (GameFramework/Actor.h:924,928) select Default, PredictiveInterpolation, Resimulation or None (Engine/EngineTypes.h:3614).
  • Resimulation requires Project Settings > Physics > Physics Prediction (UPhysicsSettings::PhysicsPrediction); PredictiveInterpolation runs without it but works best with it enabled (Engine/EngineTypes.h:3619-3629).
  • UNetworkPhysicsComponent (Engine/Public/Physics/NetworkPhysicsComponent.h:2290) records input and state history on the physics thread so the client can resimulate from a corrected past state.
  • Transform sync for non-predicted actors still rides on bReplicateMovement / FRepMovement.

Replication rules, conditions and RPC design belong to ue-networking-replication; this skill only covers which physics mode to pick.

Module Dependencies

// MyGame.Build.cs
PublicDependencyModuleNames.AddRange(new string[] {
	"Core", "CoreUObject",
	"Engine",       // UPrimitiveComponent, FHitResult, UWorld queries, UCollisionProfile
	"PhysicsCore",  // FCollisionShape, UPhysicalMaterial, FBodyInstanceCore, ECollisionTraceFlag
});
// Add "Chaos" only for Chaos:: types; "GeometryCollectionEngine"/"FieldSystemEngine" for destruction.

Deprecated — do not use

Do not emit Use in 5.8 Source
Hit.Actor Hit.GetActor() / Hit.GetHitObjectHandle() no Actor member; HitObjectHandle in Engine/HitResult.h:127
Comp->bGenerateOverlapEvents = true Comp->SetGenerateOverlapEvents(true) private field, Components/PrimitiveComponent.h:429
Params.GetIgnoredActors() Params.GetIgnoredSourceObjects() UE_DEPRECATED(5.5) in CollisionQueryParams.h:145
Params.ClearIgnoredActors() Params.ClearIgnoredSourceObjects() UE_DEPRECATED(5.5) in CollisionQueryParams.h:180
ObjParams.ObjectTypesToQuery GetObjectTypesToQuery() / SetObjectTypesToQuery() UE_DEPRECATED(5.8) in CollisionQueryParams.h:490
GetAllObjectsQueryFlag(), GetQueryBitfield() the ...64() forms UE_DEPRECATED(5.8) in CollisionQueryParams.h:368,571
Constraint->SetAngularVelocityDrive(bSwing, bTwist) SetAngularVelocityDriveTwistAndSwing(bTwist, bSwing) — argument order is swapped DeprecatedFunction meta, PhysicsEngine/PhysicsConstraintComponent.h:187-199
PhysMat->DestructibleDamageThresholdScale Geometry Collection damage thresholds renamed _DEPRECATED, UE_DEPRECATED(5.3) in PhysicalMaterials/PhysicalMaterial.h:170
FChaosQueryFilterData / FQueryFilterData ChaosInterface::FSceneQueryCommonParams UE_DEPRECATED(5.8) in PhysicsInterfaceTypesCore.h:410 / ChaosInterfaceWrapperCore.h:35
ICollisionQueryFilterCallbackBase ICollisionQueryFilterCallback UE_DEPRECATED(5.8) in CollisionQueryFilterCallbackCore.h:63
GetQueryFilterData() / GetSimulationFilterData() GetCombinedShapeFilterData() UE_DEPRECATED(5.7) in ChaosInterfaceWrapperCore.h:98
BodySetup->ChaosTriMeshes BodySetup->TriMeshGeometries (:278) UE_DEPRECATED(5.4) in PhysicsEngine/BodySetup.h:308
PhysX types (PxRigidActor, PxScene, PhysX module) Chaos equivalents no PhysX module ships in 5.8

Common Mistakes

UFUNCTION() on an out-of-line definition: UHT only reads headers, so a UFUNCTION() written above void AMyPickup::OnHit in the .cpp generates no reflection data and AddDynamic silently binds nothing. Declare the handler inside the class body with UFUNCTION(); define it plainly in the .cpp.

Handler signature drift: AddDynamic matches the delegate exactly. A missing int32 OtherBodyIndex or a FHitResult taken by value will not compile, and a stale copy of an old signature will not bind.

Overlap events set on one side only: both components need a non-ignore response and SetGenerateOverlapEvents(true). Setting it only on the trigger is the most common "my overlap never fires".

Hit events without SetNotifyRigidBodyCollision(true): for simulated bodies ECR_Block alone is not enough; OnComponentHit stays silent (swept moves dispatch regardless).

Profile applied after manual responses: SetCollisionProfileName resets the whole response container. Order is profile first, overrides second.

Mixing channel families: a component whose object type is ECC_Pawn is invisible to LineTraceSingleByObjectType querying ECC_GameTraceChannel3, and a trace channel can never be an object type. bTraceType in the ini decides which one a slot is.

bTraceComplex = true by default: per-triangle queries are several times the cost of the simple hull and skip simple-only bodies. Enable it only where triangle accuracy matters.

SetPhysicsLinearVelocity as a movement API: it overwrites the solver's velocity every call and fights contacts. Use AddForce / AddImpulse unless you are deliberately teleporting velocity.

Fast bodies tunnelling: enable SetUseCCD(true) on the body, or substepping project-wide, rather than shrinking the timestep globally. For traces every tick on many actors, use AsyncLineTraceByChannel or throttle to 5–10 Hz with a timer.

Related Skills

  • ue-actor-component-architecture — component creation, attachment, registration and lifecycle for shape and mesh components
  • ue-character-movement — UCharacterMovementComponent floor checks, capsule sweeps and step-up logic
  • ue-networking-replication — DOREPLIFETIME, replication conditions and RPCs for anything you send about a physics result
  • ue-ai-navigation — perception traces, navmesh queries and UNavigationSystemV1
  • ue-procedural-generation — collision setup on runtime-generated meshes
  • Also relevant: ue-testing-debugging, ue-gameplay-framework, ue-mover

Source: SKILL.md on GitHub

Third-party checks

No alerts2d5 checks · Risk SAFE
  • Gen Agent Trust Hub2d

    This skill provides technical documentation and C++ code references for Unreal Engine 5.8 physics and collision systems. It covers collision channels, world queries, physics bodies, and network physics. No security risks or malicious patterns were detected.

  • Socket2d

    No alerts

  • Snyk2d

    Risk: LOW · No issues

  • Runlayer6mo

    3 files scanned · No issues

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Provenance

Signed by skilld at f3742d7. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 2 days ago.

Activeupdated 3 days ago

Capability

metadata
{
  "version": "2.0.0",
  "engine": "5.8"
}

README badge

README badge for quodsoler/unreal-engine-skills/ue-physics-collision