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', 'OnBe

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: 1. Collision setup — channels, profiles, responses on components 2. Trace queries — line traces, sweeps, overlap queries for gameplay logic 3. Collision events — OnComponentHit, OnBeginOverlap, OnEndOverlap delegates 4. Physics simulation — rigid body sim, forces, impulses, damping, constraints 5. Physical materials — friction, restitution, surface type detection Collision Channels & Profiles ECollisionChannel — built in channels Responses : ECR Ignore / ECR Overlap (events, no block) / ECR Block (physical block + events). Built in profiles : BlockAll , BlockAllDynamic , OverlapAll , OverlapAllDynamic , Pawn , PhysicsActor , NoCollision . Setting Collision in C++ 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 ). Custom Channels — DefaultEngine.ini bTraceType=True = trace channel; bTraceType=False = object type channel. They use separate query functions. See references/collision channel setup.md for full profile examples. Trace Queries FCollisionQueryParams World Level Trace Functions (C++) — from WorldCollision.h via UWorld Sweep Queries — FCollisionShape (from CollisionShape.h ) Overlap Queries FHitResult — Key Fields Blueprint Layer Traces (UKismetSystemLibrary) Async Traces Debug Visualization 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). Collision Events Delegate declarations from PrimitiveComponent.h : OnComponentHit — (HitComp, OtherActor, OtherComp, NormalImpulse, FHitResult) — physics collision OnComponentBeginOverlap — (OverlappedComp, OtherActor, OtherComp, OtherBodyIndex, bFromSweep, SweepResult) OnComponentEndOverlap — (OverlappedComp, OtherActor, OtherComp, OtherBodyIndex) Requirements: Hit: QueryAndPhysics , ECR Block on both, SetNotifyRigidBodyCollision(true) . Overlap: ECR Overlap on both, SetGenerateOverlapEvents(true) on both. Physics Bodies FBodyInstanceCore key flags (set via UPROPERTY/editor): bSimulatePhysics , bOverrideMass , bEnableGravity , bAutoWeld , bStartAwake , bGenerateWakeEvents , bUpdateKinematicFromSimulation . Collision complexity ( BodySetupEnums.h ): CTF UseDefault , CTF UseSimpleAndComplex , CTF UseSimpleAsComplex , CTF UseComplexAsSimple (expensive, static only for physics). Physics Constraints 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 : 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. Key UPhysicsSettingsCore fields ( PhysicsSettingsCore.h ): EPhysicalSurface : 62 configurable slots ( SurfaceType1..SurfaceType62 ) mapped in Project Settings Physics Physical Surface. Geometry Collections (Chaos Destructibles) : use UGeometryCollectionComponent . Fracture thresholds driven by FPhysicalMaterialStrength (TensileStrength, CompressionStrength, ShearStrength) and FPhysicalMaterialDamageModifier (DamageThresholdMultiplier) on UPhysicalMaterial . Cloth Simulation Field System Field System actors apply forces, strain, and anchors to Chaos destruction and cloth: 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. Required Module Dependencies Related Skills ue actor component architecture — UPrimitiveComponent lifecycle, attachment, registration ue ai navigation — trace based sensing and navmesh overlap queries ue gameplay abilities — targeting systems built on trace and overlap queries ue cpp foundations — delegate binding syntax and UFUNCTION requirements

ue-physics-collision