# Work with Blackboard Data

Level: Beginner

## Goal

Create a Blackboard value, bind it to a `FlowCoreProcess`, read it from a visual graph, and verify that the graph is using the data source you intended.

## When To Use This

Use this guide when a graph needs designer-authored values, runtime state, or shared data that multiple nodes must read consistently.

Blackboard data is the usual place to put values that should be visible to the editor and reusable by graph logic. It is not the same as a trigger `payload`. A payload belongs to one event or Entry call. A Blackboard value belongs to a scope and can be read again by later nodes.

If you are deciding between Blackboard, payload, TempPayload, context shortcuts, or a target resolver path, read [Value Sources and Target Resolution](/flow-core-docs/documentation/runtime-guide/value-sources-and-target-resolution.md) first.

## Prerequisites

* You can open a Flow Core graph in the editor.
* You have a scene GameObject with a `FlowCoreProcess`.
* You know whether the value should belong to one object, one scene, or the whole project.

## Steps

1. Choose the smallest useful scope.
   * Use a Local `Blackboard` for per-object state such as health, selected target, current prompt, or the first tutorial value `Say`.
   * Use a `SceneBlackboard` when several scene objects need the same value.
   * Use a `GlobalBlackboard` only when the value must intentionally cross scenes or project-level workflows.
2. Add the Blackboard owner.
   * For Local data, add a `Blackboard` component to the same GameObject that owns the `FlowCoreProcess`.
   * For Scene data, add or select the scene's `SceneBlackboard`.
   * For Global data, select the `GlobalBlackboard` asset that should own the value.
3. Create the key in the correct type bucket.
   * Open the Blackboard in the Inspector.
   * Use the **Edit** tab.
   * Add the value type you need, such as `String`, `Bool`, `Int`, or `Float`.
   * Add a key inside that type bucket.
   * For a first test, create a `String` key named `Say` with the value `Hello Flow Core`.
4. Bind Local data to the process.
   * Select the GameObject with `FlowCoreProcess`.
   * In `Local Blackboards`, add the `Blackboard` component.
   * Put the Blackboard in index `0` if the graph should read `LocalBlackboard[0]`.
5. Read the value from a graph.
   * Open the graph assigned to the `FlowCoreProcess`.
   * Set Debug Context to the GameObject that owns the process.
   * Add or select an `Action` node.
   * Add an instruction that expects the same type as the Blackboard key.
   * For the `Say` test, add `Log String` from `Debug/Value/String`.
   * Set the value source to `Blackboard`.
   * Set scope to `Local`, index to `0`, and key to `Say`.
6. Keep writes explicit.
   * When a graph writes data, use a typed instruction that matches the destination key.
   * Write to the same scope, index, key, and value type that later reads will use.
   * Avoid changing Blackboard list order while chains are actively depending on the old index.
7. Inspect the resolved path.
   * Keep `Summary` and `Value` detail toggles on while authoring.
   * Use Debug Context so summaries can resolve Local and Scene Blackboard paths.
   * If the summary cannot resolve a path, fix the binding before relying on Play Mode behavior.

## Expected Result

* The value has a clear owner and scope.
* The graph reads the exact key and type you created.
* Debug Context can preview the path.
* Play Mode behavior can be checked through a visible result, such as the Unity Console printing `Hello Flow Core`.

## Troubleshooting

* The graph cannot find the value: confirm the Blackboard is in the process list for that scope and index.
* The value exists but the node still fails: confirm the key spelling and the value type match the instruction.
* The editor preview looks wrong: set Debug Context to the GameObject with the `FlowCoreProcess`.
* A Scene value resolves inconsistently: use an explicit `SceneBlackboard` reference when more than one scene Blackboard exists.
* A runtime write does not affect the next read: check execution order and make sure the write runs before the read in the same chain or before the later trigger.
* A saved value restores incorrectly: use the supported persistence guide and confirm the value type is serializable.

## Related

* [Blackboard UI](/flow-core-docs/documentation/editor-guide/blackboard-ui.md)
* [First 15 Minutes](/flow-core-docs/documentation/tutorials/first-15-minutes.md)
* [Debug Context](/flow-core-docs/documentation/editor-guide/debug-context.md)
* [Lifecycle and Dataflow](/flow-core-docs/documentation/runtime-guide/lifecycle-and-dataflow.md)
* [Value Sources and Target Resolution](/flow-core-docs/documentation/runtime-guide/value-sources-and-target-resolution.md)
* [Persistence](/flow-core-docs/documentation/api-extension-guide/persistence.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/how-to-guides/work-with-blackboard-data.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.