# Performance and Failure Modes

Level: Advanced

## Goal

Recognize common Flow Core performance risks and understand how runtime failures usually appear, so you can fix the right layer: graph structure, data binding, generated registries, or custom extension code.

## Symptoms

| Symptom                                     | Likely area                                             |
| ------------------------------------------- | ------------------------------------------------------- |
| Chains run late or bunch up.                | Trigger frequency and Invoke Mode.                      |
| Values read as defaults.                    | Missing key, wrong type, or wrong scope.                |
| A generated Instruction does not appear.    | Codegen or registry state.                              |
| A list operation appears to do nothing.     | Index rules, empty list, or disabled normalize setting. |
| Scene Blackboard data changes unexpectedly. | Multiple scene Blackboards or implicit selection.       |
| Stutters appear near custom nodes.          | Allocation, boxing, or external API calls.              |

## Likely Causes

* Non-typed or reflective access in a hot path.
* Frequent Blackboard list length changes.
* High-frequency Triggers combined with `Queue`.
* Custom Instructions or Conditions allocating per execution.
* Generated registries are stale after adding or changing extension types.
* A graph relies on implicit Scene Blackboard selection when the scene has more than one candidate.
* Event handlers register, unregister, or destroy objects during dispatch.

## Registry Loading Performance

Flow Core avoids large blocking registry work in both authoring and runtime paths.

In Edit Mode, authoring surfaces can show a loading state while generated instructions, conditions, drawers, and Blackboard picker data become available. During that state, incomplete editor data should not be treated as a missing feature or an empty result.

In Play Mode, generated instruction and condition lookup is demand-driven. Runtime execution remains correct while low-budget background warmup continues, and the first use of an entry can resolve the required factory immediately if it has not been warmed yet.

If an enabled generated Instruction or Condition is truly missing, Flow Core reports a clear failure instead of silently skipping it. Treat that as stale generated output, a missing registry rebuild, or an invalid graph reference.

## Checks

1. Identify whether this is cost or correctness.
   * If the issue is stutter or delay, start with Runtime Cost Monitoring.
   * If the issue is missing behavior, check graph assignment, registries, and data binding.
2. Check data binding.
   * Confirm Blackboard scope, index, key, and type.
   * Confirm Local Blackboards are bound on the process.
   * Use explicit Scene Blackboard references when there are multiple candidates.
3. Check generated and extension surfaces.
   * Confirm generated registries include new Instructions, Conditions, enum buckets, or custom types.
   * Confirm custom runtime code returns clear failure behavior when inputs are missing.
   * Avoid treating generated internals as public integration contracts.
4. Check runtime pressure.
   * Look for chains started too frequently.
   * Look for `Queue` on a path that receives repeated events.
   * Look for list mutations that change list size repeatedly.
   * Look for custom code that allocates in Update-like or high-frequency chains.

## Fixes

* Prefer typed Blackboard access paths in hot code.
* Cache stable keys and project-side lookups in custom code.
* Batch Blackboard list changes and rebuild blackboard bindings once.
* Reduce Trigger frequency or change Invoke Mode when late chains are more harmful than skipped work.
* Rerun the relevant generators and registry generation after adding extension types.
* Use explicit Scene Blackboard references for deterministic data ownership.
* Defer object destruction or unregister work by one frame when event dispatch lifetime is unclear.
* Use Runtime Cost Monitoring before and after optimization.

## Failure Modes

| Failure                               | Runtime behavior                                                                     |
| ------------------------------------- | ------------------------------------------------------------------------------------ |
| Missing key or type mismatch          | Reads can fall back to default values or fail resolution depending on the node.      |
| Unregistered Instruction or Condition | The behavior is unavailable or missing from runtime/editor lookup.                   |
| List index out of range               | List access, set, or remove can be skipped; insert may warn.                         |
| Multiple Scene Blackboards            | Implicit current selection may not be the one the design expects.                    |
| Missing SubFlowGraph Entry or Exit    | The subgraph path can return Invalid or fail to produce the intended result.         |
| Destroy or unregister during dispatch | Current dispatch may still use a snapshot of handlers; defer risky lifetime changes. |

## Common Traps

* Assuming a visually small graph is cheap. A single custom Instruction can dominate cost.
* Assuming `GameObject` and component value paths have the same cost and behavior.
* Assuming `Queue` preserves correctness when the delayed result is no longer relevant.
* Assuming Scene Blackboard fallback is deterministic in scenes with several candidates.
* Assuming editor preview is runtime truth when Debug Context is wrong.

## Related

* [Runtime Cost Monitoring](/flow-core-docs/documentation/troubleshooting/runtime-cost-monitoring.md)
* [Lifecycle and Dataflow](/flow-core-docs/documentation/runtime-guide/lifecycle-and-dataflow.md)
* [Invoke and Reject Modes](/flow-core-docs/documentation/reference/invoke-and-reject-modes.md)
* [FlowCore Settings](/flow-core-docs/documentation/reference/flow-core-settings.md)
* [Codegen Pipeline](/flow-core-docs/documentation/api-extension-guide/codegen-pipeline.md)


---

# 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/troubleshooting/performance-and-failure-modes.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.