Use when implementing collision detection, trace queries, physics simulation, or physical interactions in Unreal Engine. Triggers on: 'collision', 'trace', 'LineTrace', 'line trace', 'overlap', 'physics', 'hit result', 'sweep', 'collision channel', 'physics body', 'Chaos', 'raytrace', 'OnHit', 'OnBeginOverlap'. See related skills for component architecture and AI navigation.
Instrucciones de origen · Vista previa de solo lectura
name
ue-physics-collision
description
Use when implementing collision detection, trace queries, physics simulation, or physical interactions in Unreal Engine. Triggers on: 'collision', 'trace', 'LineTrace', 'line trace', 'overlap', 'physics', 'hit result', 'sweep', 'collision channel', 'physics body', 'Chaos', 'raytrace', 'OnHit', 'OnBeginOverlap'. See related skills for component architecture and AI navigation.
metadata
{"version":"1.0.0"}
UE Physics & Collision
You are an expert in Unreal Engine's physics and collision systems, including collision channels, trace queries, collision events, physics bodies, and the Chaos physics engine.
Step 1: Read Project Context
Read .agents/ue-project-context.md to confirm:
UE version (Chaos is the default physics backend from UE 5.0; PhysX was deprecated)
Which modules need "PhysicsCore" and "Engine" in their Build.cs
Whether the project uses skeletal meshes with physics assets, or primarily static mesh collision
Dedicated server targets (affects whether physics simulation should run server-side)
Step 2: Identify the Need
Ask which area applies if not stated:
Collision setup — channels, profiles, responses on components
Trace queries — line traces, sweeps, overlap queries for gameplay logic
MyMesh->SetCollisionProfileName(TEXT("BlockAll")); // preferred — sets all at once
MyMesh->SetCollisionEnabled(ECollisionEnabled::QueryAndPhysics);
// ECollisionEnabled: NoCollision | QueryOnly | PhysicsOnly | QueryAndPhysics
MyMesh->SetCollisionObjectType(ECC_PhysicsBody);
MyMesh->SetCollisionResponseToAllChannels(ECR_Block);
MyMesh->SetCollisionResponseToChannel(ECC_Pawn, ECR_Overlap);
MyMesh->SetCollisionResponseToChannel(ECC_Camera, ECR_Ignore);
Object Type Channels vs Trace Channels
Object type channels describe what an actor IS (Pawn, WorldDynamic, Vehicle). Every component has exactly one object type. Trace channels are used for queries — they define what a trace is LOOKING FOR (Visibility, Camera, Weapon). This distinction determines which query function to use: ByObjectType matches the target's object type channel; ByChannel uses the querier's trace channel and checks responses. Most gameplay traces use trace channels (ECC_Visibility, custom Weapon); overlap queries for "find all pawns" use object type (ECC_Pawn).
TArray<FOverlapResult> Overlaps;
GetWorld()->OverlapMultiByObjectType(Overlaps, Center, FQuat::Identity,
FCollisionObjectQueryParams(ECC_Pawn), FCollisionShape::MakeSphere(500.f), Params);
for (const FOverlapResult& R : Overlaps) { AActor* A = R.GetActor(); }
// By trace channel (uses channel responses, not object type matching):GetWorld()->OverlapMultiByChannel(
Overlaps, Center, FQuat::Identity, ECC_Pawn,
FCollisionShape::MakeSphere(Radius), QueryParams);
FHitResult — Key Fields
Hit.bBlockingHit; // true if blocking
Hit.ImpactPoint; // world space contact point
Hit.ImpactNormal; // surface normal
Hit.Distance; // from Start to impact
Hit.BoneName; // skeletal mesh bone
Hit.GetActor();
Hit.GetComponent();
// Physical material (requires bReturnPhysicalMaterial=true):if (UPhysicalMaterial* M = Hit.PhysMaterial.Get())
EPhysicalSurface S = UPhysicalMaterial::DetermineSurfaceType(M);
DrawDebugLine / DrawDebugSphere are from DrawDebugHelpers.h. Wrap in ENABLE_DRAW_DEBUG so they compile out in shipping builds. The bool param is bPersistentLines; the float param is LifeTime in seconds.
See references/trace-patterns.md for full gameplay patterns (hitscan, melee sweep, AoE, ground detection, async sensors).
Requirements: Hit: QueryAndPhysics, ECR_Block on both, SetNotifyRigidBodyCollision(true). Overlap: ECR_Overlap on both, SetGenerateOverlapEvents(true) on both.
Named constraint presets (set via ConstraintProfile or editor Preset dropdown):
Preset
Angular Limits
Linear Limits
Fixed
All locked
All locked
Hinge
One axis free
All locked
Prismatic
All locked
One axis free
Ball-and-Socket
All free
All locked
Physical Materials (UPhysicalMaterial)
From PhysicalMaterials/PhysicalMaterial.h:
float Friction; // kinetic (0 = frictionless)float StaticFriction; // before sliding startsfloat Restitution; // 0 (no bounce) to 1 (elastic)float Density; // g/cm^3 — used to compute mass from shape volume
EPhysicalSurface SurfaceType; // SurfaceType_Default, SurfaceType1..SurfaceType62// FrictionCombineMode / RestitutionCombineMode: Average, Min, Multiply, Max// Runtime override
MyMesh->SetPhysMaterialOverride(MyPhysMaterial);
// Detect surface from trace (requires bReturnPhysicalMaterial=true)if (UPhysicalMaterial* M = Hit.PhysMaterial.Get())
{
EPhysicalSurface S = UPhysicalMaterial::DetermineSurfaceType(M);
switch (S) { case SurfaceType1: /* Metal */break; }
}
Chaos Physics (UE5)
UE5 uses Chaos by default (PhysX removed). Key architecture:
FChaosScene (ChaosScene.h) owns the solver: StartFrame(), SetUpForFrame(), EndFrame().
Physics runs on a dedicated thread; game thread reads results at sync points.
Substepping: enabled per Project Settings > Physics (MaxSubsteps, MaxSubstepDeltaTime). Enable when small/fast objects tunnel through thin geometry — substepping divides the physics tick into smaller increments so collisions are not missed.
Async physics: runs simulation on a separate thread with one-frame latency. Enable via UPhysicsSettings::bTickPhysicsAsync. Use UAsyncPhysicsInputComponent on components that need physics-thread input callbacks.
Geometry Collections (Chaos Destructibles): use UGeometryCollectionComponent. Fracture thresholds driven by FPhysicalMaterialStrength (TensileStrength, CompressionStrength, ShearStrength) and FPhysicalMaterialDamageModifier (DamageThresholdMultiplier) on UPhysicalMaterial.
Cloth Simulation
// Cloth uses UClothingAssetBase attached to USkeletalMeshComponent// Enable in Mesh asset: Clothing → Add Clothing Data// C++ access:
USkeletalMeshComponent* Mesh = GetMesh();
if (UClothingSimulationInteractor* Cloth = Mesh->GetClothingSimulationInteractor())
{
Cloth->PhysicsAssetUpdated(); // re-sync after physics asset change
Cloth->SetAnimDriveSpringStiffness(10.f); // blend anim ↔ cloth
}
Field System
Field System actors apply forces, strain, and anchors to Chaos destruction and cloth:
// Place AFieldSystemActor in level, add field nodes:// URadialFalloff — distance-based falloff// URadialVector — directional force from center// UUniformVector — constant directional force// UBoxFalloff — box-shaped field region// Trigger destruction at runtime:
AFieldSystemActor* FieldActor = GetWorld()->SpawnActor<AFieldSystemActor>();
URadialFalloff* Falloff = NewObject<URadialFalloff>(FieldActor);
Falloff->SetRadialFalloff(1000000.f, 0.8f, 1.f, 0.f, 500.f, FVector::ZeroVector, EFieldFalloffType::Field_Falloff_Linear);
UFieldSystemMetaDataFilter* Meta = NewObject<UFieldSystemMetaDataFilter>(FieldActor);
Meta->SetMetaDataFilterType(EFieldFilterType::Field_Filter_All, EFieldObjectType::Field_Object_All, EFieldPositionType::Field_Position_CenterOfMass);
FieldActor->GetFieldSystemComponent()->ApplyPhysicsField(true, EFieldPhysicsType::Field_ExternalClusterStrain, Meta, Falloff);
Common Mistakes & Anti-Patterns
Wrong collision responses: Overlap events require ECR_Overlap AND bGenerateOverlapEvents=true on BOTH components.
Traces every Tick on many actors: Use async traces or throttle to 5–10 Hz with a timer.
QueryOnly vs PhysicsOnly confusion: QueryOnly = traces only, no physics forces. PhysicsOnly = forces only, traces skip it. Use QueryAndPhysics for both.
Complex collision in traces: bTraceComplex=true is 4–10x more expensive. Default false; only enable for precise terrain interaction.
Missing SetNotifyRigidBodyCollision: OnComponentHit will never fire without it — this flag ("Simulation Generates Hit Events") is separate from collision response.
Sweep vs overlap: Sweep = shape moving along a path (movement, projectile). Overlap = shape at fixed point (AoE, proximity). Don't substitute one for the other.
Physics on dedicated servers: Disable skeletal ragdolls with bSimulateSkeletalMeshOnDedicatedServer=false unless server accuracy is required.
Multiplayer & Replicated Actor Collision
In multiplayer, physics simulation runs on the server. Collision events (OnComponentHit, OnBeginOverlap) fire on the server only by default — clients do not receive these events unless you replicate them explicitly via RPCs. Clients see physics-simulated actor positions via FRepMovement (the replicated transform + velocity struct behind bReplicateMovement). Setting bReplicateMovement = true on an actor syncs its transform and linear/angular velocity; the underlying physics state itself is not replicated. For client-predicted physics (e.g., projectiles), simulate locally on the client and reconcile with server authority on correction. Cosmetic-only physics — ragdolls, debris, environmental props — can simulate on clients independently without server involvement, since visual fidelity matters more than authority.
