> For the complete documentation index, see [llms.txt](https://malbersanimations.gitbook.io/animal-controller/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://malbersanimations.gitbook.io/animal-controller/malbers-questforge/dialogue-system/nodes/character-action-node.md). # Character Action Node ### Overview The **Malbers Character Action Node** triggers a Malbers Animal Controller **State** or **Mode** on any `MAnimal` character during a dialogue sequence. It can control the player, an NPC, or any other character in the scene via a `TransformVar` reference. Optionally, the dialogue graph can be paused until the action completes before advancing. The node's title updates dynamically to reflect the currently selected action, displaying as `[State] StateName` or `[Mode] ModeName`. ***
### Ports | Port | Direction | Capacity | Description | | ------------ | --------- | -------- | --------------------------------------------------------------------------------------------------------------------- | | **Previous** | Input | Multi | Receives connections from any preceding node. | | **Next** | Output | Single | Advances after the action executes (immediately, or once the action completes if **Wait for Completion** is enabled). | *** ### Node Properties The following properties are always visible regardless of action type: | Property | Type | Description | | ----------------------- | -------------- | ---------------------------------------------------------------------------------------------------------- | | **Character Target** | `TransformVar` | Malbers TransformVar pointing to the character's GameObject. Must have an `MAnimal` component. | | **Action Type** | Dropdown | Selects whether to trigger a **State** or a **Mode**. Controls which fields appear below. | | **Wait for Completion** | `bool` | If enabled, the dialogue graph pauses until the triggered state or mode has fully exited before advancing. | *** ### Action Type: State Triggers a Malbers **State** on the target `MAnimal`. States control locomotion modes such as Idle, Run, Swim, Fly, etc. | Property | Type | Description | | ------------------ | --------- | ------------------------------------------------------------------------------------------------------------- | | **State ID** | `StateID` | The Malbers `StateID` ScriptableObject asset identifying which state to interact with. | | **State Reaction** | Dropdown | How to interact with the state. See options below. | | **Enter Status** | `int` | Sets the animator `EnterStatus` parameter on activation. Only visible for **Activate** and **ForceActivate**. | #### State Reaction Options | Option | Behaviour | | ----------------- | -------------------------------------------------------------------------------- | | **Activate** | Requests the state to activate. The animal may transition when conditions allow. | | **ForceActivate** | Forces the state to activate immediately, overriding current state. | | **Enable** | Enables the state so it can be entered normally. | | **Disable** | Disables the state, preventing it from being entered. | | **AllowExit** | Signals the current state that it is allowed to exit. | | **SetExitStatus** | Sets the state's exit status parameter without changing the active state. | *** ### Action Type: Mode Triggers a Malbers **Mode** on the target `MAnimal`. Modes are overlay animations that play on top of the base locomotion — attacks, greetings, gestures, etc. | Property | Type | Description | | ------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------- | | **Mode ID** | `ModeID` | The Malbers `ModeID` ScriptableObject asset identifying which mode to interact with. | | **Mode Reaction** | Dropdown | How to interact with the mode. See options below. | | **Ability Index** | `int` | Which ability within the mode to activate. Use `-99` for a random ability. Only visible for **Play** and **ForceActivate**. | | **Ability Status** | Dropdown | Controls how long the ability stays active. Only visible for **Play** and **ForceActivate**. | | **Ability Time** | `float` | Duration in seconds the ability remains active. Only visible when **Ability Status** is `ActiveByTime`. | #### Mode Reaction Options | Option | Behaviour | | ------------------ | -------------------------------------------------------------------------------- | | **Play** | Requests the mode to activate. May be queued if another mode is already playing. | | **ForceActivate** | Forces the mode to activate immediately, interrupting any active mode. | | **Interrupt** | Interrupts the currently active mode. | | **Stop** | Stops the currently active mode. | | **Enable** | Enables the mode so it can be activated. | | **Disable** | Disables the mode, preventing activation. | | **SetActiveIndex** | Changes the mode's active ability index without re-triggering it. | #### Ability Status Options | Option | Behaviour | | ---------------- | ------------------------------------------------------------------------------ | | **PlayOnce** | The ability plays its animation once and exits automatically. | | **Charged** | The ability remains active while held and exits on release. | | **ActiveByTime** | The ability stays active for the duration set in **Ability Time**, then exits. | *** ### How It Works At runtime, `DialogueManager` resolves the `CharacterTarget.Value` Transform and attempts to get the `MAnimal` component from it. If no `MAnimal` is found, the node logs a warning and advances immediately without executing any action. If `MAnimal` is found: 1. The appropriate state or mode method is called on `MAnimal` based on the configured **State Reaction** or **Mode Reaction**. 2. If **Wait for Completion** is **disabled** — the graph advances to the next node immediately. 3. If **Wait for Completion** is **enabled** — a coroutine polls each frame: * **State**: waits until `MAnimal.ActiveStateID` is no longer the state that was activated. * **Mode**: waits until `MAnimal.ActiveMode` is `null` or a different mode. * Two frames are skipped at the start to allow the action to actually begin before polling starts. *** ### Validation | Condition | Severity | | ---------------------------------------- | -------- | | **Character Target** not assigned | Error | | **Output** port not connected | Error | | **State ID** not assigned *(State mode)* | Warning | | **Mode ID** not assigned *(Mode mode)* | Warning | *** ### Usage Tips * **NPC greetings** — trigger a wave or bow Mode on an NPC at the start of a conversation, with **Wait for Completion** enabled so the first dialogue line doesn't appear until the animation finishes. * **Player lockout** — activate a custom State on the player (e.g. a sit or kneel state) to pin them in place during a cutscene, then deactivate it with a second Character Action Node at the end. * **Wait for Completion + State** — keep in mind the node waits for the state to *exit*, not just to *start*. If the state loops indefinitely, the graph will block until another system forces a state change. Design states used this way to have a natural exit. * **Ability Index -99** — passing `-99` as the ability index selects a random ability within the mode, which is useful for varied idle animations or randomised reactions. * **Character Target is a TransformVar** — this must be a Malbers `TransformVar` ScriptableObject, not a direct scene reference. Populate it at runtime using `QuestForgeRuntimeSetup` (for the player) or any other component that writes to shared variable assets (for NPCs).