claude-code-arcane 2.2.0 → 2.4.0

package/skills/ue-niagara-effects/references/niagara-workflow.md

@@ -0,0 +1,115 @@
+# Niagara VFX — Editor-Side Workflow
+
+> Adapted from the `unreal-niagara` skill in [awesome-gamedev-agent-skills](https://github.com/gamedev-skills/awesome-gamedev-agent-skills) (Apache-2.0). Cross-skill references were remapped to Arcane slash commands.
+
+Build and control real-time visual effects in UE5 with Niagara: understand the
+System/Emitter/Module hierarchy, expose parameters you can drive from gameplay, and spawn
+effects at runtime. Targets **UE 5.8**. (Niagara replaces the legacy Cascade system.)
+
+## When to use
+
+- Use when creating a Niagara System (`NS_`) and Emitters (`NE_`), wiring modules in the
+  spawn/update stages, exposing **User** parameters to gameplay, or spawning/driving an effect
+  (impact, muzzle flash, fire, magic) from Blueprint or C++.
+- Use when the project has Niagara `NS_`/`NE_` assets or references `UNiagaraComponent`.
+
+**When *not* to use:** material/shader authoring (the look of a surface, not particles) is a
+separate topic; `shader-programming` covers cross-engine shader concepts. Audio for the effect
+→ `audio-design`.
+
+## Core workflow
+
+1. **Understand the hierarchy.** A **Niagara System** (`NS_`) is the effect you place/spawn; it
+   contains one or more **Emitters** (`NE_`, often emitter *templates*). Each emitter runs in
+   stages: **Emitter Spawn/Update**, **Particle Spawn/Update**, optional **Event Handler**, and
+   **Render**.
+2. **Build behaviour from Modules**, which execute top-to-bottom in each stage (Spawn Rate,
+   Add Velocity, Gravity Force, Color over Life, etc.). Order matters — a later module reads the
+   values earlier ones wrote.
+3. **Know the parameter namespaces:** `System`, `Emitter`, `Particle`, and **`User`**. Only
+   **User-namespace** parameters are exposed to and settable from Blueprint/C++; the others are
+   internal to the simulation.
+4. **Spawn at runtime** with `UNiagaraFunctionLibrary::SpawnSystemAtLocation` (world position)
+   or `SpawnSystemAttached` (follows a component/socket), which return a `UNiagaraComponent`.
+5. **Drive the effect** by setting its User parameters on the returned component (color, spawn
+   rate, a target position) and `Activate`/`Deactivate` it.
+6. **Verify** in the Niagara editor preview and in-level; check bounds (especially GPU
+   emitters), and confirm the effect culls/destroys correctly.
+
+## Patterns
+
+### 1. Spawn a one-shot effect at a world location (C++)
+
+```cpp
+#include "NiagaraFunctionLibrary.h"
+#include "NiagaraComponent.h"
+
+// ImpactSystem is a UPROPERTY(EditAnywhere) TObjectPtr<UNiagaraSystem>.
+void AProjectile::SpawnImpact(const FVector& Location, const FRotator& Rotation)
+{
+    UNiagaraComponent* FX = UNiagaraFunctionLibrary::SpawnSystemAtLocation(
+        GetWorld(), ImpactSystem, Location, Rotation);
+    // FX auto-destroys when finished for a one-shot (system marked non-looping).
+}
+```
+
+### 2. Spawn attached to a socket (muzzle flash that follows the gun)
+
+```cpp
+UNiagaraComponent* Muzzle = UNiagaraFunctionLibrary::SpawnSystemAttached(
+    MuzzleSystem, WeaponMesh, FName("MuzzleSocket"),
+    FVector::ZeroVector, FRotator::ZeroRotator,
+    EAttachLocation::SnapToTarget, /*bAutoDestroy*/ true);
+```
+
+### 3. Drive an exposed User parameter at runtime
+
+```cpp
+// Only User-namespace parameters can be set from gameplay. Names match the User parameter.
+if (UNiagaraComponent* Fire = UNiagaraFunctionLibrary::SpawnSystemAttached(
+        FireSystem, RootComponent, NAME_None, FVector::ZeroVector, FRotator::ZeroRotator,
+        EAttachLocation::KeepRelativeOffset, /*bAutoDestroy*/ false))
+{
+    Fire->SetVariableFloat(FName("SpawnRate"), 250.f);                 // User.SpawnRate
+    Fire->SetVariableLinearColor(FName("FireColor"), FLinearColor::Red);
+}
+```
+
+### 4. Blueprint equivalent (node flow)
+
+```text
+Spawn System at Location (System = NS_Impact, Location, Rotation)  -> returns Niagara Component
+On the returned component:
+  Set Niagara Variable (Float)  Name="SpawnRate"  Value=250
+  Set Niagara Variable (LinearColor)  Name="FireColor"  Value=Red
+```
+
+## Pitfalls
+
+- **Trying to set a System/Emitter/Particle parameter from gameplay** — it won't take. Expose
+  it in the **User** namespace; only User parameters are settable via the component.
+- **Using Cascade tutorials** — Cascade is legacy/deprecated. Niagara is the current system; the
+  emitter/module workflow differs.
+- **Effect disappears or doesn't cull right** — fixed/incorrect bounds, especially for **GPU
+  Compute** emitters which need explicit Fixed Bounds. Set bounds on the emitter/system.
+- **Looping effect never stops** — spawned with `bAutoDestroy = false` and never
+  `Deactivate()`d; manage the returned component's lifetime, or mark the system non-looping for
+  one-shots.
+- **GPU sim can't drive gameplay** — GPU particle data isn't readily read back to the CPU;
+  collision/events that gameplay must react to should use CPU emitters (or Niagara → gameplay
+  via the data interface), not GPU.
+- **Module order bugs** — a Force/Velocity module placed before the one that initializes the
+  value reads zero. Mind the top-to-bottom stack order.
+
+## References
+
+- Primary docs: "Overview of Niagara Effects"
+  (`https://dev.epicgames.com/documentation/en-us/unreal-engine/overview-of-niagara-effects-for-unreal-engine`)
+  and the `UNiagaraFunctionLibrary` / `UNiagaraComponent` API. Add the `Niagara` module to
+  `*.Build.cs` for C++ access.
+
+## Related skills
+
+- `shader-programming` — material/shader concepts for particle materials.
+- `/ue-cpp-foundations` — spawning effects from gameplay code and module setup.
+- `/ue-blueprints` — triggering effects from visual scripts.

package/skills/ue-packaging/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: ue-packaging
+description: "Packaging and cooking — build configurations, cook vs package, Game Default Map, RunUAT BuildCookRun, platform SDKs"
+category: "gamedev"
+argument-hint: "[platform o build config]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit
+---
+
+# UE Packaging & Cooking
+
+Turn a UE5 project into a runnable, distributable build: choose the right build configuration, cook content, set the launch map, and package — from the editor or the command line.
+
+Ask before writing: this skill edits `Config/Default*.ini`, packaging settings and CI build scripts. Propose the change and get approval before using Write or Edit.
+
+## Context Check
+
+Read `docs/unreal/project-context.md` before proceeding. Confirm:
+
+- Engine version and whether the project is Blueprint-only (`DebugGame` is unavailable there)
+- Target platforms and which platform SDKs are actually installed
+- Whether builds run locally, on CI, or both — this decides editor flow vs `RunUAT`
+
+## When to Use
+
+- Producing a build (test or release), choosing Development vs Shipping, cooking content, configuring Packaging / Maps & Modes settings, or automating builds with `RunUAT BuildCookRun` for CI.
+- The goal is a packaged player rather than running in-editor.
+
+**When not to use:** storefront submission and release process → `/release-checklist`. Editor-time gameplay iteration is not packaging.
+
+## Core Workflow
+
+1. **Set the launch map.** Project Settings → **Maps & Modes** → **Game Default Map** is what a packaged build loads first. Wrong or empty here is the most common "packaged game is black" cause.
+2. **Pick the build configuration.** **Development** (default; optimized but keeps logging/stats/console for testing) vs **Shipping** (all optimizations, debugging tools stripped — for release). `DebugGame`/`Debug` are for debugging engine/game code and aren't for distribution; `DebugGame` isn't available for Blueprint-only projects.
+3. **Understand cook vs package.** **Cooking** converts assets to the target platform's format and packs them into `.pak` files. **Packaging** bundles the compiled executable plus cooked content into a standalone, distributable set of files. Packaging runs a cook as part of it.
+4. **Package from the editor:** the **Platforms** menu → choose the platform → set the Binary Configuration → **Package Project** → pick an output folder.
+5. **Or build from the command line** with the Unreal Automation Tool (`RunUAT BuildCookRun`) for repeatable and CI builds.
+6. **Tune Packaging settings** (Project Settings → **Packaging**): which maps and directories to cook, full-rebuild, compression, and whether to build all maps.
+7. **Verify by running the packaged build**, not just by a successful cook — launch the executable and confirm it loads the right map and runs.
+
+## Patterns
+
+### 1. Editor packaging (the menu path)
+
+```text
+Platforms (toolbar)
+  -> Windows
+     -> Binary Configuration -> Development | Shipping
+     -> Content Management -> Package Project
+  -> choose/confirm the staging output folder
+```
+
+### 2. Command-line build with UAT (CI-friendly)
+
+```bash
+# Cook + build + stage + pak + archive a Shipping Windows build.
+RunUAT BuildCookRun \
+  -project="C:/Path/MyGame.uproject" \
+  -noP4 -platform=Win64 -clientconfig=Shipping \
+  -cook -allmaps -build -stage -pak -archive \
+  -archivedirectory="C:/Builds/MyGame"
+```
+
+`RunUAT` lives in `Engine/Build/BatchFiles/` (`RunUAT.bat` on Windows, `RunUAT.sh` on macOS/Linux). Drop `-allmaps` and pass `-map=Map1+Map2` to cook a subset.
+
+### 3. Cook only (no packaging), e.g. to refresh content
+
+```bash
+RunUAT BuildCookRun -project="C:/Path/MyGame.uproject" -noP4 \
+  -platform=Win64 -clientconfig=Development -cook -skipstage
+```
+
+## Common Mistakes
+
+- **Packaged build loads a black or empty level** — Game Default Map isn't set, or that map wasn't cooked. Set it in Maps & Modes and ensure it's included in the cook.
+- **Shipping a Development build** — Development keeps logging/console/stats and is slower; ship **Shipping**. Conversely, Shipping strips `UE_LOG` and the console, so debugging a Shipping-only issue needs Development or `Test`.
+- **A referenced map or asset is missing at runtime** — it wasn't cooked. Add it to the Packaging settings' maps/directories to cook, or cook all maps.
+- **Build fails on the platform** — the platform SDK or toolchain isn't installed (Windows build tools, Android SDK/NDK, console SDKs). Install the platform's prerequisites.
+- **Expecting Blueprint Nativization** — it was **removed in UE5**. Don't rely on it for performance; profile and move hot logic to C++ instead.
+- **First cook is very slow** — shaders and all assets cook from scratch, and subsequent cooks are incremental. Don't mistake a slow first cook for a hang.
+- **Cooking secrets into the build** — config files staged into a packaged build are readable. Keep credentials out of `Config/`.
+
+## Reference Files
+
+Primary docs: [Packaging Your Project](https://dev.epicgames.com/documentation/en-us/unreal-engine/packaging-your-project), plus the Build Configurations and `BuildCookRun` references.
+
+---
+
+## Related Skills
+
+- `/ue-module-build-system` — `Build.cs`/`Target.cs` and module wiring that packaging depends on
+- `/ue-cpp-foundations` — moving hot logic to C++ now that BP nativization is gone
+- `/ue-data-assets-tables` — Asset Manager and Primary Asset types that drive what gets cooked
+- `/ue-testing-debugging` — automation tests that should gate a release build
+
+---
+
+## Checklist
+
+Validate before considering the work done:
+
+- [ ] Game Default Map is set and included in the cook
+- [ ] Build configuration matches the intent (Shipping for release, Development for testing)
+- [ ] The packaged executable was launched and verified, not just cooked successfully
+- [ ] No credentials or internal config were staged into the build
+- [ ] Conventions in `docs/unreal/project-context.md` were read and followed
+- [ ] The Common Mistakes section of this skill was reviewed against the change
+
+**PASS** — every item holds. **CONCERNS** — the work stands but at least one item is unresolved and worth flagging to the user. **FAIL** — an item is violated in a way that produces a broken or unshippable build; fix it before handing the work over.
+
+## Next Steps
+
+- `/release-checklist` — full release gate before distribution
+- `/patch-notes` — user-facing notes for the packaged build
+- `/code-review` — architectural and quality review of the change
+- `/commit` — conventional commit once the change is verified

package/skills/ue-physics-collision/SKILL.md

@@ -0,0 +1,423 @@
+---
+name: ue-physics-collision
+description: "Collision detection, traces, physics simulation, physical interactions, Chaos physics"
+category: "gamedev"
+argument-hint: "[interaction o collision setup]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit
+---
+
+# 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.
+
+Ask before writing: this skill edits collision presets, physics assets and trace code. Propose the change and get approval before using Write or Edit.
+
+---
+
+## Step 1: Read Project Context
+
+Read `docs/unreal/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
+
+```cpp
+ECC_WorldStatic, ECC_WorldDynamic, ECC_Pawn, ECC_PhysicsBody,
+ECC_Vehicle, ECC_Destructible               // object channels (what an object IS)
+ECC_Visibility, ECC_Camera                  // trace channels (used for queries)
+// Custom: ECC_GameTraceChannel1..ECC_GameTraceChannel18
+```
+
+**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++
+
+```cpp
+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`).
+
+### Custom Channels — DefaultEngine.ini
+
+```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="Interactable",CollisionEnabled=QueryAndPhysics,ObjectTypeName="Interactable",CustomResponses=((Channel="Weapon",Response=ECR_Ignore),(Channel="Visibility",Response=ECR_Block)))
+```
+
+`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
+
+```cpp
+FCollisionQueryParams Params;
+Params.TraceTag                = TEXT("WeaponTrace"); // for profiling/debug
+Params.bTraceComplex           = false;  // false=simple hull (fast); true=per-poly (expensive)
+Params.bReturnPhysicalMaterial = true;   // populates Hit.PhysMaterial
+Params.bReturnFaceIndex        = false;  // expensive, only when needed
+Params.AddIgnoredActor(this);
+Params.AddIgnoredComponent(MyComp);
+```
+
+### World-Level Trace Functions (C++) — from `WorldCollision.h` via `UWorld`
+
+```cpp
+FHitResult Hit;
+// By trace channel
+GetWorld()->LineTraceSingleByChannel(Hit, Start, End, ECC_Visibility, Params);
+GetWorld()->LineTraceMultiByChannel(Hits, Start, End, ECC_Visibility, Params);
+// By object type
+FCollisionObjectQueryParams ObjParams(ECC_PhysicsBody);
+ObjParams.AddObjectTypesToQuery(ECC_WorldDynamic);
+GetWorld()->LineTraceSingleByObjectType(Hit, Start, End, ObjParams, Params);
+// By profile
+GetWorld()->LineTraceSingleByProfile(Hit, Start, End, TEXT("BlockAll"), Params);
+```
+
+### Sweep Queries — FCollisionShape (from `CollisionShape.h`)
+
+```cpp
+FCollisionShape Sphere  = FCollisionShape::MakeSphere(30.f);
+FCollisionShape Box     = FCollisionShape::MakeBox(FVector(50.f, 50.f, 50.f));
+FCollisionShape Capsule = FCollisionShape::MakeCapsule(34.f, 88.f); // radius, half-height
+
+GetWorld()->SweepSingleByChannel(Hit, Start, End, FQuat::Identity, ECC_Pawn, Sphere, Params);
+GetWorld()->SweepMultiByChannel(Hits, Start, End, FQuat::Identity, ECC_Pawn, Sphere, Params);
+GetWorld()->SweepSingleByObjectType(Hit, Start, End, FQuat::Identity, ObjParams, Sphere, Params);
+GetWorld()->SweepSingleByProfile(Hit, Start, End, FQuat::Identity, TEXT("Pawn"), Sphere, Params);
+```
+
+### Overlap Queries
+
+```cpp
+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
+
+```cpp
+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);
+```
+
+### Blueprint-Layer Traces (UKismetSystemLibrary)
+
+```cpp
+#include "Kismet/KismetSystemLibrary.h"
+TArray<AActor*> Ignore = { this };
+// LineTrace with debug draw (ETraceTypeQuery maps to ECollisionChannel)
+UKismetSystemLibrary::LineTraceSingle(this, Start, End,
+    ETraceTypeQuery::TraceTypeQuery1, false, Ignore, EDrawDebugTrace::ForDuration, Hit, true);
+// SphereTrace
+UKismetSystemLibrary::SphereTraceSingle(this, Start, End, 50.f,
+    ETraceTypeQuery::TraceTypeQuery1, false, Ignore, EDrawDebugTrace::ForOneFrame, Hit, true);
+// By profile
+UKismetSystemLibrary::LineTraceSingleByProfile(this, Start, End,
+    TEXT("BlockAll"), false, Ignore, EDrawDebugTrace::None, Hit, true);
+```
+
+### Async Traces
+
+```cpp
+FTraceHandle Handle = GetWorld()->AsyncLineTraceByChannel(
+    EAsyncTraceType::Single, Start, End, ECC_Visibility, Params);
+// Read next frame:
+FTraceDatum Datum;
+if (GetWorld()->QueryTraceData(Handle, Datum) && Datum.OutHits.Num() > 0)
+    FHitResult& Hit = Datum.OutHits[0];
+```
+
+### Debug Visualization
+
+```cpp
+#if ENABLE_DRAW_DEBUG
+DrawDebugLine(GetWorld(), Start, End, FColor::Red, false, 2.f);
+DrawDebugSphere(GetWorld(), HitResult.ImpactPoint, 10.f, 12, FColor::Green, false, 2.f);
+#endif
+```
+
+`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)`
+
+```cpp
+// Hit events (physics collision)
+MyMesh->SetNotifyRigidBodyCollision(true);  // "Simulation Generates Hit Events"
+MyMesh->OnComponentHit.AddDynamic(this, &AMyActor::OnHit);
+
+UFUNCTION()
+void AMyActor::OnHit(UPrimitiveComponent* HitComp, AActor* OtherActor,
+                      UPrimitiveComponent* OtherComp, FVector NormalImpulse, const FHitResult& Hit) {}
+
+// Overlap events — SetGenerateOverlapEvents(true) REQUIRED on BOTH components
+MyMesh->SetGenerateOverlapEvents(true);
+MyMesh->OnComponentBeginOverlap.AddDynamic(this, &AMyActor::OnBeginOverlap);
+MyMesh->OnComponentEndOverlap.AddDynamic(this, &AMyActor::OnEndOverlap);
+
+UFUNCTION()
+void AMyActor::OnBeginOverlap(UPrimitiveComponent* OverlappedComp, AActor* OtherActor,
+    UPrimitiveComponent* OtherComp, int32 OtherBodyIndex, bool bFromSweep, const FHitResult& SweepResult) {}
+
+UFUNCTION()
+void AMyActor::OnEndOverlap(UPrimitiveComponent* OverlappedComp, AActor* OtherActor,
+    UPrimitiveComponent* OtherComp, int32 OtherBodyIndex) {}
+```
+
+**Requirements:** Hit: `QueryAndPhysics`, `ECR_Block` on both, `SetNotifyRigidBodyCollision(true)`. Overlap: `ECR_Overlap` on both, `SetGenerateOverlapEvents(true)` on both.
+
+---
+
+## Physics Bodies
+
+```cpp
+// Enable simulation (PrimitiveComponent.h / BodyInstanceCore.h)
+MyMesh->SetSimulatePhysics(true);
+MyMesh->SetEnableGravity(true);
+MyMesh->SetMassOverrideInKg(NAME_None, 50.f, true); // 50 kg
+MyMesh->SetLinearDamping(0.1f);
+MyMesh->SetAngularDamping(0.05f);
+float Mass = MyMesh->GetMass();
+
+// Forces and impulses
+MyMesh->AddImpulse(FVector(0,0,1000), NAME_None, false);       // bVelChange=true ignores mass
+MyMesh->AddImpulseAtLocation(FVector(500,0,0), HitPoint);      // adds torque
+MyMesh->AddForce(FVector(0,0,9800), NAME_None, false);          // continuous (per tick)
+MyMesh->AddRadialImpulse(Center, 500.f, 2000.f, RIF_Linear, false);
+MyMesh->SetPhysicsLinearVelocity(FVector(0,0,300));             // use sparingly
+```
+
+**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
+
+```cpp
+UPhysicsConstraintComponent* C = NewObject<UPhysicsConstraintComponent>(this);
+C->SetupAttachment(RootComponent);
+C->SetConstrainedComponents(MeshA, NAME_None, MeshB, NAME_None);
+C->SetAngularSwing1Limit(EAngularConstraintMotion::ACM_Limited, 45.f);
+C->SetAngularTwistLimit(EAngularConstraintMotion::ACM_Free, 0.f);
+C->SetLinearXLimit(ELinearConstraintMotion::LCM_Locked, 0.f);
+C->RegisterComponent();
+```
+
+**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`:
+
+```cpp
+float Friction;       // kinetic (0 = frictionless)
+float StaticFriction; // before sliding starts
+float 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.
+
+Key `UPhysicsSettingsCore` fields (`PhysicsSettingsCore.h`):
+```cpp
+float DefaultGravityZ;         // -980 cm/s^2 default
+float BounceThresholdVelocity; // min velocity to bounce
+float MaxAngularVelocity;      // rad/s cap
+float MaxDepenetrationVelocity;
+float ContactOffsetMultiplier; // contact shell size
+FChaosSolverConfiguration SolverOptions;
+```
+
+**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
+
+```cpp
+// 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:
+
+```cpp
+// 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.
+
+---
+
+## Required Module Dependencies
+
+```csharp
+// Build.cs
+PublicDependencyModuleNames.AddRange(new string[] {
+    "Core", "CoreUObject",
+    "Engine",      // UPrimitiveComponent, FHitResult, UWorld trace API
+    "PhysicsCore", // UPhysicalMaterial, FCollisionShape, FBodyInstanceCore
+});
+```
+
+---
+
+## 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
+
+---
+
+## Checklist
+
+Validate before considering the work done:
+
+- [ ] Collision channels and presets are defined in config, not hardcoded per actor
+- [ ] Traces use the narrowest channel and shape that answers the question
+- [ ] Complex collision is avoided on anything queried frequently
+- [ ] Conventions in `docs/unreal/project-context.md` were read and followed
+- [ ] The Common Mistakes section of this skill was reviewed against the change
+
+**PASS** — every item holds. **CONCERNS** — the work stands but at least one item is unresolved and worth flagging to the user. **FAIL** — an item is violated in a way that breaks correctness, replication or the frame budget; fix it before handing the work over.
+
+## Next Steps
+
+- `/perf-profile` — check physics and trace cost in the profiler
+- `/code-review` — architectural and quality review of the change
+- `/commit` — conventional commit once the change is verified