BoatRace

Gate-to-gate boat racing events for Valheim. An admin lays out a course as a list of gates in a JSON file, starts a race with everyone currently online, and racers follow lit buoy markers around the course while a live leaderboard tracks who is furthest along.

Required on the server and on every client. Race state is server-authoritative.

Setting up a course

Copy BoatRace_Gates.example.json into BepInEx/config/, rename it to BoatRace_Gates.json, and edit it. Each gate is a line between two buoy points that racers cross in order:

{
  "gates": [
    {
      "index": 1,
      "name": "Start Line",
      "pointA": { "x": 0.0, "y": 30.0, "z": 0.0 },
      "pointB": { "x": 30.0, "y": 30.0, "z": 0.0 }
    }
  ]
}

Gate 1 is the start line, the highest-numbered gate is the finish. Indices must run 1, 2, 3... with no gaps or duplicates. Stand where you want a buoy and read your coordinates off the F5 console to fill the file in.

Commands

• boatrace_start — (admin) start a race with everyone currently connected
• boatrace_end — (admin) end the race early; anyone still racing is marked DNF
• boatrace_reset — (admin) clear all race state and hide the HUD
• boatrace_reload — (admin) reload the gate file from disk and respawn markers
• boatrace_testui — preview the markers, leaderboard and arrow with dummy data
• boatrace_setpos <x> <y> — move your own leaderboard panel
• boatrace_debugstate — dump race state and gate-config fingerprints to the log

Everyone must be on the same course

The gate file is read from local disk on each machine and is not synced. If the server and a client disagree, the server scores against its own gates while that client's buoys, pins and arrows sit somewhere else — which looks exactly like broken gate detection.

BoatRace logs a gate-config fingerprint (e.g. 5g-8c44d6e8) on every machine when the gate file loads; the server and every client must show the same value. Clients report theirs on connect and after boatrace_reload, boatrace_start warns the admin by name about anyone on a different course (the race still starts), and boatrace_debugstate lists every peer's fingerprint flagged MATCH / MISMATCH / NEVER-REPORTED.

Racing rules

Crossing a gate out of sequence costs a flat time penalty (15s by default) but does not change which gate you need next. Crossing the final gate locks in your time; the race keeps running for everyone else. Disconnecting mid-race is a DNF — rejoining does not restore your run, but you keep a greyed-out place on the board and are told what happened.

Navigation aids

All three point at your own next gate, not the leader's: the next gate's buoys burn green while every other gate burns orange, a pulsing marker appears on both the minimap and the full map, and a screen-edge arrow rotates toward the gate with a distance readout.

Requires Jotunn.