# 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`.


---

# 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://solmateus.gitbook.io/solstack/solstack-the-book/overview-and-features.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.