Move simulator + AdvantageScope instructions to their own page

docs/.vitepress/config.mts

@@ -82,6 +82,7 @@ export default defineConfig({
         {
           text: 'Reference',
           items: [
+            { text: 'Running the Simulator', link: '/curriculum/robot-fundamentals/simulator' },
             { text: 'Robot Architecture', link: '/curriculum/robot-fundamentals/robot-architecture' },
             { text: 'Robot Coordinate Conventions', link: '/curriculum/robot-fundamentals/coordinate-conventions' },
             { text: 'Mapping Buttons to Commands', link: '/curriculum/robot-fundamentals/operator-command-map' },

docs/curriculum/challenges/advanced-swerve-challenges.md

@@ -17,7 +17,7 @@ SwerveDriveSubsystem:
 * You will need to have each swerve module point to its respective `angle`. This is very similar to [the earlier challenge about pointing the whole robot to an angle](/curriculum/challenges/rotating-to-a-target-orientation), except here, you are only moving a single swerve module - and the same circular-math gotchas apply, so [PID and Heading for Target Orientation](/curriculum/challenges/pid-and-heading-for-target-orientation) is worth re-reading.
 * You will need to have each swerve module drive at its goal velocity. This can also use PID, but note that the goal here is a little different than previous challenges - once the motor has reached its target speed, you will need to keep applying power or the motor will slow down again.
 
-You can check on your progress using AdvantageScope when the robot code is run in Simulation mode.
+You can check on your progress using AdvantageScope when the robot code is run in the [simulator](/curriculum/robot-fundamentals/simulator). Set up these tabs:
 * Create a "Swerve" tab and drag AdvantageKit/RealOutputs/SwerveDriveSubsystem/CurrentSwerveState into the Red state, and AdvantageKit/RealOutputs/SwerveDriveSubsystem/DesiredSwerveStates into the Blue state.
     * Note that DesiredSwerveStates won't appear until you enable the robot and ensure that the `move()` method is called at least once.
 * Create an Odometry or 3D Field tab and drag AdvantageKit/RealOutputs/PoseSubsystem/Location into Poses or 2D Poses, respectively.

docs/curriculum/challenges/altering-tank-drive.md

@@ -59,7 +59,7 @@ operatorInterface.gamepad.getifAvailable(XboxButton.A).whileTrue(togglePrecision
 ```
 - IntelliJ will flag `TogglePrecisionDriveCommand` as unknown until it is imported. Press <kbd>Alt</kbd>+<kbd>Enter</kbd> on the red text and choose the import option. (`XboxButton` is already imported in this file.)
 
-Try it out in the simulator by driving around, pressing A and seeing if the drive is slowed as expected.
+Try it out in the [simulator](/curriculum/robot-fundamentals/simulator) by driving around, pressing A and seeing if the drive is slowed as expected.
 
 Once that works, see if you can map Arcade drive to a button and test that out too!
 

docs/curriculum/challenges/command-groups.md

@@ -23,7 +23,7 @@ You might want to start by writing a new Command that can drive straight for a s
 
 Some practical notes:
 - Put your new classes alongside the others in `src/main/java/competition/subsystems/drive/commands/`.
-- To run your group in the simulator, register it the way `OperatorCommandMap` already registers `DriveToPosition` with `SmartDashboard.putData(...)`, or map it to a gamepad button like you did for precision drive. Then run the simulator the same way as in the [Tank Drive](/curriculum/challenges/tank-drive) challenge.
+- To run your group in the simulator, register it the way `OperatorCommandMap` already registers `DriveToPosition` with `SmartDashboard.putData(...)`, or map it to a gamepad button like you did for precision drive. Then [run the simulator](/curriculum/robot-fundamentals/simulator).
 - Heads up: a single Command instance can't be added to more than one CommandGroup, and can't be added to the same group twice. A square needs four turns, so you'll need four separate instances rather than reusing one.
 
 Test your program in the simulator (visualized in AdvantageScope)

docs/curriculum/challenges/moving-to-a-target-position.md

@@ -59,7 +59,7 @@ pProperty = propertyFactory.createPersistentProperty("p", 1);
   - The second argument 1 in this case is the default value that the property should start with, make this whatever makes sense for your properties as you make them
 - Now when we want to read the value of this property in our code we can do that with `pProperty.get()`, if you don't have a good place to read this value already let's just print it out in the execute() so we can see it working `System.out.println(pProperty.get());`
 
-Now let's try this out by simulating your robot like before, but now we're also going to run another new program called **Elastic (WPILib)**. The app name ends with the year of the WPILib version you installed, for example "Elastic (WPILib) 2026".
+Now let's try this out by [running the simulator](/curriculum/robot-fundamentals/simulator) like before, but now we're also going to run another new program called **Elastic (WPILib)**. The app name ends with the year of the WPILib version you installed, for example "Elastic (WPILib) 2026".
 Elastic is a program for viewing and setting these Property values.
 - Inside Elastic you're going to click on "Add Widget" in the top bar.
 - Find your "p" value in the list under "Preferences -> DriveToPositionCommand -> p" and then drag the p value out onto the dashboard.

docs/curriculum/challenges/tank-drive-solution.md

@@ -33,4 +33,4 @@ The starter code reads the left stick and sends `0` as the right power. Read the
     }
 ```
 
-If your tests pass but the robot drives strangely in the simulator, check the signs: pushing a stick forward should move that side of the robot forward.
+If your tests pass but the robot drives strangely in the [simulator](/curriculum/robot-fundamentals/simulator), check the signs: pushing a stick forward should move that side of the robot forward.

docs/curriculum/challenges/tank-drive.md

@@ -156,23 +156,13 @@ The TankDriveWithJoysticksCommand needs to get values from the human and then te
 
 We have a robot simulator that lets us test out robot code without physically having a robot. This is very helpful because we often have to share access to the competition robot among many teams and people. The simulator lets anyone on the programming team try out their code and try and find problems with it there.
 
-These instructions assume you have access to a USB Gamepad. The team usually has extra of these so ask if you don't have one.
-
-To try it out with your tank-drive code so far follow these steps:
-- In IntelliJ, in the top-right corner select the "Simulate Robot" launch configuration and then click the green play triangle beside it
-<img src="https://github.com/user-attachments/assets/cdeb67b8-27b7-4e70-886a-a6dda0f23fb8">
-  - This will open a new window called "Robot Simulation"
-  - On this new window, drag your gamepad from under "System Joysticks" on the left into the Joystick[0] slot (which is what operatorInterface.gamepad is looking for)
-  - Also in the top left under "Robot State" select "Teleoperated" to enable the robot. When you're done it should look like this:
-<img src="https://github.com/user-attachments/assets/66e2b6ea-1b31-4788-94d1-f7e10899975c">
-
-- Run the program "AdvantageScope (WPILib)", it might take a while to start and appear. The app name ends with the year of the WPILib version you installed, for example "AdvantageScope (WPILib) 2026".
-- In AdvantageScope, select File -> Connect to Simulator
-- Again in AdvantageScope, we'll now load the robot layout to show our tank on the screen. Open File -> Import Layout..., then select `AdvantageScope_layout.json` from the top of your XbotEdu repo.
-- Select either "2D top view" or "3D view" at the top of AdvantageScope
-- Use the joysticks to control the tank!
-
-Now you should be able to drive your robot around using your gamepad and the tank drive control scheme, try it out and navigate around the field to get a feel for it.
+This is the first time you'll use it, so follow [Running the Simulator](/curriculum/robot-fundamentals/simulator) from the top. You'll come back to that page in later challenges too.
+
+::: tip You'll need a gamepad
+Tank drive uses both sticks, and the keyboard fallback only has one, so ask for a gamepad if you don't have one.
+:::
+
+Once the robot is on screen, drive it around the field using the tank drive control scheme to get a feel for it. Does pushing both sticks forward go straight? Does pushing them in opposite directions spin the robot in place?
 
 
 ## Saving your code

docs/curriculum/index.md

@@ -24,6 +24,7 @@ Background you will be pointed at from the challenges, and can come back to any
 
 | Page | What It Covers |
 |------|----------------|
+| [Running the Simulator](robot-fundamentals/simulator) | Drive your code on a virtual field, and watch it in AdvantageScope |
 | [Robot Architecture](robot-fundamentals/robot-architecture) | Subsystems, Commands, the Scheduler, and how they fit together |
 | [Robot Coordinate Conventions](robot-fundamentals/coordinate-conventions) | Which way is positive, for both the robot and the field |
 | [Mapping Buttons to Commands](robot-fundamentals/operator-command-map) | Binding commands to gamepad buttons |

docs/curriculum/robot-fundamentals/simulator.md

@@ -0,0 +1,91 @@
+# Running the Simulator
+
+The simulator runs your robot code on your laptop and shows the robot driving around a virtual field. You can try out your code without a physical robot, which matters because the real robots are shared between a lot of people.
+
+Running it takes two programs side by side:
+
+- **Robot Simulation** -- runs your code, and is where you plug in a controller and enable the robot
+- **AdvantageScope** -- draws the robot on the field so you can watch what it does
+
+Come back to this page whenever a challenge says to try something in the simulator.
+
+## What you need
+
+- The XbotEdu project open in IntelliJ (see [Environment Setup](/curriculum/getting-started/environment-setup))
+- **A USB gamepad.** The team usually has spares, so ask if you don't have one.
+
+::: tip No gamepad?
+The simulator can use your keyboard as a joystick, but only for the **left stick**: <kbd>W</kbd>/<kbd>S</kbd> push it up and down, <kbd>A</kbd>/<kbd>D</kbd> push it left and right, and <kbd>Z</kbd> <kbd>X</kbd> <kbd>C</kbd> <kbd>V</kbd> are buttons. That is enough for single-stick controls like arcade drive. **Tank drive needs a real gamepad**, since the keyboard has no right stick.
+:::
+
+## 1. Start the simulator
+
+In the top-right corner of IntelliJ, select the **Simulate Robot** launch configuration, then click the green play triangle beside it.
+
+<img src="https://github.com/user-attachments/assets/cdeb67b8-27b7-4e70-886a-a6dda0f23fb8" alt="The Simulate Robot launch configuration in IntelliJ">
+
+Your code builds, and then a new window called **Robot Simulation** opens.
+
+## 2. Connect your controller and enable the robot
+
+In the Robot Simulation window:
+
+1. Find your gamepad under **System Joysticks** on the left, and drag it into the **Joystick[0]** slot. Slot 0 is the one the robot code reads from (`operatorInterface.gamepad`).
+   - Using the keyboard instead? Drag **Keyboard 0** into Joystick[0].
+2. Under **Robot State** in the top left, select **Teleoperated**. This enables the robot -- until you do, it ignores the controller.
+
+When you're done it should look like this:
+
+<img src="https://github.com/user-attachments/assets/66e2b6ea-1b31-4788-94d1-f7e10899975c" alt="The Robot Simulation window with a gamepad in Joystick[0] and Teleoperated selected">
+
+## 3. Watch the robot in AdvantageScope
+
+1. Open **AdvantageScope (WPILib)**. It can take a while to start. The app name ends with the year of the WPILib version you installed, for example "AdvantageScope (WPILib) 2026".
+2. Choose **File → Connect to Simulator**.
+3. Choose **File → Import Layout...** and select `AdvantageScope_layout.json` from the top folder of your XbotEdu repository. This sets up tabs for viewing the robot.
+4. Pick a tab at the top of the window.
+
+The tabs the layout gives you:
+
+| Tab | What it shows |
+|-----|---------------|
+| **2d top view** | The robot on the field from above. The easiest view for most challenges. |
+| **3d view** | The same thing in 3D. |
+| **Joysticks** | What the robot thinks your controller is doing. Handy when the robot doesn't respond. |
+| **Swerve** | Swerve module angles and speeds. Its data sources need setting up before it shows anything -- see the [Advanced Swerve Challenges](/curriculum/challenges/advanced-swerve-challenges). |
+| **Table** | Every value the robot code is logging. |
+| **Console** | Messages printed by the robot code. |
+
+Now drive! The robot on screen should move as you use the controller.
+
+## Making changes
+
+Your code only updates when the simulator restarts:
+
+1. Stop the simulator with the red square button in IntelliJ.
+2. Edit your code.
+3. Start **Simulate Robot** again, and re-enable the robot by selecting **Teleoperated**.
+
+If AdvantageScope shows no data after a restart, choose **File → Connect to Simulator** again.
+
+## Troubleshooting
+
+**The robot doesn't move at all.**
+Check that **Teleoperated** is selected in the Robot Simulation window -- a disabled robot ignores every input. Then check that your controller is in the **Joystick[0]** slot, not one of the others. The **Joysticks** tab in AdvantageScope shows whether the robot is seeing your input.
+
+**My gamepad isn't listed under System Joysticks.**
+Make sure it's plugged in. If it still doesn't appear, stop and restart the simulator.
+
+**Only one side of a tank drive moves.**
+You're probably using the keyboard, which has no right stick. Use a gamepad.
+
+**AdvantageScope is blank.**
+The simulator has to be running before AdvantageScope can connect. Start it, then choose **File → Connect to Simulator**. If the field is there but the robot isn't, re-import the layout file.
+
+**The robot drives the wrong way.**
+That's usually your code rather than the simulator -- check the signs on the values you send to the motors.
+
+## Learn more
+
+- [AdvantageScope](/tooling/advantagescope) -- more on AdvantageScope, including replaying logs from a real robot
+- [Elastic](/tooling/elastic) -- the dashboard used for tuning values and starting commands, introduced in [Moving to a Target Position](/curriculum/challenges/moving-to-a-target-position)