> 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/guide/simulation.md).

# Simulation

The whole robot program runs on a laptop, so you can test the state machine, autos and logging without a robot. To run it, see [Run it in the simulator](https://docs.raidrobotics.org/commands-v3-state-machine/getting-started/simulator.md). This page explains how the simulation works, and how to extend it.

## How simulation works

The robot code never knows it's being simulated. It talks to the same `TalonFX` objects as always. Each loop, `SuperstructureSim` sits "behind" each motor and plays the part of the real world:

```mermaid
flowchart LR
    C[Robot code] -- setControl --> T[TalonFX<br/>real class]
    T -- voltage --> P[Physics model<br/>SuperstructureSim]
    P -- position, velocity --> S[TalonFX sim state]
    S --> C
```

So for every motor there are three steps:

1. Read the voltage the motor is putting out.
2. Step a physics model by one loop.
3. Write the model's position and velocity back into the motor's sensor.

The drivetrain does the same thing inside CTRE's code (`CommandSwerveDrivetrain.startSimThread`).

`Robot` creates `SuperstructureSim` only in the simulator. On the real robot, none of this code runs. That `if (isSimulation())` in `Robot.java` is the only simulator check in the whole project.

## What's simulated

| Part        | Model                                                                                                                  |
| ----------- | ---------------------------------------------------------------------------------------------------------------------- |
| Mechanism 1 | `SingleJointedArmSim`: an arm with gravity, built from `Mechanism1`'s own constants (gear ratio, length, mass, limits) |
| Mechanism 2 | Rollers with nothing to push against: they spin in proportion to the voltage                                           |
| Game piece  | Faked with simple rules (below)                                                                                        |
| Battery     | `BatterySim`: more current drawn means lower voltage                                                                   |
| Drivetrain  | CTRE's swerve simulation, every 4 ms                                                                                   |

The models are built from the mechanism's own constants, so the simulation and the code can't disagree about the hardware.

### Time

The simulation steps by the time that really passed, not an assumed 20 ms. The TalonFX runs Motion Magic in real time, so physics on a different clock would drift from its profile. The step is capped at 0.1 s, so pausing in a debugger can't cause one giant step.

### The pretend game piece

Sensors with no physics, like beam breaks and limit switches, are faked with simple rules:

| Rule                                                                       | Time   |
| -------------------------------------------------------------------------- | ------ |
| Mechanism 1 at INTAKE and Mechanism 2 above +1 V: a piece arrives after... | 0.75 s |
| Mechanism 2 below −1 V: the piece leaves after...                          | 0.2 s  |

The sim then sets the beam break DIO to match (a beam break reads `false` when something blocks it).

`preload()` starts the robot holding a piece, like a match. `Robot` calls it right after creating the sim. Remove that call to start empty.

### The battery

Mechanism currents pull the simulated battery voltage down. That makes `SystemStats/BatteryVoltage` move in the log, so RAIDLogs' battery checks have something realistic to read from a simulator log. The drivetrain reads this voltage for its own simulation.

### Mechanism 1's sensor offset

The real motor's built-in sensor reads 0 wherever the arm is when it powers up, and `Mechanism1`'s `setPosition(STOW)` adds the offset on top. The sim copies that: it writes the angle **moved since startup**, times the gear ratio, as the raw rotor position. With an absolute CANcoder there's no such offset; see `SimpleSuperstructure-v3`.

## Adding a mechanism to the simulation

{% stepper %}
{% step %}

## Expose the motor

Give the mechanism a `getMotor()` (like `Mechanism1` has), and grab its `getSimState()` in the `SuperstructureSim` constructor.
{% endstep %}

{% step %}

## Pick a model

| Mechanism     | Model                 |
| ------------- | --------------------- |
| Pivots        | `SingleJointedArmSim` |
| Lifts         | `ElevatorSim`         |
| Spins         | `FlywheelSim`         |
| Anything else | `DCMotorSim`          |

Build it from the mechanism's own constants.
{% endstep %}

{% step %}

## Add its three steps

In `update()`: set the model's input voltage from the motor, step the model, and write position and velocity back. Add its current to the battery calculation.
{% 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/guide/simulation.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.
