# Blackboard UI

Level: Beginner

## Goal

Create and edit Blackboard keys in a safe, predictable way.

## Where it appears

* `Blackboard` component (Local scope).
* `SceneBlackboard` component (Scene scope).
* `GlobalBlackboard` asset (Global scope).

## Quick start: add a key

1. Select the Blackboard.
   * Component on a GameObject, or a GlobalBlackboard asset.
2. Switch to the **Edit** tab in the Inspector.
3. (Optional) Enable **Value** and **Comment** toggles to see fields.
4. Add a bucket for the value type you need.
   * Example: `Float`, `Int`, `Bool`, or list types.
5. Add a new item inside the bucket.
   * Set **Key** name.
   * Set **Value** if you want a default.
   * Add **Comment** to explain intent.

## How to choose scope

* Local: per-object state; easiest to debug.
* Scene: shared state within a scene.
* Global: shared across scenes; higher coupling risk.

## Header: GUID and persistence

* GUID identifies the Blackboard for persistence.
* Persistence toggle controls whether this Blackboard is saved.
* Edit GUID only to resolve duplicates or broken links.

## Persistence section

* `Blackboard` and `SceneBlackboard` show a separate **Persistence** section at the bottom of the Inspector.
* `GlobalBlackboard` does not show handler configuration.
* The section only appears when the main Persistence toggle is enabled.
* It is separate from bucket editing. Bucket data stays in **Edit**; handlers are configured in the dedicated section below.
* You can add multiple persistence handlers.
* Each handler can be enabled or disabled independently.
* `Target Override` lets one handler read and restore a different GameObject.
* If `Target Override` is empty, the handler uses the same GameObject as the current Blackboard.
* `Persist Local Process` restores coarse local `FlowCoreProcess` state. Do not treat it as arbitrary logic breakpoint resume.
* Use `Persist Local Process` in stable, low-interaction save windows such as hubs, camps, bases, or after major logic handoff.
* For mechanism limits and failure modes, see Persistence.

## Debugging and recovery

* `Instance ID` identifies one configured handler entry, not a handler type.
* The Inspector lets you view, copy, and manually edit `Instance ID`.
* Cached handler ids of the same type can be shown as recovery candidates.
* This gives you a manual path to align a current handler with older cached data.
* Empty ids or duplicate ids inside the same Blackboard are rejected by the Inspector.

## Toolbar actions (what they do)

* **Show Cache**: opens cache debug for this Blackboard.
* **Clear Cache**: deletes cached data for this Blackboard only.
* **Refresh Buckets**: refreshes enum bucket options after generator changes.
* **Add all keys to whitelist**: syncs keys into FlowCore Settings.

## Advanced cache operations (graph)

* Blackboard GUID is the identity used by cache filtering and package export.
* Flow/SaveLoad graphs can now operate on cached blackboard state by GUID list.
* `MatchedOnly` means "operate on the listed GUIDs."
* `ExceptMatched` means "operate on everything except the listed GUIDs."
* `Clear Blackboard Cache` removes cached blackboard entries using that GUID filter.
* `Export Blackboard Cache` creates a cache package from the filtered cached subset.
* `Replace Blackboard Cache Package` and `Append Blackboard Cache Package` change cached data only. They do not immediately change the values currently visible on live blackboards in the scene.
* Typical uses: keep only part of the cache, export a subset, or merge a prepared cache package back later.

## Play Mode notes

* Play Mode edits are runtime-only unless cache is explicitly written.
* Avoid deleting keys at runtime.

## Value sources (Payload vs Blackboard)

* For the broader choice between Blackboard, payload, TempPayload, context shortcuts, and target resolver paths, see [Value Sources and Target Resolution](/flow-core-docs/documentation/runtime-guide/value-sources-and-target-resolution.md).
* Payload reads the original object directly. It does not auto-convert from Reference types unless the specific node says so.
* Object/component/asset blackboard keys use Direct as the canonical value shape; nodes also accept their Reference wrappers for compatibility and resolve to live objects at runtime.
* List fallback is element-level. Compatibility conversion happens during access; list writes/updates target the stored list instance.
* `FlowCoreProcess` keys are safe to persist. They are saved via identity data (GUID + component index) while the UI stays as `FlowCoreProcess` for consistency.

## Fallback binding (runtime)

* If **LocalBlackboard\[0]** is missing, FlowCoreProcess will try to use a `Blackboard` component on the same GameObject and assign it to index 0.
* If **SceneBlackboard\[0]** is missing, FlowCoreProcess will try to use the `SceneBlackboard` in the active scene and assign it to index 0.
* Multiple SceneBlackboard instances are allowed; use explicit references when you need deterministic selection.

## Non-serializable value types

* Some Unity structs do not serialize. Those keys are runtime-only.
* They appear as read-only labels in the editor to avoid misleading edits.
* If you need to save them, generate a Custom Type (wrapper + serializer).
* Keys that only support FlowCore runtime Save/Load (but not Unity asset persistence) are marked with `💾`.

## Common mistakes

* Scope mismatch (Local vs Scene vs Global).
* Key exists but type does not match the node’s expected type.
* List vs Single container mismatch.
* Expecting the **Persistence** section while the main Persistence toggle is off.
* Changing `Target Override` or `Instance ID` and expecting old cached handler data to still match automatically.

## Related

* [First 15 Minutes](/flow-core-docs/documentation/tutorials/first-15-minutes.md)
* [Editor Workflow](/flow-core-docs/documentation/editor-guide/editor-workflow.md)
* [Graph Debugging](/flow-core-docs/documentation/troubleshooting/graph-debugging.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)
* [Pitfalls](/flow-core-docs/documentation/troubleshooting/pitfalls.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/editor-guide/blackboard-ui.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.