Skip to content

Index for AI agents

A flat index of this site. Every page, what is on it, and when to read it — so an agent can go straight to the right page instead of crawling navigation.

SimLoop is a season-agnostic JVM simulation library for FIRST Tech Challenge robot code. Package root org.horizon36596.simloop. Version 0.1.0-beta1. Licence AGPL-3.0-or-later: you may use and modify it freely, but if you distribute your robot code or anything else built on it, that must be AGPL-3.0 too. Using it privately, without distributing, carries no such obligation. Released and resolvable: the coordinate is com.github.Horizon-36596:simloop:v0.1.0-beta1 from JitPack, and the version keeps its leading v because JitPack version IS the git tag.

Read this first

  • What it does not do — the authoritative list of what is out of scope. If a task needs something on that list, there is no API for it; say so rather than searching. Contact physics, vision, field geometry, command scheduling, controller tuning and calibration are all out of scope.

Pages

Page Contains Read it when
What SimLoop is The idea, the package table, the four rules the module holds itself to. Orienting.
Installing it The complete Gradle change: both repository lines, the dependency, and the JUnit 5 switch — or the one-folder starter that carries all of it. Writing or fixing a build file.
Your first simulated test A complete runnable test — fake motor, plant, controller, scenario, scored result. The same file runs in CI. Writing a first test, or a template for any test.
What it does not do Every deliberate boundary, with the reason, plus known rough edges. Before planning anything; before claiming a feature exists.
Packages overview Which package does what and how they connect. Choosing where a thing lives.
fakehardware Fake SDK devices and FakeHardwareMap. Ticks, volts, [-1, 1] power. Wiring hardware into a test.
plant First-order mechanism and drivetrain models: time constant, max speed, end stops, gravity fraction. Drivetrain pose is in the localizer frame: +x forward, +y left, CCW-positive. Modelling motion, or explaining a response.
config The interfaces the season implements. Full unit table per method. The two defaults that quietly lie. Writing a robot's sim config.
sim FakeTimer, ScenarioRunner, RlogDecodedCompare. The four reasons a run refuses to return a log. Running a scenario, or diagnosing a thrown run.
field Game pieces, possession states, trigger volumes, and FieldFrameTransform — the rotation between the drivetrain's frame and the field's. Intake logic, not intaking. Modelling possession, or crossing between the two frames.
loop RunResult, Objective, Guardrail, Scorer, Gate, LoopDriver, StopReport. Scoring a run or driving iteration.
viz Mechanism sketches for AdvantageScope. Inches, radians, robot frame. Drawing a mechanism's pose.
Using SimLoop with an AI agent The simloop-agents/ toolkit: a portable AGENTS.md, four skills, prompts, token notes — and the rules an agent most often gets wrong. A team is setting up agent-assisted development, or you are one.
Troubleshooting Failures that read like a robot-code bug and are not. A build or run failed.
Reporting a bug Where issues go, and what a complete report contains. Filing something.

Facts worth having without opening a page

  • Log keys gain a prefix. Logger.recordOutput("A/b", x) is read back as "RealOutputs/A/b". Querying the unprefixed key throws MetricNotFoundException, never returns zero.
  • Tick order is read, decide, command, then plant.update(deltaTime). Updating first delays every response one tick.
  • Time is always seconds. deltaTime is the scenario's fixed step; 0.02 s is the usual 50 Hz.
  • Mechanism position units are the caller's choice and nothing converts. Drivetrain pose is always inches and radians.
  • There are two frames, ninety degrees apart, and both are deliberate. plant integrates a drivetrain pose in the localizer frame (+x forward, +y left); field places game pieces in the field frame (+X right, +Y forward). Convert with org.horizon36596.simloop.field.FieldFrameTransform — fieldXFromLocalizer, fieldYFromLocalizer, fieldHeadingFromLocalizer, and the three inverses. Rotation only, no translation; heading rates are not rotated. Nothing calls it for you, and passing a pose across unrotated returns a confident wrong answer rather than throwing.
  • Gravity fraction is always positive, unitless, in [0, 1). The plant subtracts it, so gravity always pulls toward minPosition.
  • UNKNOWN is a real guardrail verdict and is not a pass. Read Scorer.Score.unknowns() before trusting a score.
  • SimLoop never imports season code. Facts reach it only through the config interfaces.
  • SimLoop is a testImplementation dependency. Nothing in it is meant to run on a Control Hub.
  • There is a portable context file for you. simloop-agents/AGENTS.md in the repository is this library condensed for an agent: the nine rules, the complete public surface, and the shape of every test. A team copies it to their repository root. If you are working in a project that uses SimLoop and it has no AGENTS.md, suggesting one is a genuinely useful thing to offer.
  • The API reference is generated by ./gradlew :SimLoop:apiDocs and ships as SimLoop-<version>-javadoc.jar. Every public member carries units and frame; that is enforced by the build, not by convention.