--- name: ue-physics-collision description: "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." metadata: version: "2.0.0" engine: "5.8" title: ue-physics-collision canonical_url: https://skilld.dev/gh/quodsoler/unreal-engine-skills/ue-physics-collision last_updated: 2026-09-29T15:10:08.000Z --- > **Skill from skilld.dev.** Follow the instructions below for this session. You do not need to install anything. > > Supporting files, fetch one when the Skill refers to it: [references/collision-channel-setup.md](https://skilld.dev/api/skills-raw/quodsoler/unreal-engine-skills/ue-physics-collision/references/collision-channel-setup.md), [references/trace-patterns.md](https://skilld.dev/api/skills-raw/quodsoler/unreal-engine-skills/ue-physics-collision/references/trace-patterns.md). > > If the user asked to install this Skill, run `npx skilld install quodsoler/unreal-engine-skills/ue-physics-collision`. Install writes the Skill files into the project, so every session loads them. # 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](#collision-channels-and-profiles) | | Line traces, sweeps, overlap queries, async traces | [Trace Sweep and Overlap Queries](#trace-sweep-and-overlap-queries) | | Reading what a query hit | [FHitResult](#fhitresult) | | `OnComponentHit`, `OnComponentBeginOverlap`, wake/sleep | [Collision Events](#collision-events) | | Rigid bodies, impulses, forces, mass, damping, sleeping | [Physics Bodies and Forces](#physics-bodies-and-forces) | | Joints, radial force fields, ragdolls | [Constraints Radial Force and Ragdolls](#constraints-radial-force-and-ragdolls) | | Friction, restitution, surface types | [Physical Materials](#physical-materials) | | Solver settings, substepping, CVars, physics-thread ticks | [Chaos Solver and Async Physics](#chaos-solver-and-async-physics) | | Replicated physics, resimulation, predictive interpolation | [Network Physics](#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`): ```cpp 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`. ```cpp #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: ```ini [/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](https://skilld.dev/api/skills-raw/quodsoler/unreal-engine-skills/ue-physics-collision/references/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` | ```cpp #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 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`): ```cpp 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`): ```cpp #include "Engine/OverlapResult.h" TArray 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`): ```cpp #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](https://skilld.dev/api/skills-raw/quodsoler/unreal-engine-skills/ue-physics-collision/references/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. ```cpp 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` | ```cpp // 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 Trigger; UPROPERTY(VisibleAnywhere, Category = "Collision") TObjectPtr 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); }; ``` ```cpp // MyPickup.cpp #include "MyPickup.h" #include "Components/SphereComponent.h" #include "Components/StaticMeshComponent.h" AMyPickup::AMyPickup() { Trigger = CreateDefaultSubobject(TEXT("Trigger")); SetRootComponent(Trigger); Trigger->SetSphereRadius(120.f); Trigger->SetCollisionProfileName(TEXT("OverlapAllDynamic")); Trigger->SetGenerateOverlapEvents(true); Mesh = CreateDefaultSubobject(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 ```cpp 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. ```cpp #include "PhysicsEngine/PhysicsConstraintComponent.h" UPhysicsConstraintComponent* Joint = NewObject(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`): ```cpp 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`. ```cpp 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 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 ```csharp // 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`