> For the complete documentation index, see [llms.txt](https://docs.raidrobotics.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.raidrobotics.org/commands-v3-state-machine/how-to/add-a-state.md).

# Add a state

Adding a state is the most common change to the superstructure during a season. This example adds a made-up **SHOOTING** state that fires the game piece from a different arm angle, but the steps are the same for any state.

The example assumes Mechanism 1 has a new `SHOOT` position (one more line in its constants) and uses a `wantShoot` flag, which step 6 adds.

{% stepper %}
{% step %}

## Add its name to `State`

```java
public enum State { IDLE, INTAKING, HOLDING, SCORING, SHOOTING }
```

{% endstep %}

{% step %}

## Add the state

In `createStateMachine()`, add the state with **one command covering every mechanism**:

```java
final var shooting = machine.addState(Command.parallel(
    mechanism1.goTo("Shoot", Mechanism1.SHOOT),
    mechanism2.eject()
).named("Superstructure.Shooting"));
```

Think about how it should end:

* If it's a job that finishes (fire one piece), make the command end by itself and add a `whenComplete()` transition out.
* If it lasts as long as someone wants it, make it run until a request goes away, and add a `when(() -> !wantShoot)` transition out.
  {% endstep %}

{% step %}

## Add transitions in and out

```java
holding.switchTo(shooting).when(() -> wantShoot && mechanism1.isAt(Mechanism1.SHOOT));
shooting.switchTo(idle).whenComplete();
```

Remember:

* `when(...)` fires the moment its condition **becomes** true.
* If two transitions out of one state fire in the same loop, the one declared **first** wins.
* Check that you can always get out of the new state. A state with no way out is a stuck robot.
  {% endstep %}

{% step %}

## Record it for logging

```java
shooting.onEnter(() -> enter(State.SHOOTING));
```

Without this, `getState()` and the `Superstructure/State` log entry won't know the robot is in the new state.
{% endstep %}

{% step %}

## Give it a color

Add it to `colorOf(...)` so the side-view drawing shows it:

```java
case SHOOTING -> new Color8Bit(255, 160, 0);
```

The `switch` won't compile until every state has a color.
{% endstep %}

{% step %}

## Add a request, if someone triggers it

If a person or an auto triggers the state, add a flag and a request (copy `requestScore()`), and a button in `DriveTeleop`. See [Add a button](https://docs.raidrobotics.org/commands-v3-state-machine/how-to/add-a-button.md).

```java
private boolean wantShoot = false;

public Command requestShoot() {
    return Requests.hold("Superstructure.RequestShoot", want -> wantShoot = want);
}
```

Also log the new flag in `periodic()`: `table.log("Want Shoot", wantShoot);`. "The driver asked and nothing happened" is the first thing to check after a bad match.
{% endstep %}

{% step %}

## Update the diagram and try it

Update the diagram in `Superstructure.java`'s header comment and the README (and [these docs](https://docs.raidrobotics.org/commands-v3-state-machine/guide/superstructure.md)). Then try it in the simulator before the robot.
{% endstep %}
{% endstepper %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.raidrobotics.org/commands-v3-state-machine/how-to/add-a-state.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
