GET STARTEDTROUBLESHOOTING

Troubleshooting

Each problem below gives its cause and its fix. Where the plugin writes a log line, the block shows the format string from the source: %s is an object path and %d a number. The warnings and errors appear in the Output Log under LogCrushform or LogCrushformWheel. The Crushform.Stats lines are what that command prints.

Dents

Nothing dents

Cause. A UCFDeformComponent does nothing without a Crushform profile (UCFProfile). It lays out no lattice until the profile is set, and it writes no log line for that. A vehicle adapter with no Deform Profile set uses the project’s default profile.

If a profile is set but the owner has no mesh that can bend, the component stays off and logs:

%s has a profile but no deformable mesh components; Crushform stays off

Fix. Create a UCFProfile data asset and set it on the component: in the class defaults, or between SpawnActorDeferred and FinishSpawning. For the mesh side, see the sections below.

A mesh does not dent because its material is not wired

Cause. A mesh shows its dents only through its material. MF_CF_Deform moves the vertices and turns their normals, and it must be connected to World Position Offset and Normal. Without that, the mesh does not move.

Fix. Wire every material of a mesh that should bend: MF_CF_Deform into World Position Offset and Normal, MF_CF_Paint between your paint and Base Color, Roughness and Metallic, and Wear Depth and Scratch fed from MF_CF_Deform. From Python, unreal.CFContentLibrary.wire_material(material, deform, paint, max_displacement + fold_amplitude) does all of it.

Some meshes do not dent

Cause. Only static meshes and skinned meshes bend. Instanced static meshes never do, because all their instances share one primitive. Then the profile’s Include Tags and Exclude Tags filter the rest: if Include Tags is not empty, a mesh needs one of its tags, and a mesh with any of the Exclude Tags is skipped.

Fix. Put the mesh in a plain static mesh component, not an instanced one. Check the mesh’s component tags against the profile’s Include Tags and Exclude Tags, and remove the tag or change the lists. A part that moves relative to the body should be excluded; see Moving parts.

A hit is too weak to dent

Cause. A hit whose delta V is at or below Min Delta V leaves no dent. The default is 0.5 m/s. The hit may still count as a scrape.

Fix. Lower Min Delta V in the profile if small hits should dent. To test with a harder hit, run Crushform.DebugImpact [DeltaV] [Name]: it hits the actor under the crosshair at 10 m/s by default. It is a cheat; it exists in every build except Shipping.

The vehicle has no dents and no dirt

Cause. The vehicle adapter creates its deform component only when Dirt and Dents is on. The glass panes and the wheels’ dirt need it too.

Fix. Tick Dirt and Dents on the adapter.

Dents stop on some damaged vehicles

Cause. The atlas has a fixed number of slots, 128 by default, each 256x8 texels. When every slot is taken, a damaged actor waits for one, and the damaged actors farthest from their players’ cameras are drawn undamaged until a slot frees up. Crushform.Stats prints the slot count:

Crushform atlas: %d of %d slots used, %d waiting, %d evictions, %d uploads.

Fix. Point Atlas (Project Settings › Plugins › Crushform › Atlas) at a larger RGBA8 render target of your own, up to 4096 texels a side. The slot count is its size divided by Slot Width by Slot Height.

Moving parts bend wrong

Cause. The lattice is fixed to the root at BeginPlay. A mesh that moves later bends in its BeginPlay pose. Doors and the steering wheel are typical examples.

Fix. Exclude the part by tag, as described under Some meshes do not dent.

Materials

The material stops compiling after wiring: it already reads two parameter collections

Cause. A material can reference at most two Material Parameter Collections. Wiring MF_CF_Paint or MF_CF_WheelDirt adds the dirt collection, so a master that already reads two no longer compiles.

Fix. Leave room for the dirt collection before you wire: the master may reference at most one other collection. For example, move the parameters of the second collection into the first, then wire again.

Wiring is refused: the material takes a world-space normal

Cause. MF_CF_Deform works in tangent space. A material whose normal is world space is refused, and the wiring leaves it as it was:

WireMaterial: %s takes a world-space normal; MF_CF_Deform works in tangent space

Fix. Set the material to a tangent-space normal (the Tangent Space Normal option), then wire it again.

Dents flicker at the edge of the screen on Nanite

Cause. Nanite culls by the bound of World Position Offset. If Max World Position Offset Displacement is shorter than the deepest dent plus the fold amplitude, a dent near the screen edge flickers. The profile’s Max Displacement is the furthest any node moves, and body materials must use it.

Fix. Wire the material again: the wiring raises the bound when it is too small. Or set Max World Position Offset Displacement by hand to the profile’s Max Displacement plus the material’s Fold Amplitude.

A skeletal mesh does not dent

Cause. The shaders for skeletal meshes are compiled only when the material is marked Used with Skeletal Mesh. The plugin’s own vehicle masters are marked this way.

Fix. In the material’s Details, under Usage, tick Used with Skeletal Mesh.

Dirt and wheels

No dirt on the body

Cause. The body gets dirty only when a Surfaces asset is set in Project Settings > Plugins > Crushform. Without one, no body gets dirty. If the asset is set but does not load, the log says:

Crushform surfaces %s do not load; bodies stay clean

Dirt also needs a wheel host: a body with no wheels reported to it gets no dirt, and the dirt timer does nothing.

Fix. Set Surfaces to /Crushform/Surfaces/DA_CF_Surfaces, or to your own table. Add a vehicle adapter (or a host that answers the wheel questions). Then check that Dirt and Dents is on.

No dirt on a dedicated server

Cause. A dedicated server draws no dirt, so there is no dirt to see there. Crushform.Stats says so on a server:

Crushform atlas: none in this process (a dedicated server draws nothing).

The dirt events OnDirtChanged, OnWashed and OnWheelSurfaceChanged never fire on a dedicated server.

Fix. Look at dirt on a client. AddDirt and WashAt change only the local machine’s dirt, so call them on every machine that should show the result. Wash is the networked wash of the whole body; it is authority only, and it washes every machine.

The ground leaves no dirt

Cause. A wheel reads the row of its ground’s physical material in the Surfaces table. A material with no row gets the Default row. The row’s Dirt rates set what the ground gives to the body, so a Default row with zero Dirt leaves no dirt on any ground that has no row of its own.

Fix. Give the ground one of the plugin’s physical materials, such as /Crushform/Surfaces/PM_CF_Asphalt, or your own. Add a row for it in the Surfaces table with its Dirt rates set.

A wheel gets no dirt because it is only a bone

Cause. A wheel that is only a bone has no wheel mesh to dirty or deform, so it gets no dirt and no tyre deformation. The Chaos adapter reads a wheel’s bone name from the movement component.

Fix. Give the wheel a mesh, so it has something to dirty.

The wheels stay clean

Cause. The wheel’s material does not go through MF_CF_WheelDirt. The plugin’s wheel material is built that way: Base Color, Roughness and Metallic go through MF_CF_WheelDirt.

Fix. Use /Crushform/Materials/M_CF_Wheel. Or wire MF_CF_WheelDirt into the wheel’s Base Color, Roughness and Metallic yourself.

A wheel has no dents and no wheel dirt although its material has `MF_CF_Deform` or `MF_CF_Paint`

Cause. The vehicle adapter never deforms a wheel mesh, or anything attached under one, because a wheel turns under the body’s lattice. A body material (MF_CF_Deform or MF_CF_Paint) on a wheel therefore never gets dents, and only MF_CF_WheelDirt draws wheel dirt.

Fix. Remove MF_CF_Deform and MF_CF_Paint from the wheel’s material. Keep MF_CF_WheelDirt, and MF_CF_TireDeform under its Tire Deform switch. Leave Tire Deform off on a rim.

Sound and effects

No rolling sound

Cause. The rolling sound stays silent in four cases:

The Rolling Sound switch in Project Settings > Plugins > Crushform Wheels is off.

Attenuation is empty. The sound stays off and the log says:

%s: no Attenuation in Project Settings > Plugins > Crushform Wheels; the rolling sound stays off

The ground’s row has no Rolling Sound. An empty field is silent, and the row does not borrow the Default row’s sound.
No listener is near. The sound plays only while a listener is within the reach of the attenuation.

Fix. Tick Rolling Sound. Set Attenuation to /Crushform/Sounds/SA_CF_TireRolling. Give the ground’s row a Rolling Sound, for example /Crushform/Sounds/SW_CF_Tire_Asphalt_Loop. Then stand within range.

Multiplayer

Dents differ between players

Cause. One machine is the impact source for a body. By default that is the authority. A machine that is neither the authority nor the impact source does not apply a hit of its own. The machine that simulates the body is the impact source: its own report carries the dent. Also, the server rejects any report harder than Max Plausible Delta V, which is 40 m/s by default.

Fix. In your ICFDeformHost, make IsCrushformImpactSourceHere answer Yes on the machine that simulates the body. If your hits are harder than Max Plausible Delta V, raise the limit, or the server will reject those reports. Compare the network and hit counters with Crushform.Stats on the server and on the client.

Console and builds

Console commands do nothing in a shipped build

Cause. All Crushform console commands are compiled out of Shipping builds. Crushform.Debug, Crushform.ShowZones, Crushform.ShowCollision, Crushform.RepairAll and Crushform.DebugImpact are cheats; they exist in every build except Shipping, and in the editor.

Fix. Test these commands in the editor or in a build that is not Shipping. Do not depend on CrushformDebug from code that ships (see Installation).

Hosts

The Blueprint host’s answer is not visible in the preview

Cause. The editor preview does not run Blueprint host answers. AActor::ProcessEvent skips script on an actor whose world’s actors are not initialized, which is the case in the preview. The Details panel and the zone editor therefore do not see a Blueprint’s answer.

Fix. Check the answer in Play In Editor, where the actors are initialized.

A second host replaces the first

Cause. A host is kept per actor and per interface. A second host for the same actor and interface replaces the first, with a warning:

Host %s replaces host %s for %s under %s

Fix. Keep one host per actor and interface, and remove the registration you do not want.

The host is refused

Cause. An object that does not implement the interface is refused. In C++ the registry logs:

Host %s does not implement %s, so it cannot answer for %s

A host set with SetCrushformHost after BeginPlay is refused too:

%s: SetCrushformHost after BeginPlay is refused; the host is read once, in BeginPlay

Fix. In Blueprint, open Class Settings, click Add under Implemented Interfaces, then implement its functions. Call SetCrushformHost before BeginPlay.

Check that it works

Run the level again in Play In Editor and reproduce the problem.
Open the console and run Crushform.Stats. It prints the atlas slots in use, the slots waiting, and the counters of every damageable actor. If slots are waiting, see Dents stop on some damaged vehicles.
Run Crushform.Debug 1. It draws the damaged lattice nodes and recent hits, so you can see where the body was dented.
Check the Output Log for new LogCrushform and LogCrushformWheel lines.