Effects

Export

Use a Character Effect for short, lightweight feedback such as a camera shake, item jolt, stomp, or sound. Effects run alongside locomotion without driving the Animator; use an Ability when the behavior needs animation, input, interruption rules, or networked gameplay ownership.

Add a damage-feedback effect

This example starts a Shake whenever Character Health reports damage:

Select the character root and open Ultimate Character Locomotion > Effects.
Select the add (+) button and choose Shake.
Leave the row’s Enabled toggle on. Select the row to edit the effect.
Choose Target values. For presentation-only damage feedback, Camera and Item avoid adding force to the character. The released default enables Camera, Item, and Character.
Adjust Force and Duration. Their defaults are (0.4, 0.4) and 7 seconds.
Select Character Health and set Damaged Effect to Shake. Leave Damaged Effect Index at -1 to use the first Shake in the Effects list.
Enter Play Mode and damage the character once.

While the effect runs, its list label ends with (Active). The label should return to its normal name after Duration elapses.

Configure the Effects list

Ultimate Character Locomotion owns the list, initializes each effect, and updates active effects during the character update. Select an effect row to configure its shared settings and effect-specific fields.

Setting	Default	Use
Enabled	On	Allows the effect to start. Turning this off while the effect is active stops it.
Start When Enabled	Off	Starts the effect when its Enabled property changes from off to on during Play Mode. It does not mean "start when the scene loads."
State	Empty	Activates the named character state while the effect is active and deactivates it when the effect stops.
Inspector Description	Empty	Adds an editor-only note to the list label, which is useful when the same effect type appears more than once.
States	`Default`	Uses the standard State System list to change effect values while other states are active.

Duplicate effect types are allowed. Start Effect Index and Damaged Effect Index refer to the effect’s zero-based position in this list; -1 selects the first effect of the chosen type. After reordering effects, update every explicit index that points into the list.

Choose how the effect starts

Trigger	Setup	Stop ownership
Character damage	On Character Health, choose Damaged Effect and optionally Damaged Effect Index.	The chosen effect must stop itself or be stopped by code.
Ability start	Select an ability and choose Start Effect Name. Use Start Effect Index only when selecting a specific duplicate.	Stopping the ability does not stop its effect. Built-in timed effects stop themselves.
Runtime enable	Turn the effect’s Enabled property from off to on with Start When Enabled selected.	Turning Enabled off stops the active effect.
Script or custom system	Retrieve the effect from Ultimate Character Locomotion, then call `TryStartEffect` or `TryStopEffect`.	The calling system or the effect controls when it stops.

An effect cannot restart while it is already active. A start request also fails when Enabled is off or the effect-specific CanStartEffect check fails.

Included effects

The Included Effects section contains all three built-in Character Effects:

Effect	Best for	Important released defaults and requirements
Shake	Impacts, damage, explosions, or environmental vibration.	Targets Camera, Item, and Character; Force `(0.4, 0.4)`; Smooth Horizontal Force on; Vertical Force Probability `0.3`; Fade Out Duration `4`; Positional Factor `1`; Rotational Factor `3`; Duration `7`. At least one Target flag is required.
Boss Stomp	A repeated downward camera impulse.	Requires an attached Camera Controller. Positional direction is down with strength `0.5` to `1`; rotational direction is forward with strength `10` to `15`; Repeat Count is `0`; Repeat Delay is `1`. The initial stomp always occurs, so `0` produces one stomp and `-1` repeats until stopped.
Play Audio Clip	A sound tied to the character without an animation.	Audio Clip Set starts empty. Assign an Audio Config or at least one clip before using the effect. It stops after the returned Audio Source’s clip length.

Understand the runtime lifecycle

Ultimate Character Locomotion initializes every serialized effect and assigns its list index.
TryStartEffect rejects an active, disabled, or unavailable effect. A successful start adds it to the active list and calls EffectStarted.
Ultimate Character Locomotion calls Update on each active effect every character update.
The effect calls StopEffect, its owner calls TryStopEffect, or Enabled is turned off.
Ultimate Character Locomotion removes it from the active list and calls EffectStopped.

The base Effect type does not expose a dedicated start or stop UnityEvent, and the Ultimate Character Locomotion Events foldout has no Character Effect event. A custom effect can override EffectStarted and EffectStopped; call the base implementation so the configured State is activated and cleared.

Multiplayer considerations

Character Effects are not synchronized by Ultimate Character Controller. Replicate the gameplay event through the project’s networking layer, then start the corresponding visual or audio effect on the intended local player or observer.

Keep authoritative movement outside an effect. In particular, Shake > Target > Character adds force to locomotion, but that force is not network-owned or replicated by the Effect system. Camera and item feedback should normally run only for the client that owns or observes that presentation.

Released Version 3 limitations

The active-effect list assigns a one-based active index but uses it as a zero-based removal position. When effects overlap, stopping an effect other than the most recently started one can remove the wrong active entry and leave the stopped entry updating. Avoid overlapping Character Effects in released Version 3; if overlap is unavoidable, stop them in reverse start order.
Start When Enabled reacts only to a runtime transition of Enabled from off to on. An effect that begins the scene enabled does not start merely because this option is selected.
Play Audio Clip allows a start even when its Audio Clip Set produces no Audio Source. In that case it has no clip length with which to schedule its stop and remains active until stopped or disabled. Always assign playable audio and verify that the (Active) label clears.
An ability’s Start Effect Name starts the effect when the ability begins but establishes no stop relationship. Use a self-terminating effect or stop it explicitly.
Character Effects do not modify Animator parameters and have no built-in network synchronization. Use an Ability or another gameplay system when either behavior is required.

Check the editor setup

Before Play Mode, confirm:

the effect row is enabled and its Inspector Description clearly distinguishes any duplicates;
every explicit effect index still matches the intended row after reordering;
the chosen ability or Character Health trigger points to a type that exists in the Effects list;
Camera-targeted effects have a Camera Controller attached to the character; and
every timed custom effect has a definite stop path.

Verify in Play Mode

Trigger the effect once and confirm the intended row shows (Active).
Observe only the configured target: camera, item, character, or audio.
Confirm the effect clears its (Active) label at the expected duration or repeat count and that its configured State is no longer active.
Trigger it again after it stops. It should start normally; a request made while it is already active should be ignored.
In multiplayer, test the owner and a remote observer separately. Only instances explicitly triggered by the networking layer should show the effect.

Troubleshooting

Symptom	Check	Fix
The trigger does nothing.	Check the row’s Enabled toggle, selected effect type and index, and the effect-specific start requirement.	Enable the effect, correct the index, select at least one Shake target, or attach a Camera Controller for Boss Stomp.
Start When Enabled does not run at scene start.	Check whether Enabled actually changed from off to on during Play Mode.	Start the effect from an ability, Character Health, or code, or toggle Enabled at runtime.
An ability starts the effect but it continues after the ability stops.	Check whether the effect has its own duration, repeat limit, audio length, or custom stop call.	Configure a self-terminating built-in effect or stop it explicitly when the ability ends.
Play Audio Clip remains (Active) without sound.	Check whether Audio Clip Set returned a playable Audio Source.	Assign an Audio Config or clip, or stop the effect explicitly after a failed play request.
The wrong duplicate effect starts.	Compare Start Effect Index or Damaged Effect Index with the current Effects list order.	Set the zero-based list index, or use `-1` when the first effect of that type is intended.
One of several overlapping effects stops incorrectly.	Check whether effects were stopped in a different order from which they started.	Avoid overlap in released Version 3 or stop active effects in reverse start order.
A remote player does not show the effect.	Check whether the project’s network message starts it on that client.	Replicate the trigger and run the presentation locally; Character Effects are not synchronized automatically.

Developer details

Guard every lookup because TryStartEffect and TryStopEffect expect a non-null Effect reference:

using Opsive.UltimateCharacterController.Character;
using Opsive.UltimateCharacterController.Character.Effects;
using UnityEngine;

public static class CharacterEffectExample
{
    public static bool StartShake(GameObject character)
    {
        var locomotion = character != null ? character.GetComponent<UltimateCharacterLocomotion>() : null;
        var shake = locomotion != null ? locomotion.GetEffect<Shake>() : null;
        return shake != null && locomotion.TryStartEffect(shake);
    }

    public static bool StopShake(GameObject character)
    {
        var locomotion = character != null ? character.GetComponent<UltimateCharacterLocomotion>() : null;
        var shake = locomotion != null ? locomotion.GetEffect<Shake>() : null;
        return shake != null && shake.IsActive && locomotion.TryStopEffect(shake);
    }
}

For duplicate types, GetEffect<T>(index) uses the effect’s absolute list index. Calling Effect.StartEffect() and Effect.StopEffect() routes through Ultimate Character Locomotion so its active list stays informed.

A custom effect normally overrides EffectStarted, Update, and EffectStopped. This three-second camera pulse uses the Scheduler and cancels its pending event if stopped early:

using Opsive.Shared.Game;
using Opsive.Shared.Utility;
using Opsive.UltimateCharacterController.Character.Effects;

public class CameraPulseEffect : Effect
{
    private ScheduledEventBase m_StopEvent;

    protected override void EffectStarted()
    {
        base.EffectStarted();
        m_StopEvent = Scheduler.ScheduleFixed(3, StopEffect);
    }

    public override void Update()
    {
        if (m_CameraController != null) {
            m_CameraController.AddPositionalForce(SmoothRandom.GetVector3Centered(0.1f));
        }
    }

    protected override void EffectStopped()
    {
        Scheduler.Cancel(m_StopEvent);
        m_StopEvent = null;
        base.EffectStopped();
    }
}