VRX: simulating unmanned surface vessels in Gazebo for RobotX

A competition arena first, a general simulator second

Virtual RobotX is the home to the source code and documentation for the VRX simulation environment, which supports simulation of unmanned surface vessels in marine environments. That sentence is the whole scope, and it is worth taking at face value before looking further.

The environment was designed in coordination with the RobotX organizers, and it provides arenas and tasks similar to those featured in past and future RobotX competitions, along with a description of the WAM-V platform, which is the reference unmanned surface vehicle the tasks are built around. For competitors, the stated intention is that this simulation is a first step toward developing tools and prototyping solutions in advance of physical on-water testing, which is a good way to frame what a simulation environment in this domain is actually for. The obstacle is that you cannot iterate on a control policy on the water in the same way you can iterate on a policy in a simulator.

The project is open to use beyond RobotX, with the maintainers saying they hope to offer support to a wide range of potential applications as the environment improves. That hope is stated as a hope, not a plan, and the competition framing is what the repository is actually organised around.

The main branch moved to Gazebo Harmonic and ROS 2 Jazzy

The recent and most consequential change in this project is a platform port. The repository is now ported to use supported versions of Gazebo and ROS 2, with the code working against Gazebo Harmonic and ROS 2 Jazzy. The README states plainly that this is the recommended configuration for new users.

Users who want to stay on the previous stack are not left stranded. The older Gazebo Garden and ROS 2 Humble combination remains usable through the humble branch of the repository, and the default branch is now jazzy, which matches the ROS 2 distribution name. So the split is by branch rather than by version flag inside one tree, which is the cleaner approach for a project of this size, and it means a Garden and Humble user pins a branch and stays there.

The port was carried out by the Honu Robotics team, sponsored by RoboNation, and the README credits them for the effort. That kind of sponsorship detail matters for judging the pace of the project, because a modernisation of this size is not a weekend task and the funding behind it is the reason the supported stack got updated at all.

Three directories and a docker folder describe how the environment is put together

The repository layout is short and tells you how the pieces divide. There is vrx_gz/, which by naming convention is the Gazebo side of the work, vrx_ros/ for the ROS side, and vrx_urdf/ for the robot description, which is where the WAM-V model and its meshes live. The docker/ directory is for containerised use, and images/ holds the material used in the README.

The separation matters for anyone extending the environment. Simulation assets, robot description and ROS interfaces are the three things you might want to change, and keeping them in separate directories means a change to a world file does not drag in the ROS packages. It also means the dependencies differ: the Gazebo side needs the simulator and its plugins, the ROS side needs the ROS 2 distribution and its build tooling, and the URDF side needs a mesh and link convention. Nothing in the repository listing documents that in detail, which is why the wiki is the reference the README points to.

The build and continuous integration setup lives in the .github/ directory, and the README carries a ROS 2 CI badge, so changes are validated against a ROS 2 build on every push.

The virtual venue: the same environment the competition is run in

The VRX environment is also the virtual venue for the VRX Competition, and the README points at the competition wiki for tutorials and for the links to registration and documentation relevant to the virtual event. That is a design decision with consequences for anyone planning to use the environment for research.

If the competition runs in the same environment that researchers prototype in, then a result reported against a VRX task is directly comparable to a competition entry, which is exactly the property you want from a benchmark. It also means the environment is shaped by the needs of a competition: clear win conditions, clear scoring, a bounded set of tasks, and a fixed platform rather than a general purpose physics sandbox.

The competition framing also explains the artefacts. The README embeds a highlight video of the earlier release, and the Sydney regatta simulation screenshot is the visual argument for the environment, since a reader who has never seen a maritime simulation needs to see what the arena looks like before deciding whether the project is relevant to them.

The project asks you to cite its paper and to use the issue tracker

The contribution rules here are unusually specific, and they are the part of the README most likely to affect your workflow.

If you use the VRX simulation in your work, the README asks you to cite the summary publication, Toward Maritime Robotic Simulation in Gazebo, and the BibTeX entry is provided.

@InProceedings{bingham19toward,
  Title                    = {Toward Maritime Robotic Simulation in Gazebo},
  Author                   = {Brian Bingham and Carlos Aguero and Michael McCarrin and Joseph Klamo and Joshua Malia and Kevin Allen and Tyler Lum and Marshall Rawson and Rumman Waqar},
  Booktitle                = {Proceedings of MTS/IEEE OCEANS Conference},
  Year                     = {2019},
  Address                  = {Seattle, WA},
  Month                    = {October}
}

The support rules are just as direct. Technical questions go to the project issue tracker, with steps to reproduce, the system setup including operating system and ROS version, and the relevant error messages or logs. The README asks people not to email the maintainers with technical questions, on the grounds that the tracker keeps answers visible and searchable for the whole community, and fixes arrive as pull requests. The maintainers also state that VRX is an open source project supported by the community, and that the contributors are recorded on a wiki page.

Apache-2.0 is the licence, with the LICENSE file at the repository root, so use in research and in commercial work is fine provided the notice and the licence text travel with the code.

Where VRX is the wrong tool

The clearest case for not using it is that you are not already in the ROS world. The getting started section says the instructions assume a basic familiarity with the ROS environment and Gazebo, and it recommends the ROS tutorials first if those tools are new to you. That is a large amount of prerequisite work before you see a boat, and the simulation itself adds the cost of a working Gazebo installation on a specific distribution pairing.

The second case is a marine simulation need that is not a RobotX task. The project describes itself as supporting simulation of unmanned surface vehicles in marine environments, but the concrete assets are arenas and tasks similar to the RobotX competitions and a description of the WAM-V platform. If your interest is a different hull, a different sensor suite, a multi vehicle scenario or a physical fidelity study, the environment is a starting point with a particular set of assumptions baked in, and the wiki is where you would find out which of those assumptions you have to undo.

The third case is expecting a general physics sandbox. This is a task environment for a competition, with a reference platform, and its value is in being a fixed, comparable benchmark rather than a configurable simulator. A research group that wants to change the vehicle, the sensors and the world will spend time fighting the arena assumptions instead of using them.

Version 3.1.0 with a maintenance pattern of dated release notes

The release history is dated and named after the months they cover, which makes it easy to read at a glance. The listed versions are v3.1.0 for the November 2025 updates, published on 2025-11-26, v3.0.4 for the July 2025 updates from 2025-07-24, and v3.0.3 for the June 2025 updates from 2025-06-30. A Changelog.md sits at the repository root.

The repository is not archived and the last push was on 2026-08-02, so the branch is still receiving work, but the newest listed release is a v3 series tag rather than a 3.2, which suggests the numbered releases track the simulation environment while the jazzy port work continues separately on the branch. If you need a reproducible environment for a paper, a published v3 tag is the thing to pin rather than the tip of jazzy.

One point of care for new users. The stack is Gazebo plus ROS 2, and those two have their own release schedules, so the combination that VRX is tested against is Gazebo Harmonic with ROS 2 Jazzy on the main branch. Mismatching those is the most likely source of a broken environment, and the humble branch exists for the previous pairing so that an existing setup can keep running unchanged.

Editorial conclusion

Adopt VRX if your work involves maritime robotics and you want a competition shaped set of arenas, tasks and a WAM-V platform description to prototype against before hardware testing, since the environments are designed to mirror past RobotX events and the maintainers ask users to cite the project paper. Do not adopt it as a general marine simulation framework, because the scope is documented as the RobotX arena and task set, and the whole thing assumes you already work in ROS and Gazebo. Before you build on it, decide which branch you need, since jazzy carries Gazebo Harmonic and ROS 2 Jazzy while humble holds the previous Garden and Humble pairing, and expect the environment itself to be stable but the surrounding simulator stack to be the part that breaks.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. osrf/vrx on GitHub
4. README
5. Releases