> 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/overview-and-features.md).

# Overview & Features

### Overview

`State`s have all of the methods you'll need. Here's an overview:

* `on_start` — executed when this `State` is first pushed onto the `Stack`.
* `on_stop` — executed when this `State` is popped from the `Stack`.
* `on_pause` — executed when another `State` is pushed on top of this one in the `Stack`.
* `on_resume` — executed when this all of the `State`s above this one are popped from the `Stack`.
* `on_tick` — executed every time the `Stack` holding this `State` has it's `tick` method called.
* `on_shadow_tick` — same as `on_tick`, but is always run independently of this `State`'s position in the `Stack`.

To hop between `State`s you'll return a `Trans`ition `enum` from `on_tick` or similar methods, requesting the `Stack` to perform such transition next tick. Here's an overview:

* `Trans::None` — requests the `Stack` to do nothing.
* `Trans::Quit` — requests the `Stack` to `Pop` every `State` it is holding.
* `Trans::Push(Box::new(State))` — requests the `Stack` to `Push` the provided `State` on top.
* `Trans::Pop` — requests the `Stack` to pop the topmost `State` it is holding, deleting it.
* `Trans::Replace(Box::new(State))` — requests the `Stack` to `Pop` once and `Push` the provided `State`.
* `Trans::Isolate(Box::new(State))` — requests the `Stack` to `Pop` everything and `Push` the provided `State`.

> Transitions may be requested directly of the `Stack` or by returning a `Trans` from inside a `on_tick` or `on_shadow_tick` method of a `State`.

### Features

* An easy to implement `State` `trait`.
* An easy to use **State `Stack` Machine** `struct`.
* An easy to use set of **`Trans`itions between `States`**.
* New in `v0.3.0`:
  * `on_shadow_tick` is provided on `State`s; similar to `on_tick` but *is always executed independently of the `State`'s position* in the `Stack`.