# Character and Interaction Runtime

Level: Advanced

Flow Character and Flow Interaction sit at the gameplay edge of Flow Core. They turn reusable graph logic into character-scale behavior: movement, animation intent, animation-timed events, target selection, focus feedback, and interaction dispatch.

This page explains the runtime responsibilities, data flow, event context, extension boundaries, and failure modes that matter when programming against these systems.

Related pages:

* Designer: Flow Character
* Designer: Flow Interaction
* Reference: Character Interaction Catalog
* Terminology

## Runtime Responsibilities

Flow Character is responsible for character-facing runtime behavior:

* Maintaining the character identity used by Character instructions and conditions.
* Coordinating movement, facing, grounded state, arrival checks, controllability, alive/dead state, busy flags, and optional IK.
* Playing long-lived `State` assets and short-lived `Gesture` assets.
* Reading animation events and `Marker` definitions from State/Gesture clips.
* Building event graph payload data for animation event handling.

Flow Interaction is responsible for interaction-facing runtime behavior:

* Registering available `Flow Interaction Target` components.
* Letting a `Flow Interaction Owner` collect, rank, and focus candidates.
* Dispatching focus, blur, and interact events on both the owner side and target side.
* Showing or hiding target canvas feedback when the target is focused or available.
* Exposing interaction event payload data to Flow conditions.

Neither system owns higher-level game rules such as inventory, dialogue, quest state, save data, networking, or input policy beyond the built-in component behavior. Those rules should live in your graph instructions, component adapters, or game-specific services.

## Character Data Flow

```mermaid
flowchart TD
    A["Flow Character Component"] --> B["Character Feature Modules"]
    B --> C["Movement / Facing / Animation / IK"]
    A --> D["State Asset"]
    A --> E["Gesture Asset"]
    D --> F["Animation Event"]
    E --> F
    F --> G["Marker Match"]
    G --> H["FlowCharacterAnimationEventContext payload"]
    H --> I["Event Graph"]
    I --> J["Instruction chain / branch"]
```

A `State` describes animation that can stay active, blend, and refresh over time. A `Gesture` describes a more temporary action that can be layered over the character and optionally split into Entry, main, and exit segments.

`Marker` is the bridge between animation time and graph logic. A Marker stores normalized-time timing, limb or custom Id routing, optional cooldown behavior, and editor-facing notes. At runtime, animation events can be matched against these Marker definitions and converted into event graph payload data.

## Interaction Data Flow

```mermaid
flowchart TD
    A["Flow Interaction Target Enabled"] --> B["Target Registry"]
    C["Flow Interaction Owner Update"] --> D["Candidate Collection"]
    B --> D
    D --> E["Target Selection Mode"]
    E --> F["Focus / Blur"]
    F --> G["Canvas Feedback"]
    E --> H["Interact"]
    H --> I["FlowInteractionEventContext payload"]
    I --> J["Owner and Target Event Graphs"]
```

A `Flow Interaction Target` registers itself as a candidate. A `Flow Interaction Owner` gathers candidates and chooses a target using its configured selection mode, scan range, angle, layer mask, and availability rules.

Focus and blur are selection changes. Interact is an explicit action. The systems are separate so UI feedback can update without firing gameplay effects.

## Flow Context Keys

Character animation event graphs receive their event payload through the character animation event context. Interaction event graphs receive their payload through the interaction event context.

Use the context objects as read-only event data:

* Character animation events expose the character, event type, source State/Gesture, Marker match data, limb/custom Id information, and event timing.
* Interaction events expose the owner, target, event type, event side, and current interaction relationship.

Conditions such as `Character Animation Event Type`, `Character Animation Marker`, `Flow Interaction Event Type Is`, `Flow Interaction Event Side Is`, `Flow Interaction Event Owner Is`, and `Flow Interaction Event Target Is` depend on these payload values. If the condition is evaluated outside the matching event graph, the context may be missing and the condition should be treated as false.

## State, Gesture, and Marker Semantics

`State` and `Gesture` assets both support animation event routing, but they are used for different authoring intentions:

* Use `State` for sustained animation identity: locomotion, idle, combat stance, climb, swim, knocked down, or a long channel.
* Use `Gesture` for bounded actions: attack, dodge, reload, pickup, emote, cast, interact, or a one-shot upper-body action.
* Use `Marker` when graph logic needs to happen at a specific point inside the animation rather than at state start or completion.

Marker routing is intentionally semantic. A Marker can represent `LeftFoot`, `RightFoot`, `LeftHand`, `RightHand`, `Head`, or a custom Id. The graph can respond to meaning instead of hard-coded clip names or frame numbers.

Marker cooldown is also semantic. It prevents repeated event handling for the same routed meaning in a short window. This is useful for blended loops, refreshed states, and animation events that may fire more often than gameplay should respond.

## Animation Timing and Motor Override Resolution

`Speed Curve` and motor overrides solve different runtime problems.

`Speed Curve` is sampled by a Clip Track using normalized time. It multiplies the animation playback clock for that track. It does not directly change Character `Move Speed`, `Acceleration`, `Gravity`, or any other movement property. Runtime sampling clamps the curve result by `CharacterAnimationSpeedCurveMinimumMultiplier` from Flow Core Settings.

Asset-level `Motor Overrides` are fixed values owned by an active State or Gesture. Clip-level `Clip Motor Overrides` are sampled from the active Clip Track and can vary by normalized time.

Motor override resolution follows this order:

* Restore the Character movement snapshot captured before animation graph overrides.
* Collect active State contributors and apply them in layer order, then push order.
* For each State contributor, apply asset-level Motor Overrides first, then its Clip Motor Override samples.
* Collect active Gesture contributors and apply them in priority order, then push order.
* For each Gesture contributor, apply asset-level Motor Overrides first, then its Clip Motor Override samples.

Clip-level float overrides evaluate as `Value * Multiplier Curve` at the sample normalized time. Locomotion Clip Motor Override samples are blended by active locomotion clip weight. If total sample weight is below 1, the remaining weight uses the current fallback value. If total sample weight is above 1, values are normalized by total weight.

Clip-level bool overrides vote by weight. `true` and `false` weights are accumulated, any remaining weight uses the fallback value, and a tie returns the fallback value.

Use this distinction when debugging:

* A Speed Curve issue appears as animation timing drift.
* An asset-level Motor Overrides issue appears as a whole State/Gesture movement rule.
* A Clip Motor Overrides issue appears only while the related Clip Track contributes animation.
* A locomotion Clip Motor Overrides issue may be blended with other locomotion tracks, so the final value can be between the participating clip values.

## Extension Boundaries

Prefer these extension points:

* Create new Character or Interaction instructions and conditions when designers need graph-level behavior.
* Use State/Gesture assets and Marker definitions for animation-authored timing.
* Use event graphs for gameplay consequences that belong to a character or target.
* Add component adapters around project-specific systems such as inventory, dialogue, audio, ability systems, or quest state.
* Read event payload through the provided Flow context instead of storing transient event data globally.

Avoid these patterns:

* Manually mutating private runtime state from unrelated components.
* Depending on a specific Animator clip name when a Marker Id or limb route can express the intent.
* Calling interaction effects directly from target selection updates.
* Treating canvas visibility as gameplay state.
* Running high-frequency debug reflection or broad blackboard scans in movement or interaction hot paths.

## Performance Notes

Character and Interaction code may run every frame. Keep extension code small and predictable.

* Candidate scanning cost grows with owner count and target count. Use scan radius, layers, and availability gates to reduce unnecessary candidates.
* Avoid allocating new collections every frame in custom owner or target extensions.
* Keep animation event graphs focused. Expensive gameplay queries should be cached or moved behind explicit Trigger moments.
* Marker cooldown helps avoid duplicate event work in blended or refreshed animation states.
* Use strongly typed data paths for payload access. Debug-style lookup is fine for tools, but not for hot-loop behavior.

## Failure Modes

Common runtime failures usually come from missing context or mismatched authoring data:

* A Character animation condition is evaluated outside an animation event graph, so the payload is missing.
* A Marker uses `Custom` but the graph checks the wrong Id string.
* A footstep effect listens for a generic animation event but the Marker route is limb-specific.
* A Gesture is stopped before its exit segment or completion event can run.
* A `Flow Interaction Owner` has no candidates because scan radius, angle, layer, or availability is too strict.
* A `Flow Interaction Target` is disabled, not registered, or cannot currently be interacted with.
* A target canvas does not change because the target has no configured canvas feedback.
* Focus logic is used as if it were Interact logic, causing hover feedback to run gameplay effects.

When debugging, first confirm the component relationship, then confirm the payload context, then confirm the graph condition. Most issues are visible at one of those three layers.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://flow-core.gitbook.io/flow-core-docs/documentation/runtime-guide/character-interaction-runtime.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.