# Stack Root and Stack Layer

Level: Intermediate

## Goal

Use Stack Root and Stack Layer to model layered gameplay modes where only the top layer updates and push/pop order must stay predictable.

## When To Use This

Use Stack when the current mode can be temporarily covered by another mode and later restored. Common examples are pause menus, nested UI screens, dialogue input overrides, inspect mode, tutorial overlays, and gameplay modes that should resume after a temporary interruption.

Do not use Stack as a general scheduler. If several systems should run at the same time, use Flow, FSM groups, BT services, or separate processes instead.

## Mental Model

Stack Root owns the stack. Stack Layer is the thing that gets pushed.

Only the top layer receives Update. Lower layers remain paused until the layers above them are popped. This makes Stack a good fit for "current focus" logic: the active menu, active input context, active gameplay overlay, or active temporary mode.

## Lifecycle

| Event           | What the player or system observes                                             |
| --------------- | ------------------------------------------------------------------------------ |
| Push            | A new layer is placed on top of the stack.                                     |
| Resume          | The new top layer becomes active.                                              |
| Update          | The current top layer runs at the configured interval.                         |
| Pause           | A layer stops being top because another layer is pushed or it is being popped. |
| Pop             | The current top layer is removed.                                              |
| Resume previous | The layer underneath becomes active again, if one exists.                      |

Push and Pop can also run Stack Root instruction hooks before and after the mutation. Use those hooks for cross-layer bookkeeping, not for hidden gameplay decisions that belong in the layer itself.

## Authoring Workflow

1. Add a Stack Root.

   Give the Stack Root a clear title such as `UiStack`, `ModeStack`, or `InputStack`. This title is the Root Name that layers use when pushing into the stack.
2. Configure update behavior.

   Set the Layer Update Interval and time mode. Use frame-based updates for tight game logic and second-based updates for lower-frequency UI or polling behavior.
3. Choose Stack Update Interrupt Mode.

   Use Invalid or Abort when new stack operations should cancel the current Update branch. Use WaitToComplete when the current Update branch must finish before the stack changes.
4. Add Stack Layers.

   Create one Stack Layer for each mode, screen, or context. Wire Push, Resume, Update, Pause, and Pop outputs only where that lifecycle event needs behavior.
5. Set Root Name and target.

   The Stack Layer Root Name must match the Stack Root title. A layer can target Self, another `FlowCoreProcess`, or a GameObject with a process depending on the node settings.
6. Decide whether layers are unique.

   Enable Unique Layers when the same layer should not be pushed twice into one stack. This is useful for menus, inspect mode, and modal screens.
7. Verify push and pop.

   Add visible logs or simple UI changes to Push, Resume, Pause, and Pop while authoring. Remove noisy diagnostics after the lifecycle is clear.

## Pattern 1: UI Modal Stack

Use this for nested UI screens.

Typical order:

1. Gameplay layer is active.
2. Push `PauseMenu`; gameplay layer pauses.
3. Push `Options`; pause menu pauses.
4. Pop `Options`; pause menu resumes.
5. Pop `PauseMenu`; gameplay resumes.

Authoring rule: each screen owns its own show/hide logic in Resume and Pause or Push and Pop. The Stack Root owns the order.

## Pattern 2: Gameplay Mode Stack

Use this when a temporary mode should cover the current mode and later restore it.

Example: Exploration -> Dialogue -> Inspect Item -> Dialogue -> Exploration.

Exploration can keep its state in Blackboard or in its layer logic while Dialogue sits above it. Dialogue receives Update while it is top. Exploration does not receive Update until Dialogue and Inspect are popped.

Authoring rule: if two modes should update together, Stack is the wrong owner. Use FSM groups or separate processes.

## Pattern 3: Input Context Stack

Use this when input mapping or interpretation changes temporarily.

Example: Gameplay input pushes `DialogueInput`, then `ChoiceInput`, then pops back to dialogue and gameplay in reverse order.

Keep input enable/disable work in Resume and Pause. Keep one-off setup or cleanup in Push and Pop. This makes it easier to reason about what happens when the same context is resumed after a nested layer closes.

## Pattern 4: Tutorial Overlay

Use this when a guided overlay should pause or narrow the current interaction mode.

The tutorial layer can update until a condition becomes true, such as "player pressed confirm" or "target value changed." When complete, it pops itself and the previous layer resumes.

Authoring rule: keep tutorial progress facts in Blackboard so the overlay and the underlying system can agree on what has already happened.

## Cross-graph Push

A Stack Layer can push into a Stack Root in another graph or process. If the target graph has a Stack Layer with the same name, that target layer runs. Otherwise, the source layer is used as an external layer.

Use cross-graph push when one process owns the stack but another process requests a temporary layer. Keep Root Name and layer names stable, and prefer explicit comments near cross-graph pushes because typos can be hard to see at a glance.

## Verify The Stack

* Stack Root title matches the Stack Layer Root Name.
* Push produces one visible Push and Resume result.
* Only the top layer receives Update.
* Pop runs Pause and Pop for the current layer, then resumes the previous layer.
* Unique Layers blocks duplicate pushes when expected.
* Interrupt mode matches how Update branches should be cancelled or completed.
* Cross-graph pushes target the intended process and root.

## Common Mistakes

* Expecting Stack Root to push layers. Use Stack Layer Push.
* Expecting lower layers to receive Update.
* Using Root Names that do not match the Stack Root title.
* Leaving Stack Root names generic when more than one root exists.
* Using Stack for concurrent state families that should update together.
* Forgetting that WaitToComplete can delay a push or pop until Update work finishes.

## Related

* [Stack Runtime Model](/flow-core-docs/documentation/runtime-guide/stack-runtime.md)
* [Concepts Overview](/flow-core-docs/documentation/core-concepts/concepts-overview.md)
* [Design Levers](/flow-core-docs/documentation/core-concepts/design-levers.md)
* [Invoke and Reject Modes](/flow-core-docs/documentation/reference/invoke-and-reject-modes.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)


---

# 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/gameplay-modules/stack-root-and-layer.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.