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 States and the Transitions between them.

Let's model something. Here are our States (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 States 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. Popping 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!

PreviousOverview & FeaturesNextCheatsheet

Last updated