Magic

Export

The Magic Action builds a spell from reusable casting, presentation, and impact modules. Use it for a Fire Wand projectile, a targeted effect, an area spell, a channeled beam, or a teleport instead of writing one item action for every spell.

Before you begin

Create the Character Item and add a Magic action through Tools > Opsive > Ultimate Character Controller > Item Manager. The magic anchor setup is useful when a spell has no visible held model.
Add or select the character’s Use item ability. Its Action ID must match this Magic Action’s ID, and its Slot ID must include the Character Item’s slot.
Add first- and third-person cast-origin transforms when effects should start from a hand, wand tip, or staff. Character As Cast Origin can be used for a body-centered spell.
Add the required Animator states or use tested durations for the Use and cast event triggers. See Animation Event Trigger.
If the spell spends mana, create the Attribute on the character before configuring Character Use Attribute. See Attributes.

Build a Fire Wand spell

In the Item Manager, add a Magic action named Fire Wand, then select Build Item or Update Item.
Select the generated Character Item. Give the Magic Action a unique ID, then point the character’s Use ability at that value. Released Version 3 leaves an Item-Manager-created Magic Action at the default ID 0, unlike the other generated actions.
In Trigger Action Module Group, add Simple and make it the first enabled Trigger. A generated Magic Action does not receive a Trigger automatically.
In Usable Action Module Group, add Character Use Attribute when the spell should spend mana. Set Character Use Attribute Name to the exact character Attribute name and choose the amount spent by one use cycle.
In Caster Module Group, add Simple Caster. Leave Direction at Forward for a wand projectile, keep Use Look Source enabled, and assign the first- and third-person Cast Origin values. Only the first enabled Caster is active.
In Begin Module Group, optionally add a short Play Audio Clip, Spawn Particle, Fade Materials, Toggle GameObject, or Generic Item Effects row for the wind-up. These rows start with item use and stop when the Caster enters Casting, before any Start Cast Event Trigger wait.
In Cast Effects Module Group, add Spawn Projectile. Assign a pooled projectile prefab with a Projectile component, then set its Speed, offsets, and Parent To Origin choice. The default speed is 1, so tune it for the scene scale.
In Impact Module Group, add Generic Magic Impact Module. Its released-Version-3 defaults include the standard conditions and a default damage Impact Action group; replace or tune those actions for the spell.
In End Module Group, add only feedback that belongs after casting, such as a stop sound or object toggle. End modules start when casting stops and stop when item use ends.
Set Use Complete Event after the cast-start wait and required Cast Effect work. Its inherited 0.05-second duration can cancel a delayed Single cast before the effect runs. Use a correctly placed completion animation event or a tested duration, then save the prefab.

The legacy Inspector below shows a Teleport example with Simple Trigger and Caster modules, Begin feedback, three Cast Effects, and an End fade. Empty Impact and Extra groups are valid when the spell does not use them.

Teleport Magic Action with Simple Trigger and Caster modules, Begin particle fade and audio modules, Teleport particle and audio Cast Effects, and an End fade

Understand the module groups

Group	Active-module rule	Responsibility
Trigger	First enabled module	Decides whether one input performs a simple, repeat, burst, charged, or combo use cycle.
Usable	Every enabled compatible module	Applies shared item effects, Attributes, aiming substates, States, and other Usable Action behavior.
Caster	First enabled module	Creates the cast origin, direction, target list, timing, and stop behavior. Released Version 3 includes Simple Caster.
Begin	Every enabled module	Runs presentation while the spell is winding up.
Cast Effects	Every enabled module	Produces the spell result and reports when its work is complete.
Impact	Every enabled module	Responds when a Cast Effect supplies an impact. Adding an Impact module does not detect a hit by itself.
End	Every enabled module	Runs presentation between the end of casting and the end of item use.
Extra	Every enabled module	Extension point for project-specific Magic modules. Released Version 3 has no concrete built-in Extra module.

Module IDs identify rows for States and network bitmasks; the Magic Action ID is the value selected by the Use ability. Keep action IDs unique across one Character Item.

How it runs

Magic Action lifecycle from Start Use and Begin Cast through Cast Effects, completion, End Cast, and Stop Item Use

Start Use puts the Magic Action in its Begin phase and starts every enabled Begin module using preview cast data.
The shared Use and Trigger timing releases the action. Simple Caster checks grounding and target validity, creates MagicCastData, enters the Casting phase, and stops the Begin modules.
Start Cast Event Trigger releases every enabled Cast Effect. Each effect moves through pending, processing, and complete states while the Caster updates it.
A Physics Cast, Target Impact, projectile, or another impact-producing effect sends its hit through every enabled Impact module.
When the effects finish during the normal cast path, the Caster uses its stop timing, enters End, and starts the End modules. The shared Use Complete Event is independent: it can stop/reset effects before that path completes, including during a start delay.
Item-use completion stops and resets the Cast Effects. Stop Use then stops the End modules and clears the current use cycle.

Begin and End use the same module types, but they run in separate phases. Keep the wind-up in Begin and recovery or cleanup in End so an interrupted spell has an understandable result.

Choose the Simple Caster behavior

The action is invalid until at least one Trigger and one Caster are enabled. Simple Caster has the following important released-Version-3 defaults:

Field	Default	Choose this based on
Start Cast Event Trigger / Repeat Cast Event Trigger / End Cast Event Trigger	Timed, `0` seconds	Whether an Animator event or duration controls each transition. The matching events are `OnAnimatorStartCast`, `OnAnimatorRepeatCast`, and `OnAnimatorEndCast`.
Character As Cast Origin	Off	Off uses the current perspective’s Cast Origin and falls back to the character transform when it is unassigned. On always uses the character transform.
Require Grounded	On	Whether the spell may start in the air.
Direction	Forward	How the Caster creates its target position.
Use Look Source	On	Whether Forward casting follows the camera/look source instead of character forward.
Max Distance	`100`	Forward reach, Indicate reach, and the Target search radius.
Radius	`0.1`	Sphere-cast thickness for Forward and Indicate.
Max Angle	`30` degrees	Total forward target cone; the runtime checks half this value to either side.
Max Collision Count / Max Target Count	`100` / `1`	Search capacity and the maximum number of selected targets.
Use Type	Single	Single permits stopping without waiting for Cast Effect completion. Continuous uses its minimum-duration and stop rules. Author Use Complete Event timing explicitly.
Minimum Continuous Use Duration	`1` second	Minimum hold time for Continuous. Use `-1` to allow the first stop request immediately, or a positive duration.
Continuous Cast	Off	Whether completed Cast Effects continue receiving updates and can repeat during one cast.
Interrupt Source	None	Optionally force-stop on character movement, damage, or both. Jump and Fall count as movement.
Cast Update On Cast	Off	Off begins normal effect updates on the next item update; on performs the first update as soon as the start-cast event occurs.

Choose the direction by the player-facing result:

Direction	Use it for	Runtime result
None	A body-centered aura or item-only effect	Uses character forward and position without searching for a surface or target.
Forward	Fireballs, rays, and look-directed spells	Sphere-casts from the look or character direction. With no hit, it uses the point at Max Distance.
Target	Lock-on or multi-target spells	Searches inside Max Distance, sorts candidates toward character forward, and supplies up to Max Target Count colliders. See the released-Version-3 targeting limitation below before using this for strict selection.
Indicate	Ground markers and teleport destinations	Requires a surface hit. An optional Surface Indicator follows the point and is hidden for remote non-spectators. Network spectators follow the selected perspective.

For a single Fire Wand projectile, keep Use Type at Single and Continuous Cast off. For a held beam, use Continuous and choose a positive minimum duration or -1. Review the Continuous Cast timing limitation below before enabling it; use a custom Caster or effect with an explicit interval guard when a reliable repeat rate is required. A Character Use Attribute charge occurs at the shared Use stage; it does not independently charge every Cast Effect update.

Choose Cast Effects

Every Cast Effect has Delay 0, Initial Delay -1, and, for multi-target effects, Allow Multi Target enabled by default. The runtime behavior is:

On the normal update path, Initial Delay controls the first cast when nonnegative; -1 uses Delay. A separate repeat gate also runs on the first attempt with its last-execution timestamp initialized to -1. Early in a scene, a large Delay can therefore postpone the first attempt even when Initial Delay is 0.
The normal repeat gate uses Delay after completion: negative disables normal repeats, 0 allows the next eligible update, and positive waits that duration.
Continuous Cast also updates processing and completed effects in LateUpdate without these delay checks. A completed effect such as Spawn Projectile can run again each LateUpdate despite a positive or negative Delay. Do not use these fields as a guaranteed repeat-rate limit with Continuous Cast. Keep it off for a single result, or implement timing guards in a custom effect/Caster.

Released Version 3’s serialized tooltips describe Delay and Initial Delay in the opposite order. Configure them according to the runtime behavior above.

Cast Effect	Use it for	Important choices and defaults
Physics Cast	Immediate ray, sphere, or area hits	Mode defaults to Raycast; Distance and Radius both default to `5`; Max Collision Count is `50`; Allow Self Impact is off. Each hit enters the Impact group.
Play Audio Clip	Cast-stage audio, including a loop	Play At Origin is on, Loop is off, and fade-out defaults to `0.1` seconds in `0.05` steps.
Spawn Object	A temporary prop or persistent spell object	Parent To Origin is off and Destroy On Stop is on.
Spawn Particle	A burst, beam, trail, or perspective-aware visual	Can parent to the origin, project direction, clear its parent on stop, scale a renderer to target distance, and fade in or out.
Spawn Projectile	A moving projectile that reports collisions	Assign a prefab with `Projectile`; Speed defaults to `1` and Parent To Origin is off. Projectile impacts enter the Magic Impact group.
Start Effect	A Character Effect that should begin with a cast	Select the Effect and optionally enable Stop Effect so cast cleanup stops it.
Target Impact	Raycast again in the cast direction and apply the Impact group to the hit	Casts from just behind Cast Position along Direction, using Detect Layers and an unlimited distance. It does not directly use the selected target collider or enforce the Caster’s maximum distance.
Teleport	Move the character to an indicated valid surface	Rejects slopes beyond the locomotion slope limit and locations without standing space. Snap Animator is off.
Cast Item Effects	Invoke a reusable Item Effect group	The released module does not initialize its contained Item Effect group. Effects requiring item/character references can fail even with valid Inspector assignments. Use an initialized custom wrapper, or a Begin/End Generic Item Effects module when its lifecycle matches the effect. The block option alone does not repair initialization.
Magic Cast Effect Nester	Run a combination in parallel or sequence and repeat the combination	Parallel is the default; Sequential is off and Repeat Count is `0`. Nested effects also require the timing and completion checks described above.

Use Generic Magic Impact Module to run Impact Action Conditions, the successful Impact Action group, or a separate failure group. Use Ricochet Impact when the same cast should find another nearby object and immediately recast its enabled effects from the ricochet data.

Choose Begin and End feedback

Begin and End both accept every released-Version-3 MagicStartStopModule:

Module	Use it for	Important behavior
Generic Item Effects	Local item-side presentation or a UnityEvent	On Start is on and On Stop is off by default.
Fade Materials	Fade character renderers during a phase	Targets `_Color` by default, fades toward alpha `0` at speed `0.02`, and offers Revert On Stop. Once the fade has completed, its Stop path returns early and does not revert; arrange explicit restoration when that case must be supported.
Play Audio Clip	Wind-up or recovery audio	Play At Origin is on and Loop is off. Stop ends the active AudioSource.
Spawn Particle	Spawn one phase-start particle	Can parent the particle to the cast origin, but its Stop callback does not stop, unparent, or return the object; plan explicit particle cleanup.
Toggle GameObject	Show or hide perspective objects during the phase	Choose Toggle On Start, Toggle On Stop, or both; each selected callback inverts the current active state. The row’s On value is used for reset/perspective handling, not as the callback’s absolute on/off result.

Do not use the Start/Stop Spawn Particle module as the sole owner of a looping particle. Give the particle its own auto-stop and pool-return behavior, or use another module or project component that explicitly cleans it up.

Editor checkpoint

Before entering Play Mode, confirm that:

the Magic Action has a unique ID and the Use ability selects it;
the intended Trigger and Caster are the first enabled rows in their groups;
each perspective has a valid Cast Origin, or the character fallback is intentional;
Direction, grounding, layers, distance, target count, and surface indicator match the spell;
every Cast Effect has its required prefab, Effect, Item Effect group, audio, or other reference;
at least one impact-producing Cast Effect exists when the Impact group should run;
Animator event waits have matching events on the correct slot, or use tested durations; and
the mana Attribute exists on the owner read by Character Use Attribute or Use Attribute.

Verify in Play Mode

Equip the Fire Wand, select its Magic Action, expand Debug, and press Use once.
Confirm Begin feedback stops when Casting starts, before the start-cast event wait. Verify that the start-cast event releases one projectile before the configured Use completion.
Confirm mana decreases by the configured amount once and the projectile’s collision invokes the expected damage and surface response.
Watch the action move through Begin, Casting, and End. The phase field can remain End after Stop Use; it is not reset to None on that path. Verify actual effect cleanup separately, including completed Fade Materials restoration.
Switch perspectives and repeat. The projectile and feedback should use the matching first- or third-person origin without changing the gameplay target.
Test a miss, an obstructed target, an invalid teleport slope, an airborne start, movement interruption, and damage interruption for the settings that the spell enables.
For Continuous casting, hold longer than Minimum Continuous Use Duration and measure the actual repeat rate. Check for LateUpdate repeats bypassing Delay; when using a custom timing guard, verify it before testing release and cleanup.
In multiplayer, repeat the test as owner, server, and remote observer, including a multi-target cast.

Troubleshooting and released-Version-3 limitations

Symptom	Check	Fix
The generated Magic Action does nothing	Trigger and Caster groups	The Version 3 Item Builder creates the component but no starter modules. Add at least one enabled Trigger and Simple Caster.
Use runs the wrong action	Magic Action ID, Use Action ID, and other Character Item Action IDs	The Version 3 Magic builder leaves the ID at `0`. Assign a unique ID after every build or update and match the Use ability.
The first Cast Effect or its repeats occur at the wrong time	Initial Delay, Delay, and Continuous Cast	Use the normal-update rules above, including the initial `-1` timestamp gate. Continuous Cast LateUpdate bypasses these delays, including a negative repeat delay. Turn Continuous Cast off for a single result or use a custom guarded effect/Caster.
A delayed Single cast produces no effect	Use Complete Event versus start and effect delays	The default completion can reset pending effects before they run. Move completion after the required work; Single does not wait for Cast Effect completion automatically.
A Continuous cast never accepts release	Minimum Continuous Use Duration	Do not use exactly `0` in released Version 3. The stop condition accepts `-1` or a positive elapsed duration, but not zero.
Target mode reuses an old target or selects an occluded candidate	Direction: Target after a successful target, then an empty or obstructed scan	Released Version 3 does not clear the cached count on a zero-hit scan and counts in-angle candidates even when its line-of-sight test fails. Use Forward or Indicate when possible, or a custom validated Caster for strict targeting.
Character collision remains disabled after a rejected Forward or Indicate position	A Cast Effect validator such as Teleport rejects the candidate	Released Version 3 returns from that validation path before restoring the character collision layer. Avoid a rejecting validator in this path, or restore the collision layer explicitly in project code.
A Begin or End particle continues after its phase	Start/Stop Spawn Particle ownership	Its Stop callback only clears the cached transform. Configure the particle to stop and return itself, or use explicit cleanup.
The Inspector’s On Cast Event never invokes	Magic Action event selection	Released Version 3 serializes the UnityEvent but never calls it. Register for Event System `OnMagicItemCast` instead.
Impact modules never run	Cast Effect type and enabled Impact rows	Add Physics Cast, Target Impact, Spawn Projectile, or another effect that actually calls the Magic Action’s impact path; then enable the intended Impact modules.
A cast waits forever at start, repeat, or end	Animator events and slot mapping	Add `OnAnimatorStartCast`, `OnAnimatorRepeatCast`, or `OnAnimatorEndCast` to the correct animation, or disable event waiting and use tested durations.
A multi-target network cast invokes the wrong remote effect or throws an index error	More targets than Cast Effect modules in a networked cast	Released Version 3 builds the update-stage module bitmask with the target-loop index instead of the module-loop index. Keep authoritative spell results on the owner/server and replicate the result explicitly in project networking code; do not depend on the built-in update bitmask for multi-target spells.

Saving and multiplayer

Magic Action fields, module rows, perspective references, and State presets serialize with the Character Item or prefab. Treat the active Begin/Casting/End phase, current target slice, cast IDs and counters, pending timers, spawned transient effects, and current MagicUseDataStream as runtime state. Finish or cancel the cast around a save/load boundary instead of expecting it to resume midway.

With the multiplayer integration enabled, authority controls impacts and the action sends explicit network calls for Begin/End modules, Cast Effect start/update/end, impacts, projectiles, particles, and spawned objects where those modules implement support. Custom modules and arbitrary Item Effects are not automatically authoritative or replicated. Test each spell result, interruption, perspective change, and cleanup on every role; apply the multi-target update workaround in the table above.

Developer reference

MagicAction derives from UsableAction. Its action-specific extension bases are MagicCasterModule, MagicStartStopModule, MagicCastEffectModule, MagicImpactModule, and MagicExtraModule. A custom Caster supplies MagicCastData; the released type contains CastOrigin, CastPosition, Direction, CastTargetPosition, StartCastTime, TargetIndex, Targets, CastID, CastNormal, and DetectLayers.

MagicAction.MainMagicCaster is the first enabled Caster. PerformImpact builds or adopts an ImpactCallbackContext, assigns the cast ID as the source ID, and sends the context to enabled Impact modules. MagicCastEffectModule exposes IsValidTargetPosition, StartCast, OnCastUpdate, OnCastLateUpdate, CastWillStop, and StopCast; MagicMultiTargetCastEffectModule maintains one completion cache per supplied target.

The Event System publishes:

OnMagicItemCast(CharacterItem) after all effects report a completed cast;
OnMagicItemStartStopBeginEndActions(CharacterItem, bool beginActions, bool start) whenever a Begin or End group starts or stops; and
OnAnimatorStartCast, OnAnimatorRepeatCast, and OnAnimatorEndCast for the Simple Caster’s animation-event triggers.

Use those Event System callbacks for project integrations. The serialized On Start Stop Begin End Actions Event is invoked, but the serialized On Cast Event has the released-Version-3 limitation described above.