**Author:** RajaAditya **Website:** [rajaaditya.my.id](https://rajaaditya.my.id) **Version:** 1.0.0 **API:** Paper 1.21.x --- ## Features ### Multi-Arena Event System - Create unlimited independent racing arenas (`/race create `) - Each arena tracks its own lobby, boat spawns, checkpoints, and registration state - Multiple arenas can run **concurrent sessions** at the same time ### Gate-Based Lap Detection - Start/finish line and checkpoints are defined as **cuboid regions** (selected with a wand), not single points - Detection checks the boat's **full swept hull path** between ticks (not just its instantaneous position), so a fast boat can't skip a thin gate between two ticks - Configurable **padding tolerance** so a boat resting exactly on a gate's boundary still registers as a pass - Checkpoints must be hit **strictly in order** — an anti-shortcut measure before the lap counts at the finish line ### Full Race Lifecycle - Registration (`/race daftar`) → Join arena (`/race masuk`) → Countdown → Running → Finished - Players are **locked in place** (movement, inventory, block break/place, item drop/pickup, attacks) while waiting/counting down - Admins can pause, resume, force-stop, or disqualify (`dq`) a player mid-race ### Live HUD - **BossBar** showing arena, session name, current lap, and remaining time - **ActionBar** showing current lap / total, best lap, live position, and next checkpoint - Both are independently toggleable via config ### Cross-Session Player Stats - Total races, wins, total laps, and all-time best lap persisted per player, per arena - Backed by **YAML** (default, zero setup), **SQLite**, or **MySQL** (via HikariCP) - Viewable in-game with `/race stats` ### Discord Webhook Results - Posts the top-N leaderboard to a Discord webhook automatically when a round finishes - Fully customizable: bot username/avatar, embed color, title/footer text (with placeholders), leaderboard size, and an optional mention/content line ### PlaceholderAPI Support - Exposes live race data as placeholders for use in scoreboard/tab plugins (e.g. TAB) — this plugin does not render its own scoreboard - Supports both explicit-arena and player-context shorthand syntax ### Fully Configurable - All arena setup, timers, HUD, checkpoint tolerance, storage backend, and Discord options configurable via YAML - `/race reload` reloads config and messages without restarting the server --- ## Dependencies | Plugin | Required | Purpose | |--------|----------|---------| | [PlaceholderAPI](https://github.com/PlaceholderAPI/PlaceholderAPI) | No (softdepend) | Enables `%raceevent_*%` placeholders | No hard dependencies — the plugin runs standalone with YAML storage and Discord/PAPI disabled by default. --- ## Installation 1. Place `RA-RaceBoatEvent.jar` into your `plugins/` folder 2. Restart the server 3. Edit `config.yml` / `messages.yml` in `plugins/RA-RaceBoatEvent/` to your liking 4. Use `/race reload` to apply config changes without restarting 5. Set up your first arena — see [Arena Setup Walkthrough](#arena-setup-walkthrough) below --- ## File Structure ``` plugins/RA-RaceBoatEvent/ ├── config.yml # Storage backend, race timers, HUD, checkpoint tolerance, Discord webhook ├── messages.yml # All plugin messages, prefix, bossbar/actionbar formats ├── arenas/ # One YAML file per arena (lobby, spawns, checkpoints, boat slots) ├── stats.yml # Player stats, only used when storage.type = YAML ├── stats.db # SQLite database, only used when storage.type = SQLITE └── plugin.yml # Plugin metadata ``` --- ## Configuration ### config.yml ```yaml storage: # type: YAML | SQLITE | MYSQL type: YAML mysql: host: localhost port: 3306 database: raceboatevent username: root password: "" useSSL: false race: # Countdown before GO! (seconds) countdown-seconds: 5 # How many checkpoints must be passed in-order before a lap counts require-checkpoints-in-order: true # Ticks between anti-cheat re-lock enforcement while waiting lock-check-interval-ticks: 5 # Auto despawn boats this many ticks after a player leaves/finishes boat-despawn-delay-ticks: 20 # Extra tolerance (in blocks) added around checkpoint/start-finish gate # boxes when checking if a boat passed through. Boats commonly float with # their hull resting exactly on the gate's boundary, which an exact # (un-padded) box check can miss - raise these if checkpoints still feel # unreliable, lower them if gates are triggering too early/far away. checkpoint-vertical-padding: 0.6 checkpoint-horizontal-padding: 0.1 bossbar: enabled: true actionbar: enabled: true update-interval-ticks: 10 whitelisted-commands: - "/race info" - "/race stats" - "/race keluar" discord: # Kirim leaderboard top 1-10 tiap ronde selesai ke Discord via webhook. enabled: false webhook-url: "" # Nama & avatar bot yang tampil di Discord (kosongkan untuk pakai default webhook). username: "Boat Race" avatar-url: "" # Warna garis samping embed, format hex "#RRGGBB". embed-color: "#FFC800" # Judul & footer embed. Placeholder: %arena% %round% %laps% title: "🏁 Hasil Ronde: %round% (%arena%)" footer: "Boat Race Event" footer-icon-url: "" # Jumlah baris leaderboard yang dikirim (maks 25, batas embed Discord). top-limit: 10 # Isi pesan di luar embed, misal mention role. Kosongkan untuk tidak ada mention. # Contoh mention role: "<@&123456789012345678>" content: "" ``` **Config fields:** | Field | Description | |-------|-------------| | `storage.type` | `YAML` (flat-file, default), `SQLITE`, or `MYSQL` — see [Stats Storage](#stats-storage) | | `race.countdown-seconds` | Seconds counted down before a session begins | | `race.require-checkpoints-in-order` | Enforces strict checkpoint order before a lap counts | | `race.lock-check-interval-ticks` | How often the anti-cheat re-locks players stuck in WAITING/COUNTDOWN | | `race.boat-despawn-delay-ticks` | Delay before a vacated/finished boat entity is removed | | `race.checkpoint-vertical-padding` / `checkpoint-horizontal-padding` | Tolerance (in blocks) added to gate hitboxes — see [Checkpoint Detection](#checkpoint-detection) | | `bossbar.enabled` / `actionbar.enabled` | Toggle the live HUD elements independently | | `whitelisted-commands` | Commands players may still run while locked during a race | | `discord.*` | See [Discord Webhook](#discord-webhook) | --- ### messages.yml All player-facing text, fully translatable. Supports `&` color codes. ```yaml prefix: "&8[&cRaceEvent&8] &r" general: no-permission: "&cKamu tidak memiliki izin untuk melakukan ini." player-only: "&cCommand ini hanya bisa digunakan oleh player." unknown-command: "&cCommand tidak dikenali. Gunakan /race untuk melihat bantuan." arena-not-found: "&cEvent '%arena%' tidak ditemukan." arena-already-exists: "&cEvent '%arena%' sudah ada." admin: race-started: "&aRace '%arena%' ronde &f%round% &adimulai selama %duration%." # ...full admin.* feedback messages for every /race admin subcommand player: lap-completed: "&aLap %lap% selesai! &7(%time%)" new-best-lap: "&6&lBEST LAP BARU! &e%time%" # ...full player.* messages: registration, join/leave, lock feedback, DQ, spectator countdown: go: "&a&lGO!!" bossbar: format: "&e%arena% &7| Session: &f%session% &7| Lap: &f%lap% &7| Sisa Waktu: &f%time%" actionbar: format: "&7Lap &f%currentlap%/%totallap% &7| Best &f%bestlap% &7| Pos &f%position% &7| CP &f%checkpoint%" ``` **Available placeholders in messages:** | Placeholder | Available In | |-------------|-------------| | `%arena%` | most admin/player messages | | `%player%` | `dq-other` | | `%id%` | `checkpoint-added`, `checkpoint-removed`, `boat-set` | | `%amount%` | `maxplayer-set` | | `%status%` | `registration-toggled`, `allowjoin-toggled` | | `%current%` / `%max%` | `registered`, `event-full` | | `%old%` / `%new%` | `arena-renamed` | | `%round%` / `%duration%` | `race-started` | | `%lap%` / `%time%` | `lap-completed`, `new-best-lap` | | `%session%`, `%lap%`, `%time%` | `bossbar.format` | | `%currentlap%`, `%totallap%`, `%bestlap%`, `%position%`, `%checkpoint%` | `actionbar.format` | --- ### Arena Data Files Each arena created with `/race create` is saved as its own YAML file under `plugins/RA-RaceBoatEvent/arenas/`, containing: | Field | Description | |-------|-------------| | lobby / spawn | Return locations set via `/race setlobby` and `/race setspawn` | | start line | Cuboid region (pos1/pos2) set via `/race setstartline` | | checkpoints | Map of `id → cuboid region`, added via `/race checkpoint add` | | boat spawns | Per-slot spawn locations set via `/race setboat ` | | max players / registration-open / allow-join | Arena settings toggled via commands | You normally never need to hand-edit these — all fields are written by the in-game setup commands. --- ## Arena Setup Walkthrough 1. `/race create nurburgring` — create the arena 2. Stand at the lobby spot → `/race setlobby nurburgring` 3. Stand at the return/spawn spot → `/race setspawn nurburgring` 4. `/race givewand` — get the selection wand (left-click = pos1, right-click = pos2) 5. Select a cuboid across the start/finish line → `/race setstartline nurburgring` 6. Select a cuboid across each gate along the track, in the order boats should pass them → `/race checkpoint add nurburgring` (repeat per checkpoint) 7. Stand at each boat's starting position → `/race setboat nurburgring ` (repeat per boat slot) 8. `/race maxplayer nurburgring ` 9. `/race pendaftaran nurburgring true` — open registration 10. `/race allowjoin nurburgring true` — allow joining the arena once registered 11. When ready: `/race start nurburgring ` (e.g. `/race start nurburgring 5m Semifinal`) --- ## Checkpoint Detection Start line and checkpoints are **cuboid regions**, not single points — admins select an area with the wand instead of pinpointing an exact block. - Detection checks the boat's **full hull bounding box**, swept across its movement since the last tick, against the target gate's box. This prevents a fast boat from skipping a thin gate entirely between two ticks. - Checkpoints must be passed in **strict order** (`race.require-checkpoints-in-order`) — jumping ahead to a later gate does not advance progress, and the finish line only counts once every checkpoint has registered. - `race.checkpoint-vertical-padding` / `checkpoint-horizontal-padding` expand the gate's hitbox by that many blocks in each direction. This matters because a boat's hull commonly rests with its bottom face exactly on a gate's boundary (e.g. a gate built at water-surface level) — an exact, un-padded box check can miss that as "touching but not overlapping." Raise these values if checkpoints still feel unreliable on your track; lower them if gates trigger too early or from too far away. ### Debugging a checkpoint that won't trigger `/race checkdebug ` toggles a live diagnostic log for that arena. While enabled, every tick prints each racer's swept hull box next to the target gate's box (world, X/Y/Z ranges, and whether it counted as a hit) to console — useful for spotting a gate built at the wrong height or in the wrong world without guessing. ``` [CPDEBUG][nurburgring] CP#1 player=RajaAditya hit=false worldMatch=OK | boatBox world=world x[10.2,11.6] y[63.1,63.7] z[5.0,6.4] | regionBox world=world x[10.0,14.0] y[65.0,68.0] z[5.0,6.0] ``` --- ## Commands | Command | Description | Access | |---------|-------------|--------| | `/race create ` | Create a new arena | Admin | | `/race delete ` | Delete an arena | Admin | | `/race rename ` | Rename an arena | Admin | | `/race setlobby ` | Set the arena's lobby location to your position | Admin | | `/race setspawn ` | Set the arena's return location to your position | Admin | | `/race givewand` | Get the pos1/pos2 selection wand | Admin | | `/race setstartline ` | Set the start/finish line from your current wand selection | Admin | | `/race checkpoint add ` | Add a checkpoint gate from your current wand selection | Admin | | `/race checkpoint remove ` | Remove a checkpoint by ID | Admin | | `/race setboat ` | Set boat slot ``'s spawn to your position | Admin | | `/race maxplayer ` | Set the max number of participants | Admin | | `/race pendaftaran true\|false` | Open/close registration | Admin | | `/race allowjoin true\|false` | Allow/disallow joining the arena | Admin | | `/race start ` | Start a session (e.g. `5m`, `1h30m`) | Admin | | `/race pause ` | Pause a running session | Admin | | `/race resume ` | Resume a paused session | Admin | | `/race stop ` | Force-stop a session | Admin | | `/race dq ` | Disqualify a player from the running session | Admin | | `/race checkdebug ` | Toggle checkpoint/start-line diagnostic logging | Admin | | `/race reload` | Reload config and messages | Admin | | `/race daftar ` | Register for an event | Player | | `/race batal ` | Cancel your registration | Player | | `/race masuk ` | Join the arena (must be registered) | Player | | `/race keluar` | Leave the arena (only before the race starts) | Player | | `/race info [event]` | Show arena status, participant count, and current leader | Everyone | | `/race stats` | Show your personal stats for your current/first arena | Player | | `/race spectator` | Toggle spectator mode while inside an arena | Player | > Sub-commands are hidden from tab suggestions if the sender does not have `raceevent.admin`. --- ## Permissions | Permission | Default | Description | |------------|---------|-------------| | `raceevent.admin` | `op` | Access to all `/race` admin sub-commands (arena setup, race control, reload) | | `raceevent.use` | `true` | Access to player `/race` sub-commands (daftar, masuk, info, stats, etc.) | --- ## Player Lifecycle & Locking While a player is inside an arena and the session is `WAITING` or `COUNTDOWN`, they are locked in place: | Locked Action | Behavior | |----------------|----------| | Movement | Cancelled — player stays at their boat spawn until `GO!` | | Exiting the boat | Blocked while the race is `RUNNING` — use `/race keluar` (before start) or `/race dq` (mid-race) instead | | Inventory / item drop / item pickup | Blocked entirely | | Attacking | Blocked | | Block break / place | Blocked | | Commands | Blocked, except entries in `whitelisted-commands` | Once `RUNNING`, movement and boat control unlock and checkpoint/lap detection begins. A periodic re-lock check (`race.lock-check-interval-ticks`) guards against players who manage to slip loose during `WAITING`/`COUNTDOWN`. --- ## Stats Storage Cross-session player stats (total races, wins, total laps, all-time best lap) are tracked **per player, per arena**, independently of the live in-progress race state. | Backend | Setup | Notes | |---------|-------|-------| | `YAML` (default) | None | Flat file at `stats.yml`, read/written on demand | | `SQLITE` | None | Local file `stats.db`, single-writer connection pool | | `MYSQL` | Fill in `storage.mysql.*` in config.yml | Pooled via HikariCP, auto-creates the `race_stats` table on first run | Stats are recorded automatically at the end of every session for each finisher, and viewable in-game with `/race stats`. --- ## Discord Webhook When `discord.enabled: true` and a valid `discord.webhook-url` is set, the top-N leaderboard (medal emoji for 1st–3rd, `#N` after) is posted to Discord automatically every time a round finishes. **Customizable via `config.yml`:** | Field | Description | |-------|-------------| | `username` / `avatar-url` | Override the webhook's bot name/avatar (blank = use the webhook's own default) | | `embed-color` | Embed sidebar color, hex `"#RRGGBB"` | | `title` / `footer` (+`footer-icon-url`) | Embed title/footer text — supports `%arena%`, `%round%`, `%laps%` placeholders | | `top-limit` | Number of leaderboard rows sent (max 25, Discord's embed limit) | | `content` | Plain text sent outside the embed, e.g. a role mention like `<@&123456789012345678>` | The HTTP request runs off the main thread and fails silently into the console log (no in-game message) if the webhook URL is unreachable or Discord returns an error status. --- ## PlaceholderAPI Requires PlaceholderAPI to be installed. Identifier: `raceevent`. **Format:** `%raceevent__%` — e.g. `%raceevent_nurburgring_currentlap%` **Shorthand:** `%raceevent_%` resolves using whichever arena the requesting player is currently inside. | Stat | Description | |------|-------------| | `state` | Arena's current `RaceState` (`IDLE`, `WAITING`, `COUNTDOWN`, `RUNNING`, `PAUSED`, `FINISHED`) | | `session` | Current round name | | `sessionnumber` | Session counter for the arena | | `registered` | Number of registered players | | `maxplayers` | Max participant slots | | `remainingtime` | Time left in the session, `HH:MM:SS` | | `leader` | Name of the player currently in the lead | | `currentlap` | Requesting player's current lap | | `bestlap` / `lastlap` / `averagelap` | Requesting player's lap times | | `checkpoint` | Requesting player's next checkpoint index | | `totalcheckpoint` | Total checkpoints configured for the arena | | `boatnumber` | Requesting player's assigned boat slot | | `position` | Requesting player's live race position | --- ## Race Lifecycle States | State | Meaning | |-------|---------| | `IDLE` | No session active (registration may still be open) | | `WAITING` | Players may `/race masuk`, but boats are locked pending admin `/race start` | | `COUNTDOWN` | `5..4..3..2..1..GO!` in progress | | `RUNNING` | Race is live — boats unlocked, lap/checkpoint detection active | | `PAUSED` | Temporarily paused by an admin | | `FINISHED` | Session ended (time up or force-stopped); results/cleanup in progress | --- ## License Developed by **RajaAditya** — [rajaaditya.my.id](https://rajaaditya.my.id)