Troubleshooting

02

No sound or unexpected default surface#

Separate accepted contact, channel emission, attenuation, and collision-material problems.

• Audio must be enabled and contain a non-null sound with a finite positive weight.
• A profile Max Audio Spawns Per Second of 0 disables audio emission.
• Resolution order is exact Physical Material, Physical Surface, then global default.
• A matching silent surface definition shadows the global Default Definition, and a matching silent Step override shadows that definition's Default Payload. Configure that exact entry or remove it from the project-owned copy.
• The neutral Starter contains the global Default plus Surface Type 1 through 9 definitions. Each has a disabled Step Default Payload and a disabled Land override; enabling only the global definition may not affect the explicit floor being tested.
• When Unreal returns no Physical Material, fallback to SurfaceType_Default is correct behavior.

03

Niagara effect does not appear#

An accepted contact and On Footstep Spawned do not prove that the Niagara channel emitted; inspect its exact configuration and counters.

1. 1

   Confirm the resolved payload

   Read Out Context and verify the exact surface and event entry. A matching silent surface or event does not fall through to a broader default.

2. 2

   Assign a Niagara System

   Enable the Niagara channel and provide at least one non-null Niagara System with a finite positive weight. A standalone Niagara Emitter is not a valid variant.

3. 3

   Check exact counters

   Enable Collect Runtime Stats temporarily and compare Niagara emissions with profile and world Niagara rejections. On Footstep Spawned means any configured channel emitted, not specifically Niagara.

4. 4

   Check presentation

   Verify listener distance, local significance policy, transform and scale, system bounds, visibility, pooling compatibility, and the target RHI.

5. 5

   Retest one channel

   Disable unrelated channels in a project-owned test copy, use one deterministic Niagara System, and restore production diagnostics afterward.

04

Missing socket or no ground hit#

Socket failure is explicit and trace failure remains separate from source validation.

• A missing socket performs no trace and never falls back to the Skeletal Mesh component origin.
• The current runtime uses a line trace; sphere-trace behavior is not part of the shipped contract.
• Duplicate contacts in BlendSpace samples should be removed even though the rate limiter bounds runtime duplication.
• Do not trigger the same landing from both an AnimNotify and On Landed.

05

Wrong decal or missing transfer trail#

Validate material domain, projection axes, source identity, stage route, parameter names, and budget consumption.

• Use a Deferred Decal material; set Random Yaw, Pitch, and Yaw to 0 for directional footprints, then use Roll for fixed in-plane correction.
• Keep Projection Placement on Surface Anchored for contact marks; start Normal Offset Cm at 0.1 and use the smallest X projection half-depth that fully renders the ground mark.
• Decal Size is half-extents in centimeters: X projection depth, Y texture-V forward length, and Z texture-U lateral width.
• Route every selectable Surface Transfer material's final alpha through MF_FSP_SourceExclusion and enable Custom Depth-Stencil Pass with Stencil while keeping r.CustomDepth.Order at 0 or 2.
• Confirm the source contact resolves the intended exact material or surface and that acquisition/emission events match.
• Move to a different source identity; remaining on the source refreshes acquisition and does not emit a transferred mark.
• Verify every selectable material exposes the exact intensity, footwear texture, and mirror parameters configured by Surface Data.
• A decal budget rejection still consumes the eligible trail contact by design.
• Reset a legacy 2.2.0 Pitch = -90 workaround to 0 because current runtime owns the correct projection axis.

06

A receiver Actor disappears when an attached decal fades#

If the receiver Actor is destroyed or disappears when an attached decal fades, this is the receiver-owner destruction defect corrected in Footstep Studio 2.11.2.

1. 1

   Verify the installed version

   Confirm the active descriptor reports 2.11.2 and that no stale plugin copy or binary is being loaded from another project or engine location.

2. 2

   Replace the plugin cleanly

   Close the editor, replace the complete FootstepSystem package, remove only that copied plugin's stale Binaries and Intermediate directories, then regenerate and rebuild a C++ consumer.

3. 3

   Reproduce the lifetime boundary

   Test Auto attachment on a movable receiver and explicit Hit Component attachment where used. Let Life Seconds, Fade Start Delay, and Fade Duration complete.

4. 4

   Verify both outcomes

   The receiver Actor must survive while the Footstep decal Component fades and expires normally.

• 2.11.2 release note →
• Clean installation procedure →

07

Wrong footwear imprint or missing overlay#

Inspect the resolved profile source before changing texture orientation, materials, or audio budgets.

• Inspect On Footstep Resolved > Footwear Profile and Footwear Resolution Source.
• Confirm the equipment graph updates the same FootstepComponent that receives contacts.
• Clear a stale request or component override before testing provider output.
• Call Refresh Footwear Provider only after adding, removing, or renaming provider components at runtime.
• Validate that the matching imprint route starts at 0 and has a positive-weight texture.
• For an immediate imprint, enable Decal in the resolved payload and configure the exact Immediate Footwear Imprint texture and optional mirror parameter names.
• For a transferred imprint, configure the corresponding Footwear Texture Parameter Name and optional mirror parameter on the source Surface Transfer.
• Confirm every selectable base material samples the configured Texture2D parameter and uses its mask or alpha in Opacity.
• For a shared right-foot texture, mirror only the left route; separate left/right textures normally disable mirroring.
• For audio, enable Play Overlay and a usable weighted payload, then inspect both profile and world audio budgets.

08

A decal clips, floats, disappears, or lands on the wrong layer#

Separate gameplay routing, geometric placement certification, projector coverage, and rendered-pixel visibility before changing offsets or trace distances.

1. 1

   Reproduce one receiver

   Use one source, one destination, deterministic yaw, one material, and one contact. Enable Profile Debug only for the capture.

2. 2

   Confirm immutable gameplay identity

   Verify the Ground Hit component, Physical Material, Physical Surface, and normal. Placement never changes these routing facts.

3. 3

   Read the placement outcome

   A successful geometric certificate proves the resolved point is inside the final projector; it does not prove that the receiver material renders a visible pixel.

4. 4

   Classify the central failure

   Distinguish invalid receiver or hit, provider rejection or invalid output, disabled correction, no hit inside the envelope, rejected candidates, query exhaustion, or a full-trace hit beyond the envelope.

5. 5

   Use area support only for a footprint

   Enable Footprint Area only when opaque content substantially occupies the authored Y and Z bounds. Insufficient, incompatible, ambiguous, or out-of-projector support must remain rejected.

6. 6

   Author the smallest correction

   Prefer an exact-material or surface receiver override for measured clearance or envelope differences. Use a provider for WPO, procedural displacement, missing complex query geometry, or another authoritative render-facing surface.

7. 7

   Validate pixels separately

   After placement succeeds, check Deferred Decal domain, receiver DBuffer response, material opacity, orientation, source exclusion, render path, and target RHI.

• Receiver projection authoring →
• Provider interface contracts →

09

A transferred decal appears on the foot or body#

Verify material connectivity, renderer prerequisites, the complete presentation snapshot, and renderer-state ownership independently.

• Confirm every selectable Surface Transfer material routes final opacity through MF_FSP_SourceExclusion and retains the three exact runtime parameter names.
• Set Custom Depth-Stencil Pass to Enabled with Stencil and keep r.CustomDepth.Order at 0 or 2.
• Leave source exclusion enabled and begin with the shipped 0.25 cm depth tolerance; increase it only after a diagnosed depth mismatch, within 0–5 cm.
• For a single-actor presentation, confirm every relevant mesh component is registered on the source actor. Visibility and current bounds do not remove a same-actor mesh from the snapshot.
• For multi-actor bodies or a source actor with unrelated meshes, implement FootstepSourceExclusionProvider and return the exact presentation set. Its result replaces automatic discovery.
• If an overlapping mark already holds a lease, confirm no external system changed the leased Custom Depth or Stencil values. A changed tuple correctly rejects a new mark and is preserved on final cleanup.
• Validate source isolation and complete receiver pixels on the production RHI. CPU state and material parameters cannot prove per-pixel Custom Depth and Stencil provenance.

• Source exclusion setup →
• Runtime-owned decal parameters →

10

The Surface Impression field does not affect the material#

Check request admission, receiver routing, material binding, field sampling, and mesh response in that order.

1. 1

   Confirm submission

   Enable the payload, supply a project-owned mask or usable footwear imprint, match Receiver Channel exactly, and inspect Surface Impression admission or rejection counters.

2. 2

   Confirm receiver ownership

   Place the contact within Field Extent and Plane Acceptance Distance, align local XY to the surface, and satisfy Minimum Surface Normal Dot.

3. 3

   Confirm explicit binding

   Call Bind Primitive Component or opt into tagged owner binding. Verify the material slot still contains the receiver-owned dynamic instance.

4. 4

   Confirm the three runtime parameters

   Keep FSP_SurfaceImpressionTexture, FSP_SurfaceImpressionWorldToUV0, and FSP_SurfaceImpressionWorldToUV1 unchanged and sample field red through the coverage function.

5. 5

   Refresh old local copies

   If a project copied the Surface Impression function or master before 2.11.1, replace or recreate that copy so the scaled-row field-normal precision correction is present.

6. 6

   Separate field from geometry

   Tint, normal flattening, and roughness can respond without dense geometry. WPO requires adequate vertices and target-specific Nanite settings; collision and navigation never deform.

• Surface Impression setup →
• Receiver function reference →
• Material parameter reference →

11

Dedicated server or remote actor is silent#

Silence can be the intended local-cosmetic network policy rather than a missing RPC.

12

Data Validation or packaging fails#

Correct the exact authored property or release gate instead of accepting a partial artifact.

• Fix missing Surface Data, empty sockets, non-finite or negative values, inverted ranges, and duplicate keys.
• Disable unfinished channels or provide a non-null positive-weight resource.
• Correct transfer event keys, emission bounds, expiry, intensity, Deferred Decal domains, ordered stages, route identities, and configured material parameters.
• Correct footwear stage order, duplicate contact or audio routes, unusable texture variants, enabled-but-empty overlays, and invalid immediate or transfer material parameter bindings.
• When replacing a source plugin, close the editor, replace the complete FootstepSystem folder, remove only that copied plugin's stale Binaries and Intermediate directories, regenerate C++ project files, and rebuild.
• Verify the descriptor is at Project/Plugins/FootstepSystem/FootstepSystem.uplugin; an accidentally nested FootstepSystem/FootstepSystem path will not load correctly.
• Validate the complete fourteen-asset plugin payload, then validate every project-owned Data Asset and material copy.
• Compile all three Material Functions, all three masters, and all five instances on every shipping RHI; shader compilation does not replace visual acceptance.

13

Prepare a minimal support package#

A reproducible, scoped report gives support enough evidence to distinguish integration, authoring, renderer, and runtime defects without exposing the customer's project.

1. 1

   State the environment

   Record Footstep Studio version, exact Unreal Engine version, target platform, RHI, build configuration, and whether the case occurs in Editor, PIE, Standalone, or packaged output.

2. 2

   Describe one expected and actual result

   Name the trigger path, contact, event, surface, footwear source, receiver, and the first frame or contact where behavior diverges.

3. 3

   Include the stable contract

   Provide Return Value, Out Reject Reason, the relevant Out Context fields, and a short scoped counter capture. Include only the smallest relevant LogFootstepSystem excerpt.

4. 4

   Attach authored settings safely

   Provide redacted screenshots or exported values for the relevant Profile, Surface Data, Footwear Profile, receiver, material parent, and project renderer settings. Do not send licensed third-party assets or private repository credentials.

5. 5

   Reduce the reproduction

   Use one actor, one contact, one surface, and one effect channel where possible. State whether the issue reproduces with a duplicated neutral template and whether Data Validation is clean.

6. 6

   Restore production diagnostics

   After capture, disable Profile Debug, rejected-request logging, rejected-event broadcasts, and runtime stats.