Expand description
Solstack
Solstack is a library that enables you to manage the control flow of your application through what’s known as a state stack machine.
This library provides a Stack
type that holds a stack of State
s. When the stack is ticked (a tick being an update/frame call) it executes the methods on the topmost state it holds. This means that only one state is run at a time; the one at the top.
-
You can read The Book.
-
Take a look at the examples on the git repository.
-
Search documentation at the crate’s docs.
-
Watch the project develop through its changelog!
Project is in early development, things may change around! Take a look at the changelog before updating.
Features
- A simple
State
trait to implement. - An easy to use
Stack
State Machine. - Multiple
Trans
itions between states. - Multiple state methods, such as
on_start
,on_pause
,on_tick
, etc. - New in v0.3.0:
- Shadow tick method that is always run once the stack is ticked, even if the state isn’t the topmost at said the stack.
Use case
When you are writing a game, for instance, you’ll probably need a way of organizing the different states of the application as a whole. When the application starts, you might have a simple MenuState
on your stack, that asks the player for input. If the player clicks on “Play”, you want to push another state on top of the stack, say, GameState
.
Only the State
on top of the stack has it’s methods executed by the stack; this means that the MenuState
is essentially paused. If the player wants to pause the game, inside your GameState
there could be logic that says that on pressing Esc
the stack should push a PauseMenuState
on top of the stack. This won’t delete the GameState
, it will simply pause it, since now the stack will run only the topmost state PauseMenuState
.
If the player wants to exit the game, you can pop everything from the stack, leaving it empty. If the player wants to get back to the game, you can simply pop the PauseMenuState
out of the stack, resuming the one under it GameState
.
For a more detailed usage example, see The Book (liked at the beginning of this page).
Get started
You can find a very simple example here. For more detailed examples, take a look at the examples
folder on the project’s github repo. For a complete tutorial, take a look at The Book.
Links are available at the start of this page.
use solstack::prelude::*;
use solstack::macros::*; // Easy abstractions over boilerplate-y code.
#[derive(Default)]
struct GameData {
value: i32
}
struct AddOneAndPrintState;
impl State<GameData> for AddOneAndPrintState {
fn on_start(&mut self, data: &mut GameData) {
data.value = 10;
println!("on_start `make data be 10` > GameData({})", data.value);
}
fn on_tick(&mut self, data: &mut GameData) -> Trans<GameData> {
data.value += 1;
println!("on_tick `add one to data` > GameData({})", data.value);
Trans::None
}
}
fn main() {
let mut data = GameData::default();
let mut stack = Stack::<GameData>::new();
stack_push!(stack, data, AddOneAndPrintState);
stack_tick!(stack, data);
stack_tick!(stack, data);
}
Thanks
The documentation will always be updated.
Thank you for using solstack
!
By Sol solmateusbraga@gmail.com
Modules
Macros
stack.isolate(&mut data, Box::new(FooState {}))
.
Use stack_isolate!(stack, data, FooState {}, BarState {}, ...)
OBS.: Don’t use &mut data
as a parameter, but simply data
.stack.pop(&mut data)
.
Use stack_pop!(stack, data)
Or stack_pop!(stack, data, 3)
3 being the amount of states to pop.
OBS.: Don’t use &mut data
as a parameter, but simply data
.stack.push(&mut data, Box::new(FooState {}))
.
Use stack_push!(stack, data, FooState {}, BarState {}, ...)
stack.quit(&mut data)
.
Use stack_quit!(stack, data).
OBS.: Don’t use &mut data
as a parameter, but simply data
.stack.replace(&mut data, Box::new(FooState {}))
.
Use stack_replace!(stack, data, FooState {}, BarState {}, ...)
OBS.: Don’t use &mut data
as a parameter, but simply data
.stack.tick(&mut data)
.
Use stack_tick!(stack, data)
.
OBS.: Don’t use &mut data
as a parameter, but simply data
.Trans::Isolate(Box::new(FooState {}))
.
Use trans_isolate!(FooState {})
Trans::None
.
Use trans_none!()
Trans::Pop
.
Use trans_pop!()
Trans::Push(Box::new(FooState {}))
.
Use trans_push!(FooState {})
Trans::Quit
.
Use trans_quit!()
Trans::Replace(Box::new(FooState {}))
.
Use trans_replace!(FooState {})