> 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/getting-started/simulator.md).

# Run it in the simulator

The whole robot program runs on a laptop: the state machine, the autos, the drivetrain and the logging. The mechanisms and the game piece are pretend, but the code running them is exactly the code that runs on the robot. Try every change here first.

## Start the simulator

```bash
./gradlew run
```

In VS Code you can also use the WPILib menu › **Simulate Robot Code** and pick **Sim GUI**.

The simulator window opens with the robot disabled.

{% stepper %}
{% step %}

## Plug in a controller

In the **System Joysticks** panel, drag **Keyboard 0** (or a real Xbox controller) onto **Joystick 0** in the **Joysticks** panel.

The keyboard keys are already set up in `simgui-ds.json`:

| Key           | Does                                       |
| ------------- | ------------------------------------------ |
| W / A / S / D | Drive (left stick)                         |
| Q / E         | Turn (right stick X)                       |
| R             | Reset which way is "forward" (left bumper) |
| Space         | Intake a game piece (right trigger)        |
| F             | Score (right bumper)                       |
| {% endstep %} |                                            |

{% step %}

## Pick an opmode and enable

In the **Robot State** panel, pick a mode, choose an opmode from the list, and enable.

* **Teleop › Drive**: the robot starts holding a game piece (a preload). Hold **F** to score it, then hold **Space** to intake another.
* **Autonomous › Example: Score, Fetch, Score**: watch the robot run the whole routine on its own.
  {% endstep %}

{% step %}

## Watch what it's doing

Open **NetworkTables › Telemetry** and double-click these to open them as widgets:

* **Superstructure › Drawing**: the robot from the side. The bar across the top is the state (gray IDLE, green INTAKING, blue HOLDING, red SCORING). The purple line is Mechanism 1, and the white tip on it is the game piece.
* **Drive › Field**: the robot on the field.

The other tables (`Mechanism1`, `Mechanism2`, `Superstructure`, `Vision`, `Auto`) show every value the code logs, live.
{% endstep %}
{% endstepper %}

## How the pretend game piece works

There's no real game piece in the simulator, so `SuperstructureSim` fakes the beam break with two simple rules:

* With Mechanism 1 at its **intake** position, running Mechanism 2 **inward** for 0.75 seconds makes a piece appear.
* Running Mechanism 2 **outward** for 0.2 seconds makes it leave.

That's enough to run the whole state machine: IDLE, INTAKING, HOLDING, SCORING and back. See [Simulation](https://docs.raidrobotics.org/commands-v3-state-machine/guide/simulation.md) for how the rest of the physics works.

## Logs from the simulator

The simulator writes real log files to the project's `logs/` folder, with the same entries the robot writes. You can open them in AdvantageScope or upload them to RAIDLogs to check logging changes without a robot.

{% hint style="warning" %}
The simulator rewrites `simgui-ds.json` when it closes, and that can drop the keyboard setup. If the keys stop working, run `git checkout simgui-ds.json` to get them back.
{% endhint %}


---

# 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/getting-started/simulator.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.
