> For the complete documentation index, see [llms.txt](https://solmateus.gitbook.io/solstack/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://solmateus.gitbook.io/solstack/solstack-the-book/use-case.md).

# Use Case

Why and where should you use solstack? A case for State Stack Machines.

Imagine you're writing a game. You need a way of controlling the flow of your program. From the main menu to the game itself; from the game to the pause menu; or from the pause menu to quitting the program.

***Solstack** will help you structure these `State`s and the `Trans`itions between them*.

Let's model something. Here are our `State`s (prefixed with `S`):

* `SMainMenu`: where the player lands on initializing the game.
* `SGame`: where the actual gameplay logic resides.
* `SPauseMenu`: where the player can save, resume playing or exit.

Since the `SMainMenu` is the first thing the user will encounter, we'll manually `Push` that `State` on our `Stack` when the program begins. Then we'll tick the `Stack` in a main loop until there are no `State`s inside it anymore.

> You can manually perform transitions on a `Stack` by using it's methods on your local instance.
>
> The loop can be achieved by using the `Stack`'s `is_running` method.

The `Stack`, at the beginning of our program, will look like this:

1. `SMainMenu`

With only one sate on the `Stack`, it is on top; and so it will have it's methods called. `SMainMenu`'s logic is simple: when the player presses *START*, it requests the `Stack` to `Push` an `SGame`. If that happens, the `Stack` would look like this:

1. `SGame`
2. `SMainMenu`

Since only the topmost state is run by the stack's `tick`, `SMainMenu` just sits there. Now the player is enjoying their game; but they wish to pause! Well, inside `SGame` all we have to do is request the stack to `Push` an `SPauseMenu` if the player ever presses *ESC*. Simple! Let's see the `Stack` again:

1. `SPauseMenu`
2. `SGame`
3. `SMainMenu`

Now `SPauseMenu` is at the top. `SGame` will be **paused**; it's still there, but it is not being executed. Inside the `SPauseMenu` there should be logic saying that if the player presses *ESC* again, the `Stack` should `Pop`. `Pop`ping means removing or completely deleting the topmost `State` at the `Stack`. In this case, `SPauseMenu` itself. The `Stack` would then, again, look like this:

1. `SGame`
2. `SMainMenu`

Finally, `SGame` is at the top again! And so, it will resume **exactly** where it left off! If the player chooses to **quit the game**, you simply request the `Stack` to `Quit`, which will `Pop` every `State` it has, making the main loop end.

This concept can be extended to much bigger patterns; and hopefully you'll find joy in structuring your application with `solstack`!