Simulation Architecture

Core Principle

Reusable code goes in sim-core. Game-specific code goes under that year’s robot project.

The simulator runs the same Robot.java and subsystem code that deploys to the real robot. Instead of talking to real motors and sensors, the code talks to simulated physics engines.

Two Layers

When a new game drops, you only write the year-specific layer. Everything else is inherited.

Dual-Engine Architecture

The sim pairs two physics engines, each handling what it does best:

              Your Robot Code
             (Robot.java, subsystems, commands)
                    |
                    | motor voltages, sensor reads
                    v
        +-----------+-----------+
        |                       |
        v                       v
   MapleSim                 sim-core (ODE4J)
 (Drivetrain)             (Everything Else)
        |                       |
        | pose, velocity        | collisions, intake,
        | encoders, gyro        | scoring, terrain, vision
        |                       |
        v                       v
   Year-Specific SimManager (orchestrator)
        |
        v
   AdvantageKit → AdvantageScope

MapleSim (Drivetrain)

MapleSim  is purpose-built for FRC swerve simulation:

• Motor models (voltage → torque, with current limits)
• Tire dynamics (slip, traction, carpet friction)
• Gear ratios (drive and steer reductions)
• Encoder/gyro feedback (TalonFX + Pigeon2 sim state)

ODE4J via sim-core (Everything Else)

ODE4J  handles general rigid body physics:

• Hundreds of game pieces with gravity, bounce, and collisions
• 3D field geometry (walls, ramps, bumps) from OBJ meshes
• Intake zones, launch trajectories, scoring detection
• Vision simulation (Limelight AprilTag estimates + game piece detection via frustum sensors)

Why Two Engines?

Key design decision: MapleSim’s arena is configured with AddRampCollider=false — MapleSim only handles the hub collision boundary (2D). ODE4J handles all 3D terrain including ramps.

sim-core Internals

Located at robot/sim-core/src/main/java/frc/sim/:

Packages

Key Classes

Adaptive Sub-stepping

Fast objects (e.g., a ball at 30 m/s) can tunnel through thin walls in a single 20ms step. PhysicsWorld.step() detects the fastest body and subdivides the timestep so no object moves more than 0.1m per sub-step. Most frames use 1 sub-step; extra sub-steps only kick in during launches.

Proximity Sleep/Wake

With hundreds of game pieces, simulating every one is expensive. GamePieceManager uses a hysteresis pattern:

• Wake pieces within 1.5m of the robot
• Sleep pieces beyond 3.0m

The gap prevents thrashing at the boundary. Fast-moving pieces (launched shots) also create wake zones so nearby pieces react to collisions. Result: only ~20-30 pieces are active at any time, even with 400+ on the field.

Terrain Surfaces

Four built-in contact materials:

Per-geom overrides let you assign different materials to different field elements.

Sensor Geoms (Scoring)

Scoring zones use ODE4J sensors — they detect overlap without creating contact joints. Pieces pass through the trigger while the system records the score.

Chassis Control Modes

Game Piece Lifecycle

This is the same regardless of game year:

SPAWN          → Created on field by year-specific layout
  ↓
DISABLED       → Moved underground, zero physics cost
  ↓  (robot within wake radius)
AWAKE          → Physics enabled
  ↓  (overlaps intake zone + intake active)
CONSUMED       → Removed from world, hopper counter increments
  ↓  (mechanism fires, cooldown expired, hopper > 0)
LAUNCHED       → New body spawned at mechanism exit with 3D velocity
  ↓  (gravity, bounces off walls/field)
IN FLIGHT      → Normal rigid body physics
  ↓  (enters scoring sensor zone)
SCORED         → Removed from field, score increments

Counter-based tracking: GamePieceManager tracks held pieces with heldCount / maxCapacity. intakePiece() removes from world + increments counter. launchPiece() decrements counter + spawns new physics body. Pieces are grouped by type in a Map<String, List<GamePiece>>.

Vision Simulation

frc.sim.vision provides Limelight camera simulation in two modes:

• VisionSimManager — manages multiple simulated cameras (AprilTag and game piece), maintains a 2-second pose history buffer, and coordinates game piece sensor enable/disable around the physics step
• LimelightSim — per-camera simulation supporting two modes (see below)
• CameraConfig / LimelightType — hardware profiles (LL3: 30fps / 25ms latency, LL4: 60fps / 20ms latency)

AprilTag Mode

Each tick, the robot’s true pose is recorded into a TimeInterpolatableBuffer. When a camera “captures a frame” (based on its FPS), it samples the pose at now - latency to simulate realistic measurement delay. Results are published to NetworkTables in YALL/PoseEstimate format with fake fiducial data (4 tags, tuned for tight stddevs).

Game Piece Mode

A LimelightSim in game piece mode builds a 3D trimesh frustum (from the camera’s FOV, near plane, and far plane) and attaches it to the chassis body as an ODE4J sensor. The frustum follows the robot automatically since it’s attached to the chassis rigid body.

Detection pipeline:

1. prepareGamePiece() — enable/disable the frustum sensor based on FPS gating (called before physics step)
2. ODE4J collision detection runs — the frustum detects overlapping game piece bodies
3. updateGamePiece() — reads sensor contacts, finds the closest piece, converts its 3D position to camera-relative angles, and publishes tv/tx/ty/ta to NetworkTables (called after physics step)

The published NT entries are consumed by LimelightHelpers.getTV/getTX/getTY/getTA, so subsystem code (e.g. IntakeSubsystem) reads the same API in sim and on the real robot.

Motor Controller Adapters

The year-specific SimManager bridges MapleSim to CTRE’s simulation APIs with bidirectional adapters:

MapleSim → (position, velocity) → Adapter → TalonFX SimState
MapleSim ← (commanded voltage) ← Adapter ← TalonFX SimState

Two adapter types in 2026’s RebuiltSimManager:

• TalonFXMotorControllerSim — syncs a single TalonFX motor
• TalonFXMotorControllerWithRemoteCanCoderSim — syncs TalonFX rotor state AND CANcoder absolute position (used for swerve steer modules)

Both connect to SimulatedBattery for brownout effects.

Component Animation

The SimManager maintains rotation accumulators for animated mechanisms (rollers, feeders, shooter wheels). Each tick, if a mechanism is active, its angle accumulator increments by a speed constant. These are published as an array of Pose3d values to AdvantageKit, which AdvantageScope renders as articulated robot parts.

3D Models & Git LFS

AdvantageScope can render the actual robot CAD in its 3D view using GLB (binary glTF) model files. These files live in sim_models/ inside each year’s robot project.

Directory Structure

robot/2026-rebuilt/sim_models/
├── Robot_Components/           # Articulated model (individual components)
│   ├── config.json             # AdvantageScope config (maps components to GLB files)
│   ├── model.glb               # Base chassis
│   └── model_0.glb ... model_15.glb  # Individual mechanism parts
└── Robot_Static/      # Single-mesh model (no moving parts)
    ├── config.json
    └── model.glb

Git LFS (Large File Storage)

GLB files are binary and can be large (the 2026 models total ~100MB). To keep the repo lean:

• GLB files are stored via Git LFS  — the .gitattributes at the repo root routes all *.glb files through LFS automatically
• Models are excluded from clone — the .lfsconfig at the repo root sets fetchexclude = **/sim_models/**, so cloning the repo downloads tiny pointer files (~130 bytes) instead of the real models
• Models download on demand — each year’s build.gradle has a fetchModels task that pulls only that year’s models via git lfs pull
• config.json is NOT in LFS — it’s a small JSON file tracked normally by git, always available on clone

How It Works for Developers

From a developer’s perspective, this is invisible:

1. Adding models: Just git add / git commit your GLB files. LFS handles the rest behind the scenes.
2. Getting models: Run ./gradlew simulateJava — the fetchModels task runs automatically and downloads any missing models. You can also run ./gradlew fetchModels directly.
3. Skipping model download: Pass -PskipFetchModels to skip the download (e.g. ./gradlew simulateJava -PskipFetchModels).
4. No LFS installed? The build still works. You just won’t see the robot model in AdvantageScope. The Gradle task prints install instructions.

New Year Setup

When creating a new year’s robot project from the template:

1. The fetchModels Gradle task is already included in the template’s build.gradle
2. The sim_models/Robot_Components/ and sim_models/Robot_Static/ directories exist with placeholder config.json files
3. Export your CAD as GLB files into the appropriate folder — Robot_Components/ for articulated models (separate mechanism parts) and Robot_Static/ for a single static mesh
4. Update the config.json files with your component rotations and positions
5. Commit and push — LFS tracks the GLB files automatically

2026 REBUILT Specifics

Code: robot/2026-rebuilt/src/main/java/frc/robot/sim/

Vision cameras: Three simulated Limelights:

• limelight-two (LL4, AprilTag): 60 FPS, front-right mount, 25° inward yaw
• limelight-five (LL3, AprilTag): 30 FPS, front-left mount, -25° inward yaw
• limelight-one (LL4, Game Piece): 5 FPS, rear-facing mount, detects fuel within 0.3–3.0m frustum

Field: 16.54m × 8.07m with two hubs, ramps, 360-400 fuel balls in neutral zone, 24 per depot.

Hood state machine: RebuiltSimManager tracks hood angle (simHoodAngleRad) by watching the ShooterHood subsystem state (AIMING_UP / AIMING_DOWN) and applying HOOD_ADJUST_RATE within min/max bounds.

Field mesh loading: RebuiltField tries the deploy directory first, falls back to classpath. Check console for warnings if the mesh isn’t found.

The Sim Loop (every 20ms)

1. MapleSim steps drivetrain (motor voltages → tire forces → chassis state)
2. Read robot pose + velocity from MapleSim
3. Convert velocity to world frame (robot-relative → field-relative rotation)
4. Update ODE4J chassis body (corrective force to match MapleSim velocity)
5. Wake nearby game pieces (1.5m radius)
6. Check intake zone (before physics step, to prevent re-consuming launched balls)
7. Enable/disable game piece detection sensors (FPS gating)
8. ODE4J physics step (with adaptive sub-stepping)
9. Sync gyro (MapleSim yaw → Pigeon2 sim state)
10. Update AprilTag vision (write true pose to simulated Limelight NT entries)
11. Update game piece detection cameras (read sensor contacts → publish tv/tx/ty/ta)
12. Update game piece states (auto-disable settled pieces)
13. Check scoring zones (sensor geom overlaps)
14. Update hood angle (watching ShooterHood state)
15. Update shooter (launch if firing + cooldown expired + hopper > 0)
16. Update animation accumulators (rollers, feeders, shooter wheels)
17. Publish telemetry (poses, scores, components → AdvantageKit)

Design Patterns

Supplier-Based Decoupling

ShooterSim, IntakeZone, and other bridges use Supplier<T> / DoubleSupplier to lazily read subsystem state. This avoids snapshot inconsistencies within a tick and decouples sim-core from concrete subsystem classes.

BiConsumer Publish Callback

GamePieceManager uses BiConsumer<String, Pose3d[]> for telemetry publishing. This decouples sim-core from AdvantageKit — the year-specific code provides the publish callback.

Kinematic Follower

MapleSim owns the “truth” for robot pose. ODE4J applies corrective forces (F = mass × (v_desired - v_current) / dt) to match, while ODE4J’s contact constraints naturally prevent wall penetration. This gives you the best of both engines without double-counting.

Building a Sim for a New Game Year

1. Define game piece properties — shape, mass, radius, bounce via GamePieceConfig.Builder
2. Generate the field collision mesh — see below
3. Configure the chassis — mass, dimensions via ChassisConfig.Builder
4. Write the SimManager — initialize MapleSim + sim-core, run the sim loop, publish telemetry
5. Add scoring zones — sensor geoms at scoring locations, register with ScoringTracker
6. Add mechanism bridges — connect subsystem state to intake zones and launch parameters

Use RebuiltSimManager as the reference implementation.

Generating the Field Collision Mesh

The sim needs an OBJ file that defines the field’s collision surfaces (walls, ramps, hubs, etc.). We use FEDS Bot to generate a Python script that outputs the OBJ from hardcoded field dimensions. See robot/2026-rebuilt/src/main/resources/generate_field.py for the 2026 example.

The workflow:

1. Write a prompt asking for a Python script to generate this year’s field collision mesh. Include field details — both manually written descriptions and references from the game manual. See the 2026 prompt  as an example.
2. Give the prompt to FEDS Bot (make sure you’ve added the new game manual PDF to ./game-manuals/ first so it has context).
3. Save the generated script to robot/20XX-GAMENAME/src/main/resources/generate_field.py
4. Run it — it produces field_collision.obj
5. Visually inspect the OBJ at 3dviewer.net , then load it in the sim and drive around in AdvantageScope — verify that obstacles line up with the visual field
6. If something’s off, go back to FEDS Bot to tweak the script and repeat from step 3

Troubleshooting

Robot doesn’t move: Check that the sim GUI shows “Enabled” in “Teleop”. Make sure a controller or keyboard is connected.

Balls fall through the floor: Verify PhysicsWorld has gravity enabled and the OBJ mesh loaded without errors.

Balls tunnel through walls: Adaptive sub-stepping should prevent this. If it happens, the launch velocity may exceed the 0.1m sub-step threshold.

ClassNotFoundException: frc.sim.core.PhysicsWorld: sim-core isn’t on the classpath. In settings.gradle:

include ':sim-core'
project(':sim-core').projectDir = new File(settingsDir, '../sim-core')

And in build.gradle:

implementation project(':sim-core')

Slow performance: Check active piece count. Default wake radius (1.5m) should keep it under 30. Also make sure you ran the mesh simplify script.

Encoder mismatch: Check MapleSim gear ratios match the physical robot config.