PlayMaker

Export

Use the PlayMaker integration to start Ultimate Character Controller abilities, change states and attributes, control items, and branch an FSM from Ultimate Character Controller results without writing a separate script for each workflow.

Supported package boundary

The released Ultimate Character Controller Version 3 integration is a PlayMaker 1 custom-action package. Its 28 actions inherit from PlayMaker 1’s FsmStateAction and use OnEnter, OnUpdate, and Finish. The current PlayMaker 1 Asset Store listing reports 1.9.10f1, but the Opsive bridge was last source-updated in April 2023 and declares no minimum or maximum PlayMaker 1 version. Import and compile the exact package combination before updating a production project.

This bridge does not support PlayMaker 2. Hutong Games states that PlayMaker 2 is not backward compatible with PlayMaker 1, and PlayMaker 2 uses a different custom-action lifecycle and editor API. Keep an existing Ultimate Character Controller project on PlayMaker 1, or port the Opsive actions before moving that project to PlayMaker 2.

Before you begin

Build and test the Ultimate Character Controller Version 3 character before adding an FSM. The integration controls existing Ultimate Character Controller components; it does not create the character, abilities, items, attributes, or states.
Install PlayMaker 1 and complete its installer before importing the Opsive bridge. Do not import PlayMaker 1 and PlayMaker 2 into the same project.
Decide where the FSM should live. Put PlayMaker FSM on the character when most actions use that character, or put it on a separate controller and assign Target Game Object explicitly.
Add every ability, effect, item-set category, attribute, and named state that the FSM will reference before configuring actions.

Install the integration

Install PlayMaker 1 and confirm that a simple PlayMaker FSM runs in Play Mode.
Sign in to Opsive Downloads and download the PlayMaker integration. The bridge is not included in the base product’s Integrations folder before this download.
Import the downloaded bridge after PlayMaker has compiled. Importing it creates the integration files in the project.
Allow Unity to compile. Resolve the first Console error before building an FSM; the action scripts require the HutongGames.PlayMaker and Ultimate Character Controller assemblies.
Open the PlayMaker Action Browser, search for Ultimate Character Controller, and confirm that the Opsive actions appear in that category.

The bridge adds PlayMaker actions and custom action editors. It does not add a required runtime component beyond the ordinary PlayMaker FSM and the Ultimate Character Controller components used by each action.

Start an ability from an FSM

This is the smallest useful test because it verifies action discovery, character targeting, Ultimate Character Controller ability lookup, and PlayMaker transitions.

Add the Ultimate Character Controller ability that the FSM should control, such as Jump, to Ultimate Character Locomotion > Abilities.
Add PlayMaker FSM to the character and open the FSM editor.
Create a state named Start Jump, then add Ultimate Character Controller > Start Stop Ability from the Action Browser.
Leave Target Game Object at the owner when the FSM is on the character. Otherwise, assign the character GameObject.
Set Ability Type to Jump.
Leave Priority Index at -1 when only one Jump ability exists. If multiple abilities use the same type, enter the Ultimate Character Controller ability index that should be controlled.
Keep Start enabled and assign separate Success Event and Failure Event transitions.
Enter Play Mode and activate the Start Jump state. The success branch should run only when Ultimate Character Controller’s normal ability rules allow Jump to start.

Use another Start Stop Ability action with Start disabled when the FSM should request a stop. The action calls Ultimate Character Controller’s normal TryStartAbility or TryStopAbility path, so ability conflicts, start conditions, movement state, and other Ultimate Character Controller rules still apply.

Control an Ultimate Character Controller state

Use Set State when an FSM should apply several Inspector values as one named configuration rather than changing individual component fields.

Create and verify the named state and its preset through the Ultimate Character Controller State System.
Add Ultimate Character Controller > Set State to a PlayMaker state.
Set Target Game Object to the object containing the state, enter the exact State Name, and leave Active enabled to activate it.
Add another Set State action with the same name and Active disabled on the transition that should release the state.
In Play Mode, watch the Ultimate Character Controller State list and the affected Inspector values as the FSM enters and leaves those states.

The bridge deliberately does not contain one action for every Ultimate Character Controller field. Prefer a named state when designers need a reusable group of values, and use a dedicated action when the change represents a runtime operation such as starting an ability or applying damage.

Work with attributes and health

The character or target object must already contain the relevant Attribute Manager or Health component.

Get Attribute Value reads the current Value, Min Value, or Max Value into a PlayMaker float. Attribute Name defaults to Health, and Every Frame is off by default.
Set Attribute Value writes the selected Value, Min Value, or Max Value. Keep Every Frame off for a one-time change.
Damage and Heal call the target’s Health component with a positive Amount. Enabling Every Frame applies that amount on every update, not once per second.
Is Alive stores a Boolean and can send Alive Event or Dead Event.
Has Taken Damage stores the attacker and sends Damaged Event or Not Damaged Event. It detects damage from the current or immediately preceding frame while the action is active; it is not a history query.

Use the Attributes and Health pages to create and verify the underlying Ultimate Character Controller data before reading it from PlayMaker.

Control items and inventory

Configure the character’s item definitions, Item Set Manager, categories, abilities, slots, and action IDs before adding these actions.

Adjust Item Identifier Amount adds or removes the specified Item Definition amount from the target Inventory. Amount defaults to 0; use a negative value to remove inventory.
Get Item Identifier Amount stores the amount for an Item Definition in a PlayMaker integer.
Start Equip Unequip selects an ItemSet Category and Item Set Index, then asks the matching Equip Unequip ability to change sets.
Start Item Set Ability selects an Ability Type and ItemSet Category and sends success or failure. See the current source limitation below before using it with more than one item-set ability in a category.
Start Stop Use finds a Use ability by Slot ID and Action ID. Slot ID defaults to -1, Action ID to 0, Start to enabled, and Wait For Use Complete to enabled.
Reload finds the Reload ability with the requested Slot ID and Action ID and is compiled only when the Ultimate Character Controller shooter feature is present.

Use the Items and Inventory workflow to confirm that the same operation works through Ultimate Character Controller before asking an FSM to control it.

Other included workflows

The action category also contains focused helpers for common Ultimate Character Controller operations:

Goal	Actions	Important setup
Inspect or control abilities	Is Ability Active, Is Ability Enabled, Set Ability Enabled, Start Stop Ability	Select the ability type; use Priority Index only when duplicate types exist.
Inspect or control effects	Is Effect Active, Start Stop Effect	The effect must already exist under Ultimate Character Locomotion. See the current editor limitation below.
Aim and move the character	Set Aim Target, Set Move With Object Target, Set Position And Rotation	The target requires Local Look Source, Move With Object, or Ultimate Character Locomotion respectively.
Assign or change the camera	Assign Character, Toggle Perspective	Assign Character targets the Camera Controller. Toggle Perspective compiles only when both first- and third-person features are installed.
Change the character model	Change Model	The target requires Model Manager; the shipped action accepts model indexes greater than `0`.
Use the Opsive object pool	Instantiate Object, Destroy Object	Store the instantiated GameObject when another state must destroy it later.
Send a name-only Opsive event	Execute Event	Do not use the shipped action without reviewing the current source defect below.

How targeting and transitions run

Most actions resolve Target Game Object when their PlayMaker state begins. An unassigned target means the GameObject that owns the FSM. Actions then find the required Ultimate Character Controller component on that object and either finish immediately or remain active when Every Frame or a wait option is enabled.

Success Event, Failure Event, Active Event, and similar fields send PlayMaker FSM events. They do not broadcast Ultimate Character Controller events. Execute Event is the exception: it sends a name-only event through the Opsive EventHandler to the selected GameObject.

Polling actions such as Is Ability Active, Is Ability Enabled, Is Effect Active, Get Attribute Value, Is Alive, and Has Taken Damage can run every frame. Keep that option off when a single snapshot is sufficient, and transition out of a polling state when its result is no longer needed.

Current bridge limitations

The package is written for PlayMaker 1 and cannot be treated as a PlayMaker 2 action pack.
The bridge contains no action for every Ultimate Character Controller Inspector field. Use Ultimate Character Controller states for grouped configuration changes.
Execute Event in the shipped source invokes the named event twice when Every Frame is disabled and never calls Finish. Do not use it unchanged for a one-shot event.
The custom editor for Start Stop Effect populates Effect Type from Ultimate Character Controller ability classes instead of effect classes. Use Is Effect Active for inspection, or correct and retest the Start Stop Effect editor before relying on it.
Start Item Set Ability displays Ability Type, but its runtime lookup selects the first Item Set ability matching the chosen category and does not use the selected type. Do not place multiple candidate item-set abilities in that category without adapting the action.
With Wait For Use Complete enabled, Start Stop Use waits for completion but does not send its configured Success or Failure Event. Disable that option when the FSM transition depends on the result event, or adapt the action.
Several actions return early when their required component, ability, item definition, or target is missing. Some of those paths do not call Finish, so an FSM can appear stuck until the setup is corrected.

Verify in Play Mode

Open the Action Browser and confirm all expected actions appear under Ultimate Character Controller with no compile errors.
Run the Start Jump test. Confirm that a valid start follows Success Event and an intentionally blocked start follows Failure Event.
Activate and deactivate a named Ultimate Character Controller state. Confirm the State list and preset values change only on the intended GameObject.
Read Health with Get Attribute Value, apply one Damage action, and read it again. The amount should change once, not on every frame.
Use Is Alive and Has Taken Damage while the target receives damage. Confirm the PlayMaker events and attacker variable change on the expected frame.
Add one inventory item, query its amount, equip a known item set, and use the configured Slot ID and Action ID. Confirm the character’s Ultimate Character Controller abilities remain the runtime owner of those operations.
Repeat one action from an FSM on another GameObject with Target Game Object assigned explicitly. Only the assigned character should respond.
Test every failure transition by disabling an ability, omitting a required item, or choosing a blocked action. The FSM should leave the state deliberately rather than remaining active without feedback.
If the project saves or networks gameplay, repeat the tests after load and for every local, authoritative, and remote role.

Saving and multiplayer

The bridge does not persist PlayMaker states, FSM variables, active Ultimate Character Controller states, attributes, inventory, or ability progress. Save PlayMaker data and Ultimate Character Controller runtime data through their respective project save systems, then restore them in a defined order. A reliable baseline is to restore the Ultimate Character Controller character first and let the FSM resume from a neutral state rather than replaying one-shot actions during load.

The actions also send no network messages and perform no authority checks. Execute gameplay-changing actions only for the character’s authoritative owner, then replicate the resulting Ultimate Character Controller ability, item, attribute, state, or transform through the project’s supported multiplayer layer. A PlayMaker event is local unless the project explicitly sends it across the network.

Troubleshooting

Symptom	Check	Fix
The Opsive actions do not appear	PlayMaker may not have compiled before the bridge, or PlayMaker 2 may be installed	Use PlayMaker 1, complete its installer, then reimport the current Ultimate Character Controller Version 3 integration.
Unity reports missing `HutongGames.PlayMaker` types	The bridge was imported before PlayMaker 1 or the PlayMaker installer was not completed	Finish the PlayMaker 1 installation, allow Unity to compile, then reimport the bridge.
The FSM controls the wrong object	Target Game Object may still use the FSM owner	Put the FSM on the Ultimate Character Controller character or assign the intended character, camera, inventory, or state owner explicitly.
Start Stop Ability does nothing	The selected ability type may not exist, the duplicate-type index may be wrong, or Ultimate Character Controller may reject its start rules	Add and enable the ability, keep Priority Index at `-1` for one instance, and wire both result events.
An action state never finishes	A required target, ability, effect, or look source may be missing, or the shipped Execute Event action may be in use	Inspect the Console and action fields, assign the missing dependency, avoid the unmodified Execute Event action, and add an explicit timeout around project-critical actions.
An attribute result never changes	The Attribute Manager may be absent or Attribute Name may not match exactly	Add the attribute, use its exact name, and store the result in a compatible PlayMaker float.
Damage or inventory changes repeat rapidly	Every Frame may be enabled	Disable it for one-shot changes, or scale the operation deliberately in a custom continuous action.
Item equip or use does not start	The category, Item Set Index, Slot ID, or Action ID may not match the character’s configured abilities	Inspect the character’s Item Set Manager and item abilities, then enter those exact identifiers.
Toggle Perspective is missing	Both first- and third-person scripting defines may not be present	Use a character package with both perspectives, or control the installed View Type through a project-specific workflow.
Change Model does nothing for index `0`	The shipped action rejects model indexes less than or equal to zero	Choose a valid available model index above zero or adapt the action if the first entry must be selected.
Execute Event fires twice or the state remains active	The shipped one-shot implementation has a source defect	Avoid the action unchanged; correct it to execute once and call `Finish`, then test the named receiver.
PlayMaker and Ultimate Character Controller work locally but not for remote players	The integration has no networking or ownership logic	Run actions on the authoritative owner and use the selected Ultimate Character Controller/network integration to replicate the result.

Developer reference

Every shipped action uses [ActionCategory("Ultimate Character Controller")]. Most resolve the target with Fsm.GetOwnerDefaultTarget, cache the relevant Ultimate Character Controller component, and use PlayMaker fields for inputs, stored results, and transition events.

The 28 action sources are grouped as follows:

Character and camera: AssignCharacter, ChangeModel, SetAimTarget, SetMoveWithObjectTarget, SetPositionAndRotation, and TogglePerspective.
Abilities and effects: IsAbilityActive, IsAbilityEnabled, SetAbilityEnabled, StartStopAbility, IsEffectActive, and StartStopEffect.
Items and inventory: AdjustItemIdentifierAmount, GetItemIdentifierAmount, StartEquipUnequip, StartItemSetAbility, StartStopUse, and conditionally compiled Reload.
Attributes and health: Damage, Heal, GetAttributeValue, SetAttributeValue, HasTakenDamage, and IsAlive.
State and events: SetState and ExecuteEvent.
Pooling: InstantiateObject and DestroyObject.

Reload is wrapped in ULTIMATE_CHARACTER_CONTROLLER_SHOOTER. TogglePerspective is wrapped in both FIRST_PERSON_CONTROLLER and THIRD_PERSON_CONTROLLER. The custom action editors provide type and Item Set category popups from the current project; the Item Set category popup requires an initialized Item Set Manager in the scene, and Start Stop Effect has the type-popup defect described above.

When porting to PlayMaker 2, do not mechanically copy these classes. PlayMaker 2 replaces the FsmStateAction lifecycle and its OnEnter, OnUpdate, and Finish pattern with its newer action, parameter, update-mode, and editor APIs. Preserve the Ultimate Character Controller operation and result semantics while rebuilding each action against the PlayMaker 2 API.