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.

Requirements

• Jotunn 2.30.0 or later (installed automatically as a dependency)

This mod must be installed on the dedicated server AND on every connecting client. It enforces that itself: a client without it, or running a different major/minor version, is refused at connect with a mod-compatibility message rather than silently misbehaving.

Compatibility

• Valheim 1.0.7 (Deep North), network version 39
• Jotunn 2.30.0 or later — earlier Jotunn versions do not work on Valheim 1.0.7

Built against Valheim 1.0.7 and verified against the shipped game assemblies. Earlier releases of this mod targeted Valheim 0.221.12 and will not work on 1.0.7.

Not yet tested in live multiplayer. This build has been verified statically against Valheim 1.0.7 and Jotunn 2.30.0, but has not yet completed a live multiplayer test on a dedicated server. Please report anything you hit.