PurpleProject
A VS Code extension for FRC teams: turns a fresh WPILib robot project into a
LibPurple project that builds out of the box — LibPurple submodule (pinned to
a tested version), vendordeps, folder structure, core robot files (FSM,
swerve, autos), cameras, and subsystems ("Systems") backed by motors and
lidars.
New project in 4 steps
- In VS Code: WPILib: Create a new project → Java → Command Robot or
Timed Robot template (either works), then open the new folder.
- Command Palette → PurpleProject: Full Project Setup. Answer
Initialize git and Overwrite existing files.
- Add your mechanisms with PurpleProject: Add System and cameras with
PurpleProject: Add Camera.
- Build (
./gradlew build, or WPILib: Build Robot Code).
Commands
Run these from the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) while your
WPILib project folder is open:
- PurpleProject: Full Project Setup — folders + vendordeps + LibPurple
- core files in one shot. Best for a brand-new WPILib project.
- PurpleProject: Scaffold Project Folders — creates the folder tree under
src/main/java/frc/robot (Constants, FSM/Actions, FSM/States/{Drive,Main,PIT},
Subsystems/{Camera,Systems}, Swerve, Utils/Auto) and
src/main/deploy/choreo. It also removes WPILib's example files
(Constants.java, commands/, subsystems/ExampleSubsystem.java), which
otherwise break the build: frc.robot.Constants can't be both a class and a
package, and subsystems vs Subsystems collide on Windows/macOS.
- PurpleProject: Add Vendor Dependencies — copies the vendordep JSONs
(AdvantageKit, Phoenix6, PathplannerLib, ChoreoLib, photonlib, Autopilot,
WPILibNewCommands) into
vendordeps/ and wires the AdvantageKit annotation
processor into build.gradle.
- PurpleProject: Add LibPurple to Project (git submodule) — adds
LibPurple as a git submodule under src/main/java/frc, on branch main
at the commit the templates were tested with (see Settings). Long-path
support is turned on for the repo so the deep LibPurple folders clone on
Windows. If the clone fails, the half-added submodule is cleaned up so you
can just run the command again.
- PurpleProject: Add Core Robot Files — copies
Robot, RobotContainer,
Main, RobotMap, RobotProperties, the FSM (StateBase2026, drive
states, Idle, auto StartAuto/Delay, PIT states), Swerve, Constants
and Utils (auto chooser, Elastic, ...).
- PurpleProject: Add Camera — generates a
Subsystems/Camera/*Camera.java
Limelight class from a template and registers it in RobotContainer.
- PurpleProject: Add System (motors + lidars) — generates a new
Subsystems/Systems/*.java subsystem. See below.
Writing a new System (e.g. a new Intake, Interpool, Climber, ...)
Systems are built on LibPurple's motor framework
(frc.LibPurple.systems.Motor.* and frc.LibPurple.systems.Lidar.Lidars):
- A private singleton with
getInstance() that picks TalonFXIO on REAL
and a no-op MotorIO on REPLAY/sim.
- A
makeConfig(canId, bus, name, inverted) helper building one
MotorSystemConfig per motor (systemName, name, ID, bus,
unitToRotorRatio, fxConfig). Motor 0 is the leader; every motor after it
follows the leader (inverted = true means opposed to the leader).
- A
configs array (leader + followers) passed to TalonFXIO, and the
leader's config passed to super(...).
- Optional
Lidars fields (new Lidars(dioPort, thresholdMm, systemName, logName)),
each polled from periodic().
- Thin public methods (
setVoltage, setVelocity, setPosition, ...) that
forward to the protected set*Impl methods on System<>.
PurpleProject: Add System writes all of that for you. It asks for the
system's name, how many motors and each motor's name, which CAN bus they're on
(rio or the CANivore), then how many lidars (0 is fine) and each one's name.
CAN IDs and DIO ports are pre-filled with the next free number found in the
robot code (RobotMap, TunerConstants, other systems) and can be changed in the
prompt. It then:
- adds the CAN IDs / DIO ports to
RobotMap (e.g. INTAKE_LEADER_ID),
- creates
FSM/Actions/<Name>/<Name>SetVoltage.java to use in states, and
- registers the system in
RobotContainer.registerSubsystems().
Afterwards, set the gear ratio (unitToRotorRatio) and PID gains, and add the
system's action to your states: StateBase2026 takes one action per subsystem,
e.g. super(new HolonomicStop(), new IntakeSetVoltage(0)).
Settings
| Setting |
Default |
Description |
libpurple.repoUrl |
https://gitlab.com/EranOvadia/LibPurple.git |
Git URL of the LibPurple submodule |
libpurple.branch |
main |
LibPurple branch to check out (recorded in .gitmodules) |
libpurple.commit |
5eb4e05… (main, tested) |
Commit checked out on that branch. Clear it to take the latest commit of the branch instead. |
libpurple.targetFolderName |
LibPurple |
Folder name created inside frc/ (must match the library's Java package name) |
libpurple.frcRelativePath |
src/main/java/frc |
Path to the frc Java package, relative to project root |
When LibPurple main moves on and the templates are updated to match, bump
DEFAULT_LIBPURPLE_COMMIT in src/extension.ts and the libpurple.commit
default in package.json together.
Running it locally (development)
- Open this folder in VS Code.
- Run
npm install
- Run
npm run compile
- Press
F5 to launch an Extension Development Host window.
- Open a WPILib FRC project in that new window and run a command.
Packaging into a .vsix
npm install
npm run compile
npx vsce package
Install the resulting .vsix via Command Palette → Extensions: Install
from VSIX..., or code --install-extension purple-project-<version>.vsix.
Requirements
git on your PATH (install from https://git-scm.com if the command says
it's missing).
- Network access to wherever
LibPurple is hosted, for the submodule clone.
- The WPILib 2026 installation (for building).
Notes
- In simulation the robot code runs in AdvantageKit replay mode, so it
asks for a log file on start. Point it at one with the
AKIT_LOG_PATH
environment variable, or open a log in AdvantageScope first.
- Teammates cloning the robot repo on Windows should run
git config --global core.longpaths true once, then
git submodule update --init.
| |