# TempPayload

Level: Intermediate

## Goal

Understand when to use TempPayload, how it differs from payload and Blackboard data, and how to avoid losing or misreading temporary runtime values.

Use this page when an Action or chain needs to pass a resolved value to later instructions without turning that value into persistent Blackboard state.

## Decision guide

| Use         | When                                                                                   | Lifetime                                     |
| ----------- | -------------------------------------------------------------------------------------- | -------------------------------------------- |
| payload     | The value comes from the Trigger, Entry, or event that started the chain.              | Current chain.                               |
| TempPayload | The value is produced during the chain and only later steps in the same chain need it. | Current chain.                               |
| Blackboard  | The value must be shared, inspected, reused by another chain, or saved.                | Depends on Blackboard scope and persistence. |

TempPayload is chain-local scratch data. It is useful for handoff inside one running chain. It is the wrong place for state that should survive after the chain ends.

## What TempPayload is

TempPayload is a writable typed slot on the current runtime context.

* It can be written by instructions during a chain.
* Later values in the same chain can read it through TempPayload value sources or target resolver steps.
* It is cleared when the chain ends.
* It is never serialized or persisted.
* It stores direct runtime values, not saved references or GUID-style reference variants.

The trigger payload is provided at chain start. TempPayload is written by graph behavior after the chain has already started.

## Supported value shapes

TempPayload supports common single values and list values used by Flow Core value sources, including:

* `bool`
* `int`
* `float`
* `string`
* `Vector2`
* `Vector3`
* `GameObject`
* `Transform`
* `FlowCoreProcess`
* Lists of the same supported value families

Read the same value shape that was most recently written. If a later instruction writes a different TempPayload type, it replaces the active slot for subsequent reads.

## Typical patterns

| Pattern                           | Why TempPayload fits                                                                                                                                                                                                                              |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Target resolver handoff           | Resolve a target once, write it to TempPayload, and let later instructions use `TempPayload` as the target source. See [Value Sources and Target Resolution](/flow-core-docs/documentation/runtime-guide/value-sources-and-target-resolution.md). |
| Short interaction chain           | Store the currently interacted object for the rest of the interaction response.                                                                                                                                                                   |
| Temporary component/process route | Resolve a `FlowCoreProcess` or `Transform` once and reuse it within the same chain.                                                                                                                                                               |
| Intermediate calculation          | Store a value that only exists to feed the next few instructions.                                                                                                                                                                                 |

If another chain, another scene object, or a later frame sequence needs to inspect the value independently, use Blackboard instead.

## Direct-only references

TempPayload carries direct runtime objects such as `GameObject`, `Transform`, and `FlowCoreProcess`.

It does not perform a second pass from saved reference values back into live objects. If a value comes from Blackboard, the Blackboard value resolver must produce the live object before it is written into TempPayload.

This keeps TempPayload predictable: it is a runtime handoff slot, not a persistence layer.

## Authoring checks

* Choose TempPayload only after confirming the value is needed inside the same chain.
* Write TempPayload before the first instruction or value that reads it.
* Keep type usage obvious: do not write a `GameObject` and later read a `string`.
* Use comments or node summaries when TempPayload carries the main target for a multi-step Action.
* Write to Blackboard instead if debugging, cross-chain reuse, scene sharing, or save/load behavior matters.

## Debugging reads

* If a TempPayload read returns the default value, confirm the write happened earlier in the same chain.
* If the wrong value is read, look for a later TempPayload write that overwrote the active slot.
* If a chain works from one Trigger but not another, compare the original payload and the instructions that write TempPayload.
* If a value is needed after a wait, confirm the chain is still the same running chain and was not canceled or restarted.
* If a value must survive scene reload, application restart, or another chain, move it to Blackboard and persistence.

## Common mistakes

| Mistake                            | Result                                                              | Fix                                                           |
| ---------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------- |
| Using TempPayload as global state. | Other chains cannot depend on it.                                   | Use Scene or Global Blackboard.                               |
| Reading before writing.            | Default or unresolved value.                                        | Move the write earlier in the chain.                          |
| Overwriting with another type.     | Later reads of the old type fail or return defaults.                | Keep one value shape per chain section.                       |
| Expecting persistence.             | Value disappears when the chain ends.                               | Store persistent data in Blackboard.                          |
| Expecting reference fallback.      | Direct object reads may fail if the live object was never resolved. | Resolve through Blackboard or target resolver before writing. |

## Related

* [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)
* [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)
* [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/temp-payload.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.