# Stack Runtime Level: Intermediate ## Goal Understand how Stack Root and Stack Layer cooperate at runtime, how layer lifecycle branches fire, and how to debug common stack mismatches. Use this page when a graph uses layered UI, gameplay modes, temporary input contexts, or overlays where only the current top layer should update. ## Mental model Stack is a layer runtime model inside a Flow graph. It is not a replacement for FSM or BT. * Use Stack when behavior is last-in, first-out: open modal, pause the previous layer, update the modal, then pop and resume the previous layer. * Use FSM when one long-lived mode should own explicit transitions. * Use BT when priority decisions should be re-evaluated over time. `Stack Root` owns the stack state. `Stack Layer` defines the layer that can be pushed, paused, resumed, updated, and popped. ## Runtime responsibilities | Runtime part | Owns | Does not own | | ------------ | ------------------------------------------------------------------------------------ | ------------------------------------------------ | | Stack Root | Stack state, root hooks, top-layer Update loop, Pop and Pop All control. | Per-layer Push/Resume/Update/Pause/Pop branches. | | Stack Layer | Push and Pop entry points, lifecycle outputs, target/root matching, update interval. | Global scheduling or unrelated layer stacks. | Only the top layer receives Update. Lower layers remain paused until they become the top layer again. ## Lifecycle | Step | Observable behavior | | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | Push | Entering a Stack Layer Push input resolves the target Stack Root, pauses the previous top layer, activates the new layer, and starts its Update loop. | | Resume | A layer receives Resume when it becomes the top layer again after another layer is popped. | | Update | The Stack Root drives the top layer's Update branch at the layer's configured interval. | | Pause | A layer receives Pause when another layer is pushed above it. | | Pop | The top layer receives Pop when it is removed from the stack. The previous layer resumes if one exists. | | Pop All | The root repeats Pop behavior until the stack is empty. | Stack Root hooks run around stack operations. Stack Layer lifecycle outputs are where per-layer graph behavior belongs. ## Design choices * Root Name: Stack Layer `Root Name` must match the Stack Root title in the target graph. * Target: Stack Layer can push to Self, a target `FlowCoreProcess`, or a target `GameObject` with a `FlowCoreProcess`. * Unique Layers: When enabled on the root, pushing a layer already in the stack is ignored. * Update Interval: Use Frames or Seconds to control how often the top layer Update branch runs. * Update Time Mode: Seconds-based intervals can use scaled or unscaled time. * Stack Update Interrupt Mode: Controls what happens when a stack operation arrives while an Update branch is still running. Use longer update intervals for UI overlays, tutorial prompts, or mode checks that do not need per-frame work. ## Cross-graph push Cross-graph Push resolves the Stack Root in the target graph. If the target graph has a Stack Layer with the same layer name, the target layer is used. If not, the source layer is used as an external layer. Root hooks run on the target runtime context, while layer outputs run on the layer runtime context. This is useful when one graph owns the root stack, but another graph requests a layer. It also means name matching must be deliberate. ## Observable patterns | Pattern | Stack shape | What to watch | | ---------------------- | ------------------------------------------------- | --------------------------------------------------------------------- | | UI modal stack | Main menu layer, modal layer, confirmation layer. | Previous UI pauses while the modal is top; it resumes after Pop. | | Gameplay mode stack | Exploration, combat, dialogue, cutscene. | Only the top mode updates input and mode-specific logic. | | Input context stack | Default input, inventory input, rebinding prompt. | Input override pushes above normal gameplay and pops cleanly. | | Tutorial overlay stack | Gameplay layer, tutorial prompt, blocking step. | Tutorial layer can pause lower-layer Update until the step completes. | ## Authoring checks * Give Stack Root titles stable, unique names in the graph. * Use the Stack Root Names whitelist when available to reduce Root Name typos. * Keep Push, Resume, Update, Pause, and Pop branches small and observable while authoring. * Put work that belongs to every stack operation in Stack Root hooks. Put per-layer behavior in Stack Layer outputs. * Use Unique Layers when duplicate pushes would make the design ambiguous. * Avoid long synchronous work in Update. Use waits or lower update frequency when the layer does not need immediate reaction. ## Debugging reads * If Push appears ignored, check the Stack Layer target, Root Name, and whether the Stack Root Guard rejected the operation. * If the wrong layer updates, check duplicate Stack Root titles and duplicate Stack Layer names. * If Update never fires, confirm the layer is actually top of the stack and the update interval is not longer than expected. * If a previous layer never resumes, inspect whether the top layer was popped or whether Pop All emptied the stack. * If cross-graph behavior differs between scenes, verify both the target process and target graph contain the expected root/layer names. ## Failure modes | Symptom | Likely cause | First check | | ---------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------- | | Push does nothing. | Missing root, wrong target, Guard rejected, or Pass Enabled off. | Stack Layer Target and Root Name. | | Pop does nothing. | The layer is not the current top layer or the stack is empty. | Live stack size and top layer. | | Update stalls. | Update branch is still running or interrupt mode is waiting. | Stack Update Interrupt Mode and long waits. | | Duplicate layer appears. | Unique Layers is off. | Stack Root Unique Layers. | | Wrong layer runs after cross-graph Push. | Name match selected a target-layer counterpart. | Target graph Stack Layer names. | | Pop Empty hooks run unexpectedly. | Pop or Pop All ran on an empty stack. | Push/Pop order and root selection. | ## Related * [Lifecycle and Dataflow](/flow-core-docs/documentation/runtime-guide/lifecycle-and-dataflow.md) * [Stack Root](https://github.com/HaikunHuang/FlowCore/blob/main/reference/nodes/node-stack-root.md) * [Stack Layer](https://github.com/HaikunHuang/FlowCore/blob/main/reference/nodes/node-stack-layer.md) * [Invoke and Reject Modes](/flow-core-docs/documentation/reference/invoke-and-reject-modes.md) * [Performance and Failure Modes](/flow-core-docs/documentation/troubleshooting/performance-and-failure-modes.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/stack-runtime.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.