Character Foot Effects

Export

Use Character Foot Effects to detect each step, raycast to the ground below it, and let the Surface System choose the audio, decal, particle, or other response for the material under the character.

Before you begin

Set up one complete footstep response before tuning detection:

  1. Open Tools > Opsive > Ultimate Character Controller > Setup Manager.
  2. On Scene, under Manager Setup, select Add Managers. Confirm the scene’s Game object has Surface Manager, Decal Manager, and the shared Object Pool.
  3. In the Project window, choose Assets > Create > Opsive > Ultimate Character Controller > Surface Impact, save the asset as Footstep, and review Surface Impacts.
  4. Choose Assets > Create > Opsive > Ultimate Character Controller > Surface Effect for each response, such as wood audio, metal audio, a dust particle, or a footprint decal. See Surface Effects.
  5. Select each Surface Type. Add an Impact Effects element, assign Footstep to Surface Impact, and assign that material’s response to Surface Effect.
  6. Give each test floor collider a Surface Identifier, assign its Surface Type, and leave Allow Decals enabled only where a footprint decal is appropriate.
  7. Confirm the character has Ultimate Character Locomotion, Character Layer Manager, an Animator Monitor, and an Animator before adding foot effects through Character Manager.

The detector and Surface System are separate. A correctly timed step can still be silent when its Surface Impact, detected Surface Type, or mapped Surface Effect is missing.

Add Character Foot Effects

  1. Open Tools > Opsive > Ultimate Character Controller > Character Manager.
  2. Assign the scene model for a new character, or assign the Ultimate Character Locomotion root to Character for an existing character. Verify every Character Model row and its Animator Controller.
  3. Enable Foot Effects. It starts enabled for a new character.
  4. Select Build Character for a new character or Update Character for an existing character.
  5. Select each animated model below the character root. Character Manager adds Character Foot Effects to the same GameObject as its Animator Monitor.
  6. For a Humanoid Animator, verify that Feet references the left and right toe bones when available, otherwise the foot bones. The builder flips the generated right-foot entry and, when a foot has no Audio Source, adds one with Volume 0.4, Spatial Blend 1, and Max Distance 20.
  7. For a Generic Animator or custom rig, assign the contact transforms manually. Character Manager cannot infer non-humanoid feet.
  8. Expand Character Foot Effects > Footprint, assign the Footstep Surface Impact, select Footstep Mode, and tune the fields for that mode.

Character Foot Effects starts with Body Step as the serialized mode. Its released field defaults are:

Field Default Purpose
Surface Impact None Identifies the footstep when Surface Manager chooses a response.
Footstep Mode Body Step Chooses how an automatic step is detected.
Feet None Holds the contact Transforms. Character Manager initializes two entries only when it can resolve a Humanoid head and foot or toe bones.
Foot Offset 0.11 Extends the downward ground raycast. It is not the Body Step height threshold.
Move Direction Frame Count 7 Sets the accumulated up/down sample threshold in Body Step mode, adjusted by character and global time scale. Reversing direction does not reset the counters.
Min Trigger Interval 0.1 Prevents Trigger mode from accepting another step too soon.
Require Movement Enabled Makes Trigger mode ignore contact while horizontal local velocity is nearly zero.
Require Alternating Feet Enabled Makes Trigger mode reject the same foot twice in succession.
Fixed Interval 0.3 Sets the time between Fixed Interval step groups while grounded and moving.
Min Bob Interval 0.2 Sets the minimum time between Camera Bob steps.

Choose how a step is detected

Mode Use it when How released Version 3.2.0 detects a step
Body Step Animated feet make dependable contact and exact left/right timing matters. While the character is grounded and moving, it watches each configured foot’s vertical motion. A descending foot can step when either its upward or downward sample count since the last accepted step exceeds Move Direction Frame Count divided by character and global time scale, and it is not the last accepted foot. Direction reversals do not clear the counts; an accepted step clears all feet’s counts.
Trigger Physical foot contact is more reliable than animation motion. A Footstep Trigger on the contacting foot calls Character Foot Effects from OnTriggerEnter. Min Trigger Interval, Require Movement, and Require Alternating Feet filter the call. The Feet array is not used.
Fixed Interval A steady cadence is more important than exact contact. While grounded and moving, it cycles the configured foot groups every Fixed Interval. The group origin is raycast even when that particular foot is not touching the ground.
Camera Bob A first-person view has a reliable vertical bob. After a look source is attached, it detects the low point where the view changes from descending to ascending, then cycles a foot group. Min Bob Interval suppresses close repeats.
None Project code or animation events own the timing. No built-in automatic detector runs. Use a small relay to call TriggerFootStep or FootStep; an animation-event mode is not exposed in this Inspector.

All four automatic routes still end with the same ground raycast and Surface System lookup. Body Step does not compare the foot’s height with Foot Offset. The offset only increases how far the final ray can reach below the selected origin.

Configure Trigger mode

For each contacting foot:

  1. Add a Collider sized around the contact area and enable Is Trigger.
  2. Add Footstep Trigger to the same GameObject.
  3. Set Flip Footprint on the side that needs a mirrored decal.
  4. Ensure Unity can produce OnTriggerEnter for the foot and floor collider. A Character Manager build supplies the character root’s kinematic Rigidbody; a manually assembled character still needs a valid Unity trigger/Rigidbody arrangement.
  5. Put the floor on a layer that is not the character’s layer, Water, or one of Character Layer Manager’s Invisible Layers. Both Footstep Trigger and the final ground ray use the derived IgnoreInvisibleCharacterWaterLayers mask.
  6. Enter Play Mode and confirm each contact passes Require Movement, Require Alternating Feet, and Min Trigger Interval.

Footstep Trigger ignores contacts outside the character’s IgnoreInvisibleCharacterWaterLayers mask. It also suppresses steps for three fixed-update intervals after an immediate transform change, which prevents a teleport from creating a false contact.

Map feet, sides, and groups

Each Feet entry contains:

  • Object: the Transform whose position becomes the step raycast origin;
  • Group: the group used by Fixed Interval and Camera Bob; every Transform in the active group steps together, then the component advances to the next group; and
  • Flipped Footprint: mirrors the footprint decal on its local X axis, normally for the right side.

Body Step evaluates feet individually and ignores Group. Trigger mode receives its Transform and flip setting from Footstep Trigger, so it ignores the Feet list entirely.

For a biped with group-driven placement, place the left foot in group 0 and the right foot in group 1. For a quadruped, group the contacts that should land together. Keep group numbers contiguous from 0; an unused group produces an interval with no step.

At Awake, a null or zero-length Feet list creates one fallback group at the Character Foot Effects GameObject. That fallback is useful for a centered Fixed Interval or Camera Bob sound, but not for separate left/right footprints. It does not make Body Step valid: an empty list detects no feet, and a null list on a non-humanoid can fail when Body Step evaluates it.

Released Version 3.2.0 displays Feet only while Body Step is selected even though Fixed Interval and Camera Bob reuse serialized groups. To configure those origins in the Inspector, select Body Step, edit Feet, then switch to the intended group-driven mode before saving.

The released footprint direction is the forward direction of the GameObject that owns Character Foot Effects. A Feet Object supplies position, not facing. Align the model/component transform with the character’s forward direction, then use Flipped Footprint for side mirroring.

Choose the surface response

Keep one Footstep Surface Impact and vary the Surface Effect by Surface Type:

Desired result Configure it on the mapped Surface Effect
Positional footstep sound Under Audio, assign Audio Config or leave it empty and configure Audio Clips, Min/Max Volume, Min/Max Pitch, Random Clip Selection, and Min Audio Clip Frame Interval. The footprint path plays audio on the foot originator.
Dust, splash, or debris Under Spawned Objects, assign a pool-safe Object and set Probability. The effect spawns at the ground hit.
Left/right footprint Under Decals, assign Prefabs, set Min Scale, Max Scale, and Allowed Decal Edge Overlap, enable Allow Decals on the Surface Identifier, and configure the foot’s flip setting.
Surface-specific combinations Map the same Footstep Surface Impact to a different Surface Effect in every Surface Type.
A safe response for an unidentified floor Surface Manager starts with Fallback Surface Impact and Fallback Surface Type unassigned, while Fallback Allow Decals starts enabled. Assign both fallback assets deliberately. If a fallback must never leave a decal, map it to a Surface Effect whose Prefabs list is empty; the released later missing-pair fallback path does not always apply Fallback Allow Decals.

New Surface Type assets serialize Allow Footprints as enabled, which selects the direction-aware footprint path. Released Version 3.2.0’s custom Surface Type inspector does not draw that field. Use the visible Surface Identifier > Allow Decals setting and the Surface Effect’s Decals > Prefabs list for normal editor authoring. A legacy or custom-authored Surface Type with the hidden field disabled uses the regular response path instead; it still plays audio, spawns objects, applies a State, and can request an ordinary decal.

How it runs

  1. At initialization, the component builds its foot groups. Body Step and Fixed Interval run from FixedUpdate; Trigger waits for Footstep Trigger; None waits for project code; and Camera Bob begins after an ILookSource attaches.
  2. For a locally controlled character, Body Step, Fixed Interval, and Camera Bob return unless Ultimate Character Locomotion reports both Grounded and Moving. Trigger mode is contact-driven and applies its own optional movement filter instead.
  3. The selected placement mode accepts a foot or foot group only while its direction, interval, bob, or contact rules pass.
  4. FootStep casts from 0.2 units above the selected Transform, down along the character model’s local down direction. The base distance is 0.21 + Foot Offset, with additional reach for vertical movement. Trigger colliders are ignored.
  5. Surface Manager resolves the hit collider’s Surface Type and pairs it with the configured Surface Impact.
  6. With the normal new-Surface-Type default, Surface Effect spawns objects, plays audio on the foot originator, applies its optional State, and asks Decal Manager for a direction-aware footprint. A custom type whose hidden Allow Footprints value is false uses the regular response path.
  7. Spawned feedback objects and decals use the shared object pool. The surface and decal policies decide whether a footprint decal is permitted.

FootStep returns true when its ground raycast hits. It ignores the Boolean returned by Surface Manager, so an accepted step can update the last-foot and interval state even when no Surface Effect resolves. Diagnose detection and surface mapping as separate checkpoints.

Editor checkpoint

Before Play Mode, confirm that:

  • Character Manager’s Foot Effects option produced one Character Foot Effects component for each intended animated model;
  • Generic and custom rigs have explicit contact Transforms;
  • the Footstep Surface Impact is assigned and appears once in every relevant Surface Type’s Impact Effects list;
  • every test floor resolves its intended Surface Type directly or through an intentional fallback;
  • Body Step feet move vertically and have sensible left/right flip settings;
  • Trigger feet have working trigger Colliders and Footstep Trigger components;
  • Fixed Interval or Camera Bob groups are contiguous, alternate as intended, and do not fall back accidentally to the model origin;
  • Foot Offset is only large enough to reach the expected floor below each origin;
  • footprint receivers use the intended Allow Decals value, their Surface Effects contain the intended decal prefabs, and any no-decal fallback effect has an empty decal list;
  • every decal or spawned-effect prefab is configured for pooling and has a bounded lifetime.

Verify on several surfaces in Play Mode

  1. Place adjacent wood and metal floor colliders. Give each a distinct Surface Type and map the same Footstep impact to clearly different audio. Add a third test floor whose Surface Type has another Impact Effects entry but no matching Footstep pair so the configured fallback can be tested without editing an asset during Play Mode.
  2. Walk entirely on wood. Confirm the chosen mode produces one sensible step per intended contact and only the wood response plays.
  3. Cross slowly onto metal. Confirm the response changes according to the surface directly below each accepted foot, not the character root.
  4. Add distinct left and right footprint decals. Confirm their positions alternate, face with the character model, and the configured side is mirrored.
  5. Test a small step, slope, and descending motion. Increase Foot Offset only if the ground ray misses; do not use it to retime Body Step.
  6. For Trigger mode, stop moving with one trigger touching the floor, then start again. Confirm Require Movement, alternating-foot filtering, and the minimum interval prevent duplicate contacts.
  7. For Fixed Interval or Camera Bob, compare walking and running States with different interval presets. Confirm the cadence changes without double-playing a foot group.
  8. Walk onto the intentionally unmapped floor. Confirm Surface Manager uses the intended fallback and that a no-decal fallback remains decal-free.
  9. Repeat steps rapidly and watch the Hierarchy and audio output. Pooled objects should return correctly, decal limits should hold, and Min Audio Clip Frame Interval should suppress any unacceptable same-frame duplicates.

Troubleshooting and released-Version-3 limitations

Symptom Check Fix
Character Foot Effects was not added. The selected model has no Animator Monitor/Animator, or the Character Manager update did not include Foot Effects. Add the required animated-character components, enable Foot Effects, and use Update Character. For a Generic rig, verify and configure the component manually.
Body Step never fires or logs a null-reference exception. The character is not grounded and moving, Feet is empty or null on a non-humanoid, a Feet Object is null, or the accumulated vertical-motion counts have not exceeded the threshold. Assign every real contact Transform, remove null elements, and tune Move Direction Frame Count while observing the animated bones. Do not rely on the group fallback for Body Step.
Changing Foot Offset does not retime Body Step. The offset controls the final raycast distance, not the Body Step motion threshold. Tune the animation/mode and Move Direction Frame Count for timing; use Foot Offset only for ray reach.
Trigger mode never fires. The foot lacks an Is Trigger Collider or Footstep Trigger, the Rigidbody arrangement cannot produce OnTriggerEnter, the floor is on Water, the character layer, or an Invisible Layers entry, or a movement/alternation/interval rule rejects it. Correct the Collider, Rigidbody, and layer setup, then temporarily relax one Trigger filter at a time.
A step is detected but no sound or particle plays. FootStep can succeed from a ray hit even when Surface Manager cannot resolve a valid impact/type/effect pair. Verify the assigned Surface Impact, detected Surface Type, explicit Impact Effects mapping, and fallback separately.
Sound plays but no footprint appears. The receiver disallows decals, Decals > Prefabs is empty, the decal prefab lacks the mesh/renderer data Decal Manager needs, the edge test rejects it, or a legacy/custom Surface Type has hidden Allow Footprints disabled. Enable Allow Decals, assign a valid decal prefab, and test away from edges. New Surface Types default to the footprint path; use a project editor tool when an older asset’s hidden value must be changed.
Both footprints appear together or at the model center. Group assignments are the same, or Feet is empty and the component created one fallback group. Configure separate left/right groups under Body Step, then restore Fixed Interval or Camera Bob.
Fixed Interval or Camera Bob skips a cadence with no response. The serialized group numbers contain a gap, so the active group can be empty. Edit Feet while Body Step is selected and renumber the groups contiguously from 0, then restore the intended mode.
Footprints face sideways. Released Version 3.2.0 uses the Character Foot Effects GameObject’s forward direction, not the foot Transform’s forward direction. Align the model/component transform with character forward and use the flip setting only for mirroring.
Camera Bob produces no steps. No look source is attached, the view has no vertical bob, the character is not grounded/moving, or Min Bob Interval is too large. Attach the camera/look source, enable a visible bob, and verify the locomotion conditions before reducing the interval.
Trigger steps repeat or disappear after teleporting. The minimum interval, alternating-foot filter, or built-in post-teleport suppression rejected the contact. Test after three fixed updates, verify each Footstep Trigger passes the correct foot Transform, and tune the trigger filters.
Footsteps are too loud or effects accumulate. Several feet share a group, two detectors are active, audio has no frame interval, or spawned feedback does not return to the pool. Keep one timing route per model, correct the groups, configure Min Audio Clip Frame Interval, and use pool-safe finite effects.
An animation event cannot select Footstep mode. Released Version 3.2.0 has no Animator Event entry in Footstep Mode. Select None and use a project relay that calls TriggerFootStep or FootStep.
A fallback footprint appears even with Fallback Allow Decals disabled. The detected impact and type existed, but their pair was missing; Version 3.2.0’s later fallback-type path does not mark that lookup as a fallback for the decal check. Add the explicit pair, or use a fallback Surface Effect with an empty Decals > Prefabs list.

Developer reference

CharacterFootEffects is in Opsive.UltimateCharacterController.Character. Its public configuration includes FootstepMode, SurfaceImpact, Feet, MoveDirectionFrameCount, FootOffset, MinTriggerInterval, RequireMovement, RequireAlternatingFeet, FixedInterval, and MinBobInterval.

TriggerFootStep(Transform, bool) applies movement, interval, alternating-foot, and teleport filters before calling the virtual FootStep(Transform, bool). FootStep bypasses those Trigger filters, performs the ground raycast, and forwards it to the footprint overload of SurfaceManager.SpawnEffect. Override FootStep only when the project needs a different contact query or additional bookkeeping.

There is no built-in Animator Event mode. For deliberately authored animation timing, select None and put a small relay on the Animator GameObject:

using Opsive.UltimateCharacterController.Character;
using UnityEngine;

public sealed class FootstepAnimationRelay : MonoBehaviour
{
    [SerializeField] private CharacterFootEffects m_FootEffects;
    [SerializeField] private Transform m_LeftFoot;
    [SerializeField] private Transform m_RightFoot;

    public void LeftFootstep()
    {
        m_FootEffects.FootStep(m_LeftFoot, false);
    }

    public void RightFootstep()
    {
        m_FootEffects.FootStep(m_RightFoot, true);
    }
}

Add LeftFootstep and RightFootstep Animation Events to the clips at contact. This relay calls FootStep, so each event still performs the ground raycast but bypasses the Trigger-only filters. Call TriggerFootStep instead when the animation events should obey Require Movement, Require Alternating Feet, Min Trigger Interval, and teleport filtering. Those fields are hidden while None is selected; configure them while Trigger is selected, then switch back to None.

SurfaceType.AllowFootprints is public read-only at runtime and its backing m_AllowFootprints field defaults to true, but the released custom inspector draws only Impact Effects. A project that must change an existing asset’s hidden value should do so through a controlled editor tool using SerializedObject, then verify whether the direction-aware or regular decal path is intended.

The component listens for OnCharacterAttachLookSource, OnCharacterChangePerspectives, OnCharacterMoving, and OnCharacterImmediateTransformChange to prepare Camera Bob data, delay the first moving step, and suppress teleport contacts. It does not publish a separate footstep event.

Footstep feedback is transient and is not saved. The component does not send a footstep network message. With the UCC multiplayer define enabled, non-authoritative, non-local remote characters gate the FixedUpdate-driven modes on interpolated movement plus a ground raycast; each client still needs matching Surface System assets and pooled feedback. Trigger or project-invoked calls are not sent by Character Foot Effects itself.