MWLib

MW-Lib is the MARS/WARS robot library. Everything the other pages in this section describe as "ours" lives there: the subsystem state machine, the mechanisms, the super state machine, the swerve drive, the behavior-tree engine, logging and the vision helpers. Robot projects depend on a released version of it, and the lessons in Scriptum do too.

Javadoc for the latest release: frc-team-4143.github.io/MW-Lib.

---

What Is in It

Package	What it holds	Page
com.marswars.subsystem	MwSubsystem (the state machine every subsystem extends), MwSuperStateMachine (RobotContainer), SubsystemManager	Subsystems, State Machines
com.marswars.mechanisms	ArmMech, ElevatorMech, FlywheelMech, RollerMech, TurretMech, MotorConfig	Mechanisms
com.marswars.swerve_lib	MwSwerveSubsystem, MwSwerveConstants, SwerveDriveConfig, SwerveStates	Swerve
com.marswars.bt	The behavior-tree engine (core, control, decorator, action, xml), RobotStateNodes, swerve.SwerveNodes, monitor, debug.BtLiveServer	Autonomous
com.marswars.auto	Auto, AutoManager (the chooser), BehaviorTreeAuto, Choreo trajectory loading	Autonomous
com.marswars.logging	MwLog, the AdvantageKit-backed logger, tunables and replay	Telemetry
com.marswars.util	RobotIdentity, preferences, alliance flipping	Robot Identity
com.marswars.vision, proxy_server	AprilTag localization, vision simulation	Vision
com.marswars.dashboard, sensors, geometry, data_structures	Elastic helpers, sensor wrappers, field geometry, small containers

---

Depending on It

Versions are YY.minor.patch: the first number is the season the architecture is written for (27.0.0 opens the 2027 season), the second a feature release within it, the third a fix. Tags carry a v (v27.0.0). The robot project pins one version in build.gradle. We use JitPack, which builds every tag on first request with no token or credentials, so it works the same for robots, lessons and anyone's laptop:

repositories { maven { url = 'https://jitpack.io' } }
dependencies { implementation 'com.github.FRC-Team-4143.MW-Lib:mw-lib-java:27.0.0' }

One thing the published package does not carry is its own dependency list, so a robot project that starts the behavior-tree live server adds implementation 'org.java-websocket:Java-WebSocket:1.6.0' itself.

---

Building Against a Local Checkout

When you are changing MWLib and the robot code together, you do not want to publish a release for every try. mainbot's settings.gradle has an opt-in composite build that swaps the published jar for a live compile of your local checkout:

• Persistent (per developer, never committed): create local.properties in the mainbot project root:

  mwlibLocal=true
  # mwlibPath=/absolute/path/to/MW-Lib   # optional; defaults to ../MW-Lib

• One-off: ./gradlew build -PmwlibLocal (a -P flag overrides the file).
• Disable for one run: ./gradlew build -PmwlibLocal=false. This is what CI parity looks like, since CI always builds against the published version.

While local mode is on, a bold yellow banner prints at the start and end of every build, deploy and simulate so nobody mistakes a local build for the released library. Edit MWLib, then ./gradlew build or deploy in mainbot recompiles and bundles it; no publish and no version bump.

Finish with a release

A robot that works only with mwlibLocal=true is a robot nobody else can build. Before a change is "done", release MWLib, bump the version in build.gradle, and check ./gradlew test -PmwlibLocal=false passes.

---

Making a Change in MWLib

1. Branch from develop in MW-Lib (feat/<thing>). Build mainbot against it with mwlibLocal=true.
2. Keep the robot project honest: anything generic (a drive mode, a behavior-tree node any robot could use, a mechanism feature) belongs in MWLib; anything about one robot's hardware stays in the robot project.
3. Shared behavior-tree nodes are registered with registerLibraryNode in com.marswars.bt. MWLib keeps no node-list file: the palette section for its nodes is generated from the registrations (MwLibNodes.nodeSpecXml()), so there is nothing to regenerate in MWLib. Each robot's nodes.xml is where the list lives; regenerate it in the robot project after bumping MWLib or changing a node:

   ./gradlew test -PupdateNodeSpec     # in the robot project (mainbot)

   Without the flag, the robot's test fails if its nodes.xml is stale, so a forgotten regeneration cannot ship.
4. ./gradlew test javadoc locally; the simulation test suite runs in CI on Java 17 and 21.
5. Open a PR into develop. Put breaking changes (removed classes, renamed log keys) in the description, since it becomes the release notes.

---

Releasing

Releases are cut from develop by the Make Release GitHub Actions workflow; nothing is tagged by hand.

1. Merge the PR into develop with CI green.
2. Actions → Make Release → Run workflow; enter the version (27.0.0, no v).
3. The workflow runs the tests on develop, tags v27.0.0, asks JitPack to build the tag and waits until mw-lib-java:27.0.0 resolves (if JitPack's build fails, the run fails and prints JitPack's build log), then creates the GitHub Release and publishes the Javadoc.
4. Bump the version in mainbot's build.gradle (and the lessons' build.gradle), remove mwlibLocal=true, and build once against the published artifact.

---

Related Documentation

• Quick Reference: the robot project layout that uses all of this.
• Autonomous: adding nodes to the behavior-tree engine.
• Swerve: why drive behaviour changes go in MWLib.