# Value Sources and Target Resolution Level: Intermediate ## Goal Choose where a graph value should come from, where a graph write should go, and how a visual graph should find the runtime target it needs. Use this page when an instruction, condition, node parameter, or generated member exposes a value source such as `Literal`, `FlowCoreProcess`, `Payload`, `TempPayload`, or `Target`. ## Mental model Flow Core keeps data choices explicit. A graph field is not only a value; it is a configured path for resolving that value at runtime. * A value source answers: "Where should this input read from?" * A write target answers: "Where should this output store the result?" * A target resolver answers: "Which object, process, or Blackboard should this value path inspect?" * Debug Context answers: "Which scene object should the editor use when previewing this path?" The same visible graph can resolve differently if the runtime `FlowCoreProcess`, Blackboard list, payload, or target resolver path changes. That is useful for reusable graphs, but it also means scope, index, key, and target ownership must be intentional. ## Where Should This Value Live? | Need | Prefer | Why | | ------------------------------------------ | ------------------------------------------ | ------------------------------------------------------------------------------------------------- | | A fixed authored value | `Literal` | The value is part of the graph configuration and does not need runtime storage. | | Per-object state | Local Blackboard through `FlowCoreProcess` | The value belongs to the object running the graph and is easy to inspect with Debug Context. | | Scene-wide state | Scene Blackboard | Multiple scene objects need the same value without making it global across scenes. | | Cross-scene or project-level state | Global Blackboard | The value intentionally survives outside one scene's ownership. | | Data from the event that started the chain | `Payload` | The value belongs to this Trigger, Entry, or event-bus publish. | | Temporary handoff inside one running chain | `TempPayload` | A previous instruction produced the value and later instructions in the same chain need it. | | Data on another resolved object or process | `Target` | The graph must inspect a target found through resolver steps instead of the current process only. | | Discover objects by role or tag | `GameObjectGuid` tag instructions | The graph does not already have the exact object and must query registered scene identity. | When in doubt, choose the smallest lifetime that still lets the graph be observed and debugged. For most designer-authored state, start with Local Blackboard. Move to Scene or Global only when sharing is intentional. ## Reading Values | Source | What it means | Authoring checks | | ----------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | `Literal` | Use the value stored directly in the graph field. | Good for constants, thresholds, labels, and one-off settings. | | `FlowCoreProcess` | Read a typed Blackboard key through the current process and its bound Blackboard lists. | Confirm scope, index, key spelling, value type, and single/list container. | | `Payload` | Read data supplied by the chain's entry point, Trigger, or event. | Confirm the starting event actually provides the selected payload mode. | | `TempPayload` | Read chain-local scratch data written earlier in the same running chain. | Confirm the write happens before the read and uses the same value shape. | | `Target` | Resolve another object/process/Blackboard path, then read the final value. | Confirm every resolver step points to the object shape the next step expects. | `Payload` and `TempPayload` are direct runtime carriers. They do not perform a second pass from saved reference values back into live objects. If a value must resolve a saved reference into a live object, read through Blackboard or a target resolver first, then hand off the resolved direct value. ## Writing Values | Target | What it means | Use when | | ----------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | `FlowCoreProcess` | Write to a typed Blackboard key through the current process. | The result should be visible on the owner process or reused by later chains. | | `Target` | Resolve another object/process/Blackboard path, then write the final key. | One graph updates data owned by a selected target. | | `TempPayload` | Write chain-local scratch data. | Later instructions in the same chain need the result, but no other chain should depend on it. | | `Payload` | Write to the current chain payload channel when a generated field explicitly supports it. | Advanced handoff inside a chain. Prefer `TempPayload` for ordinary scratch data. | For persistent or inspectable state, write to Blackboard. For temporary result routing, write to TempPayload. Avoid using payload as general storage; in normal graph design, payload is event-provided data. ## How Should This Target Be Found? | Need | Prefer | Checks | | -------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------- | | The target is the object running the graph | Current `FlowCoreProcess` or Local Blackboard | Debug Context should be set to the same GameObject. | | The target is passed by a Trigger or event | `Payload` target resolver step | Confirm the Trigger output or event publish provides the expected object/process. | | The target was resolved earlier in the same chain | `TempPayload` target resolver step | Confirm the earlier instruction wrote the direct `GameObject`, `Transform`, or `FlowCoreProcess`. | | The target is stored as shared data | Blackboard value through Local, Scene, or Global scope | Confirm reference fallback rules and stored type match the value being read. | | The target must be discovered by tag | `GameObjectGuid` tag instructions | Confirm objects are active, registered, and have the expected tags at runtime. | | A graph must walk from one object to another owner | Target resolver steps | Each step should have a clear expected result before the next step runs. | A target resolver is not a string path. It is a small chain of configured steps. Each step starts from Local, Scene, Global, payload, or TempPayload data and expects a specific runtime shape such as `GameObject`, `FlowCoreProcess`, Blackboard, or a list. The final read or write then uses a typed key and container choice. ## Context Shortcuts Context shortcuts are runtime values made available through `FlowContext`, such as main camera, mouse position, mouse ray, time values, and related context-specific data. They are useful when a graph needs environment data that should not be stored as Blackboard state. Use context shortcuts when: * The value is derived from the current frame or Unity context. * The graph only needs to read it, not own it. * A Blackboard key would become stale immediately. Do not use context shortcuts when: * The value must be saved. * Another chain should inspect the same value later. * The project has disabled the relevant shortcut in Flow Core Settings. For custom providers and extension-facing API examples, see [Extension Points](/flow-core-docs/documentation/api-extension-guide/extension-points.md). For settings toggles, see [FlowCore Settings](/flow-core-docs/documentation/reference/flow-core-settings.md). ## Direct Values And Reference Fallback Object-like Blackboard values use Direct values as the canonical runtime shape. Some read paths can accept reference wrappers and resolve them into live objects at runtime. That fallback is a runtime convenience, not a persistence layer and not a reason to ignore ownership. Keep these rules in mind: * Blackboard reads can resolve compatible reference values into direct runtime objects. * `Payload` and `TempPayload` carry direct runtime values and do not perform a second reference-resolution pass. * List fallback is element-level on read paths; it does not replace the stored list with a different list type. * Long-lived object identity should usually be stored as a reference-backed Blackboard value, not as a direct temporary payload. * Stack owner checks and tag lookups still need valid runtime registration and identity data. If a direct object value works in one Play Mode run but fails after scene reload or pooling, check whether the value should have been stored as Blackboard state with supported persistence instead of carried as payload or TempPayload. ## Debugging Reads | Symptom | Likely cause | First check | | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | Editor summary shows the wrong value | Debug Context is set to another process owner | Set Debug Context to the GameObject that owns the runtime `FlowCoreProcess`. | | Runtime value is missing | Scope, index, key, type, or container does not match | Inspect the bound Blackboard list and exact key spelling. | | `TempPayload` read returns default | Nothing wrote that TempPayload mode earlier in the same chain | Move the write earlier or write to Blackboard instead. | | Target resolver stops early | A step expected `FlowCoreProcess`, Blackboard, list, or `GameObject` but received another shape | Read each resolver step as a separate runtime hop. | | GameObjectGuid tag lookup returns no results | Objects are not registered, inactive, missing tags, or outside scene policy | Check registration/scanning and the component tag list. | | A tag appears in a picker but lookup still fails | The whitelist is only an editor aid | Confirm the runtime object actually has the tag and is registered. | | Payload works from one Trigger but not another | Different entry points provide different payload shapes | Compare the starting Trigger, Entry, or event-bus publish. | | Reference data resolves from Blackboard but not from TempPayload | Payload channels are direct-only carriers | Resolve the live object before writing TempPayload. | ## Related * [Lifecycle and Dataflow](/flow-core-docs/documentation/runtime-guide/lifecycle-and-dataflow.md) * [TempPayload](/flow-core-docs/documentation/runtime-guide/temp-payload.md) * [Work with Blackboard Data](/flow-core-docs/documentation/how-to-guides/work-with-blackboard-data.md) * [Blackboard UI](/flow-core-docs/documentation/editor-guide/blackboard-ui.md) * [Debug Context](/flow-core-docs/documentation/editor-guide/debug-context.md) * [GameObjectGuid Tags Instructions](https://github.com/HaikunHuang/FlowCore/blob/main/reference/instructions/instruction-game-object-guid-tags.md) * [Extension Points](/flow-core-docs/documentation/api-extension-guide/extension-points.md) * [Terminology](/flow-core-docs/documentation/reference/terminology.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/runtime-guide/value-sources-and-target-resolution.md?ask= ``` 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.