Frostline Racing

Frostline Racing is a Paper server plugin for ice boat racing. Servers can create arena tracks, let players join races, queue for active arenas, spectate races, track stats and leaderboards, configure race presentation, and optionally use Premium features such as cosmetics, visual setup tools, ranked racing, and PlaceholderAPI expansion values.

Current public version: Beta 0.7

Current server target:

• Paper 1.21.6+, including newer 26.x builds.
• Java 21 on pre-26.1 builds.
• Java 25 on Paper 26.1+ if the server requires it.

Future roadmap includes investigating Paper 1.20+ support, but 1.20 support should not be advertised until the jars are audited and smoke-tested on 1.20.x, 1.21.x, and current 26.x servers.

Editions

Free

Free includes the complete core racing loop:

• Arena racing.
• Multiple arenas.
• Ordered checkpoints.
• Multiple laps.
• Race countdowns.
• Finish placement tracking.
• DNF handling.
• Race timeout.
• Queueing.
• Spectating.
• Arena browser GUI.
• Smart quick join.
• Persistent SQLite stats.
• Race and lap leaderboards.
• Configurable messages, UI, sounds, lobby items, and command rewards.
• Admin arena setup commands.
• Optional WorldEdit selection support for setup commands.
• Optional PlaceholderAPI consumption inside Frostline config strings.

Free is currently feature-frozen except for bug fixes, compatibility work, documentation, and fixes shared with Premium.

Premium

Premium includes Free plus:

• Cosmetics.
• Cosmetic selection GUI.
• Premium visual setup preview.
• Premium setup wand.
• Premium setup dashboard GUI.
• Ranked racing foundation.
• Premium PlaceholderAPI expansion values.
• Dynamic top 10 PlaceholderAPI leaderboard values.
• Premium setup GUI music preview.
• Customizable Premium GUI icons, including PLAYER_HEAD base64 textures and texture URLs.

Premium features remain gated to Premium builds or explicitly composed Partner builds.

Commands

Primary command:

/frostline

Legacy alias:

/iceboat

Player Commands

/frostline join <arena>
/frostline join random
/frostline quickjoin
/frostline arenas
/frostline browser
/frostline leave
/frostline spectate <arena>
/frostline status <arena>
/frostline stats [player]
/frostline top <arena>
/frostline toplap <arena>
/frostline music <on|off>

Premium or ranked-gated player commands:

/frostline cosmetics
/frostline join <arena> ranked
/frostline join random ranked
/frostline quickjoin ranked
/frostline quickjoin <player> ranked
/frostline rank [player]
/frostline rankedtop [page]

/frostline quickjoin <player> is an admin queue action and requires frostline.admin.queue.

Admin Commands

/frostline admin about
/frostline admin reload
/frostline admin forcestart <arena>
/frostline admin debug <arena>
/frostline admin testsound [key]
/frostline admin queue [arena]
/frostline admin clearqueue <arena|all>
/frostline admin clearwaiting <arena>
/frostline admin reset <arena>
/frostline admin kick <arena> <player>
/frostline admin items
/frostline admin items all

Setup commands:

/frostline admin validate <arena>
/frostline admin create <arena>
/frostline admin delete <arena> --confirm
/frostline admin setlobby <arena>
/frostline admin setspectator <arena>
/frostline admin addstart <arena>
/frostline admin clearstarts <arena> --confirm
/frostline admin setbounds <arena>
/frostline admin addcheckpoint <arena>
/frostline admin clearcheckpoints <arena> --confirm
/frostline admin setfinish <arena>
/frostline admin setdisplayname <arena> <display name>
/frostline admin setplayers <arena> <min|max> <number>
/frostline admin setlaps <arena> <laps>
/frostline admin setwaitingcountdown <arena> <seconds>
/frostline admin setcountdown <arena> <seconds>
/frostline admin enable <arena>
/frostline admin disable <arena>

Music setup commands:

/frostline admin setmusic <arena> resource-pack <key> [volume] [pitch]
/frostline admin setmusic <arena> nbs <file.nbs> [volume] [pitch]
/frostline admin setmusic <arena> off
/frostline admin previewmusic <arena>

Stats maintenance commands:

/frostline admin stats resetplayer <player> --confirm
/frostline admin stats resetarena <arena> --confirm
/frostline admin stats resetall --confirm
/frostline admin stats pruneinvalid --confirm
/frostline admin stats export [file]
/frostline admin stats import <file> --confirm

Premium admin commands:

/frostline admin preview <arena|off>
/frostline admin wand <arena|off>
/frostline admin setup <arena>

Ranked admin commands:

/frostline admin setranked <arena> <enabled|disabled>
/frostline admin ranked setrating <player> <rating> --confirm

Permissions

Common player permissions:

Permission	Default	Purpose
frostline.join	true	Join arenas and quick join.
frostline.browse	true	Open the arena browser.
frostline.leave	true	Leave races, waiting lobbies, queues, or spectating.
frostline.spectate	true	Spectate active races.
frostline.status	true	View arena status.
frostline.stats	true	View player stats.
frostline.top	true	View best race times.
frostline.toplap	true	View best lap times.
frostline.music	true	Toggle personal music.
frostline.ranked.join	true	Join ranked races when ranked is available.
frostline.ranked.stats	true	View ranked stats.
frostline.ranked.top	true	View ranked leaderboard.
frostline.cosmetics	true	Open the Premium cosmetics menu.

Admin parent permission:

frostline.admin

Admin child permissions:

frostline.admin.about
frostline.admin.reload
frostline.admin.forcestart
frostline.admin.debug
frostline.admin.testsound
frostline.admin.music
frostline.admin.queue
frostline.admin.reset
frostline.admin.kick
frostline.admin.stats
frostline.admin.ranked
frostline.admin.items
frostline.admin.setup

Cosmetic unlock permissions are defined per cosmetic. Bundled examples use nodes such as:

frostline.cosmetics.trail.snow
frostline.cosmetics.finish.sparkle
frostline.cosmetics.win.fireworks

Legacy iceboat.* permission aliases remain available for compatibility.

Dependencies And Soft Hooks

Required:

• Paper server.

Optional:

• WorldEdit: used by arena setup commands that read a player's WorldEdit selection for bounds, checkpoints, and finish regions.
• PlaceholderAPI: lets Frostline config strings consume placeholders from other PlaceholderAPI expansions. Premium builds also register Frostline's own %frostline_*% expansion.

The plugin should still run without WorldEdit or PlaceholderAPI.

Files And Storage

Runtime data folder:

plugins/FrostlineRacing

Main config files:

File	Purpose
config.yml	Core settings, music settings, ranked settings, lobby items, command rewards.
arenas.yml	Arena definitions and setup data. Runtime arena edits update this file.
messages.yml	Chat messages, browser labels, item labels, and fallback legacy UI message keys.
ui.yml	Countdown/race/spectator titles, bossbars, actionbars, and scoreboards.
sounds.yml	Race sound effects.
cosmetics.yml	Premium cosmetics definitions and cosmetics GUI layout.
setup-gui.yml	Premium setup dashboard GUI layout.
cosmetic-selections.yml	Premium per-player cosmetic selections.
stats.db	SQLite stats, leaderboards, and ranked tables when ranked is available.

Config files are automatically updated with missing default keys while preserving existing custom values.

Current config version: 0.7.

Arena Model

An arena includes:

• enabled
• display-name
• world
• min-players
• max-players
• laps
• waiting-countdown-seconds
• countdown-seconds
• race-timeout-seconds
• allowed-modes
• ranked minimum player settings
• optional music
• lobby spawn
• spectator spawn
• bounds region
• start positions
• ordered checkpoint regions
• finish region

Arena ids come from arenas.yml. Display names may use MiniMessage formatting.

Arena Setup Workflow

Basic setup flow:

1. Create an arena with /frostline admin create <arena>.
2. Set lobby and spectator spawns.
3. Add enough start positions for the arena's max player count.
4. Set arena bounds.
5. Add checkpoint regions in order.
6. Set the finish region.
7. Set player counts, laps, and countdown values.
8. Run /frostline admin validate <arena>.
9. Enable the arena with /frostline admin enable <arena>.

WorldEdit can be used for region-based setup commands:

• /frostline admin setbounds <arena>
• /frostline admin addcheckpoint <arena>
• /frostline admin setfinish <arena>

Premium setup tools add:

• /frostline admin preview <arena|off> for visual particle previews.
• /frostline admin wand <arena|off> for in-world setup controls.
• /frostline admin setup <arena> for the setup dashboard GUI.

Race Flow

Common player flow:

1. Players join an arena directly, through the arena browser, or through quick join.
2. Waiting arenas start a waiting countdown when enough players are present.
3. The start countdown teleports racers to start positions and applies the configured movement restriction.
4. Racers drive through checkpoints in order for the configured lap count.
5. Racers finish, DNF, disconnect, or time out.
6. Results are displayed.
7. Stats and rewards are processed.
8. The arena resets after settings.post-game-seconds.

If a race is active and the arena is full, players can queue for the next race. Queued players are promoted after reset when space is available.

Spectators can join active races and use spectator items to navigate racers.

Race Rules And Settings

Important settings in config.yml:

Setting	Default	Purpose
settings.checkpoint-scan-period-ticks	2	How often checkpoints and finish regions are checked.
settings.post-game-seconds	8	Delay before reset after a race ends.
settings.reconnect-grace-seconds	15	Time disconnected racers/queued players/spectators can reconnect.
settings.scoreboards-enabled	true	Global scoreboard toggle.
settings.clear-inventory-during-race	true	Save and clear inventories during races.
settings.countdown-movement-mode	locked	Movement rule during countdown: locked, look, or move.
settings.bounds-teleport-cooldown-seconds	2	Cooldown for out-of-bounds return teleport.
settings.last-racer-behavior	declare_winner	Behavior when only one unfinished racer remains.
settings.finish-mode	wait_all	Race finish mode: wait_all or first_finish_delay.
settings.first-finish-delay-seconds	60	DNF timer after first finisher when using first_finish_delay.

Last-racer behavior:

• declare_winner: remaining racer wins immediately.
• cancel: race ends without auto-finishing the remaining racer.
• continue: remaining racer must finish or hit timeout.

Finish modes:

• wait_all: race ends after every non-DNF racer finishes or timeout hits.
• first_finish_delay: first finisher starts a timer; unfinished racers are DNF when it expires.

Stats And Leaderboards

Frostline records:

• races played
• finished races
• wins
• DNF count
• best race times
• best lap times

Commands:

/frostline stats [player]
/frostline top <arena>
/frostline toplap <arena>

Admin maintenance:

/frostline admin stats resetplayer <player> --confirm
/frostline admin stats resetarena <arena> --confirm
/frostline admin stats resetall --confirm
/frostline admin stats pruneinvalid --confirm
/frostline admin stats export [file]
/frostline admin stats import <file> --confirm

Declared winners receive placement and win credit but do not create artificial race-time or best-lap leaderboard entries.

Reconnect Grace

Disconnect behavior:

• Disconnecting during a race removes the player's boat but keeps progress for the grace window.
• Reconnecting in time returns the racer at their last valid checkpoint or start location.
• Expiring the grace window marks the racer DNF.
• Disconnecting while queued keeps the queue slot for the grace window.
• Disconnecting while waiting removes the player from the waiting lobby immediately.
• Disconnecting while spectating can restore spectator state if the race is still active.

Queued Reload

/frostline admin reload is safe during active sessions:

• If arenas are idle, reload runs immediately.
• If sessions are busy, reload is queued.
• New joins are blocked while reload is pending.
• Active races finish normally.
• Reload runs after all sessions become idle.

Lobby Items

Configurable lobby hotbar items live in config.yml:

• arena selector
• quick join
• Premium cosmetics item
• return-to-lobby item

Admins can toggle lobby items:

/frostline admin items
/frostline admin items all

If lobby-items.clear-inventory-on-join is false, Frostline tries to place items in configured slots and moves or drops occupied items safely.

The return-to-lobby item can run a player or console command.

Race UI And Sounds

Race presentation is configurable through ui.yml:

• countdown title/subtitle
• countdown bossbar
• countdown actionbar
• countdown scoreboard
• race title/subtitle
• race bossbar
• race actionbar
• race scoreboard
• spectator scoreboard

Sound effects are configurable through sounds.yml:

• countdown tick
• final countdown
• race start
• checkpoint
• lap
• finish
• DNF
• personal best

Admins can test sounds:

/frostline admin testsound [key]

Messages And Placeholders

messages.yml controls chat text and many labels. Text supports:

• MiniMessage formatting.
• Legacy & color codes.
• Hex colors.
• Frostline placeholders in both {name} and %name% styles.
• {prefix} and %prefix%.
• PlaceholderAPI placeholders from other plugins when PlaceholderAPI is installed and a player context is available.

Default chat messages use {prefix}.

The configured prefix lives at:

messages:
  prefix:
    text: "<gray>[<aqua>Frostline Racing<gray>] "

PlaceholderAPI

Free and Premium can consume external PlaceholderAPI placeholders inside Frostline config strings when PlaceholderAPI is installed.

Premium also registers Frostline's own expansion:

%frostline_*%

Legacy aliases remain available:

%iceboat_*%

Available placeholder groups:

• session state
• arena identity
• race progress
• session counts
• persistent stats
• ranked stats
• dynamic top 10 race-time leaderboards
• dynamic top 10 lap-time leaderboards

Session State

Placeholder	Return value
%frostline_in_race%	true when the player is a racer in a current race session; otherwise false.
%frostline_is_spectating%	true when the player is spectating a current race session; otherwise false.
%frostline_is_queued%	true when the player is queued in a current race session; otherwise false.
%frostline_arena%	Current arena display name as plain text, with formatting removed. Returns empty when the player is not in a session.
%frostline_arena_raw%	Current arena display name exactly as configured. Returns empty when the player is not in a session.
%frostline_arena_legacy%	Current arena display name converted to legacy section-code formatting. Returns empty when the player is not in a session.
%frostline_arena_id%	Current arena id. Returns empty when the player is not in a session.
%frostline_state%	Current session state name in lowercase. Returns empty when the player is not in a session.

Race Progress

Placeholder	Return value
%frostline_lap%	Player's current lap number. Returns 0 when the player has no race progress or is not in a session.
%frostline_laps%	Configured lap count for the current arena. Returns empty when the player is not in a session.
%frostline_checkpoint%	Player's next checkpoint number, capped at the arena checkpoint count. Returns 0 when the player has no race progress or is not in a session.
%frostline_checkpoints%	Configured checkpoint count for the current arena. Returns empty when the player is not in a session.
%frostline_placement%	Player's finishing placement. Returns empty when the player has not placed or is not in a session.
%frostline_time%	Current elapsed race/player time formatted as m:ss.cc. Before the race starts, returns 0:00.00. Returns empty when the player is not in a session.
%frostline_time_millis%	Current elapsed race/player time in milliseconds. Before the race starts, returns 0. Returns empty when the player is not in a session.
%frostline_best_lap%	Player's best lap formatted as m:ss.cc. Returns empty when no best lap is available or the player is not in a session.
%frostline_best_lap_millis%	Player's best lap in milliseconds. Returns empty when no best lap is available or the player is not in a session.

Session Counts

Placeholder	Return value
%frostline_racers%	Racer count in the current session. Returns 0 when the player is not in a session.
%frostline_max_players%	Maximum player count for the current arena. Returns empty when the player is not in a session.
%frostline_queue%	Queued player count in the current session. Returns 0 when the player is not in a session.
%frostline_spectators%	Spectator count in the current session. Returns 0 when the player is not in a session.
%frostline_active%	Active racer count in the current session. Returns 0 when the player is not in a session.
%frostline_finished%	Finished racer count in the current session. Returns 0 when the player is not in a session.
%frostline_dnf%	DNF racer count in the current session. Returns 0 when the player is not in a session.

Persistent Stats

Placeholder	Return value
%frostline_wins%	Stored player win count. Returns 0 when the player has no stored stats.
%frostline_races_played%	Stored player races played count. Returns 0 when the player has no stored stats.
%frostline_finished_races%	Stored player finished races count. Returns 0 when the player has no stored stats.
%frostline_dnf_count%	Stored player DNF count. Returns 0 when the player has no stored stats.

Ranked Stats

Ranked placeholders return empty when Ranked is unavailable, when the ranked service is disabled, or when the player has no ranked stats.

Placeholder	Return value
%frostline_rank_rating%	Player's ranked rating.
%frostline_ranked_races%	Player's ranked races played count.
%frostline_ranked_wins%	Player's ranked win count.
%frostline_ranked_finishes%	Player's ranked finish count.
%frostline_ranked_dnf%	Player's ranked DNF count.

Arena Leaderboards

Beta 0.6 adds Premium leaderboard placeholders for top race times and top lap times.

Leaderboard placeholders return empty when the arena is unknown, the rank is outside 1 through 10, or the requested position has no stored entry yet.

Arena ids are parsed dynamically, so bundled arenas such as frozen_cove and user-created arena ids are supported. Use the arena id from arenas.yml, not the display name. Arena ids may contain underscores; the final segment after the last underscore is treated as the requested field.

These placeholders are available when PlaceholderAPI is installed and the packaged build includes the Premium PlaceholderAPI feature.

Placeholder pattern	Return value
%frostline_top_race_<rank>_<arena_id>_name%	Player name for the arena's top race-time position.
%frostline_top_race_<rank>_<arena_id>_time%	Race time for the arena's top race-time position, formatted as m:ss.cc.
%frostline_top_race_<rank>_<arena_id>_millis%	Race time for the arena's top race-time position in milliseconds.
%frostline_top_race_<rank>_<arena_id>_uuid%	Player UUID for the arena's top race-time position.
%frostline_top_lap_<rank>_<arena_id>_name%	Player name for the arena's top lap-time position.
%frostline_top_lap_<rank>_<arena_id>_time%	Lap time for the arena's top lap-time position, formatted as m:ss.cc.
%frostline_top_lap_<rank>_<arena_id>_millis%	Lap time for the arena's top lap-time position in milliseconds.
%frostline_top_lap_<rank>_<arena_id>_uuid%	Player UUID for the arena's top lap-time position.

Examples:

Placeholder	Return value
%frostline_top_race_1_frozen_cove_name%	Player name for first place on frozen_cove by best race time.
%frostline_top_race_1_frozen_cove_time%	First-place best race time on frozen_cove.
%frostline_top_race_5_frozen_cove_millis%	Fifth-place best race time on frozen_cove, in milliseconds.
%frostline_top_lap_10_frozen_cove_time%	Tenth-place best lap time on frozen_cove.
%frostline_top_lap_3_custom_ice_loop_uuid%	Player UUID for third place by best lap time on custom_ice_loop.

Music

Each arena can have one race song.

Supported music sources:

• .nbs files in plugins/FrostlineRacing/music.
• custom resource-pack sound keys.

Music starts when the race begins and stops when the race ends or a player leaves/DNFs/disconnects outside active grace.

Player toggle:

/frostline music on
/frostline music off

Admin setup:

/frostline admin setmusic <arena> resource-pack <key> [volume] [pitch]
/frostline admin setmusic <arena> nbs <file.nbs> [volume] [pitch]
/frostline admin setmusic <arena> off
/frostline admin previewmusic <arena>

music.preview-seconds controls preview duration.

Music uses SoundCategory.RECORDS, so the client Jukebox/Note Blocks volume slider applies.

Rewards

Command rewards are configured in config.yml and run as console.

Hooks:

• participation
• finish
• dnf
• first-place
• second-place
• third-place

Reward placeholders:

%player%
%uuid%
%arena%
%placement%
%status%
%time%
%best_lap%

Rewards are disabled by default.

Premium Cosmetics

Premium cosmetics include:

• countdown effects
• trails
• lap effects
• finish effects
• win effects

Players open the menu with:

/frostline cosmetics

Cosmetics are configured in cosmetics.yml.

Current behavior:

• Selections are stored in cosmetic-selections.yml.
• Cosmetics can be permission-gated.
• Locked cosmetics can be visible or hidden.
• Left-click selects a cosmetic.
• Right-click previews without saving.
• Selected items use enchanted glint.
• Cosmetic display items can use normal materials or PLAYER_HEAD icons with base64 textures or texture URLs.
• Invalid materials or particles warn once and skip that cosmetic.
• Particle counts are capped by config.

Premium Setup Tools

Premium setup tools include:

• visual preview
• setup wand
• setup dashboard GUI

Commands:

/frostline admin preview <arena|off>
/frostline admin wand <arena|off>
/frostline admin setup <arena>

Preview:

• Read-only.
• Sends particles only to the previewing player.
• Shows bounds, checkpoints, finish, start positions, lobby spawn, and spectator spawn.
• Can preview disabled or incomplete arenas from arenas.yml.

Wand:

• Replaces the admin's inventory while active.
• Restores inventory, armor, offhand item, and selected hotbar slot when exited.
• Sneak-right-click cycles modes.
• Location modes save the player's current location.
• Region modes use left-click and right-click corners.

Setup dashboard:

• Validates setup.
• Toggles preview.
• Equips wand.
• Edits display name.
• Sets lobby, spectator, start, bounds, checkpoints, and finish.
• Clears starts/checkpoints through confirmation screens.
• Adjusts min/max players, laps, waiting countdown, and start countdown.
• Toggles ranked mode when ranked is available.
• Previews arena music.
• Enables or disables the arena.
• Uses setup-gui.yml for GUI layout and item customization.

Ranked Racing

Ranked is Premium-only in the current public builds.

Current ranked scope:

• Casual and ranked race modes.
• Per-arena allowed-modes.
• Per-arena ranked minimum player count.
• Ranked browser mode toggle.
• Ranked join commands.
• SQLite ranked stats and race history in stats.db.
• Conservative pairwise Elo-style rating updates.
• Ranked leaderboards.
• Ranked PlaceholderAPI values.

Commands:

/frostline join <arena> ranked
/frostline join random ranked
/frostline quickjoin ranked
/frostline quickjoin <player> ranked
/frostline rank [player]
/frostline rankedtop [page]
/frostline admin setranked <arena> <enabled|disabled>
/frostline admin ranked setrating <player> <rating> --confirm

Current ranked limitations:

• No seasons yet.
• No divisions or tiers yet.
• No advanced matchmaking yet.
• No team ranked modes yet.
• No native ranked rewards yet.

Admin Diagnostics

Admins can run:

/frostline admin about

The report includes:

• plugin/version/edition
• build artifact and platform metadata
• generated timestamp
• server version
• Bukkit version
• Java version
• database file state
• enabled and reserved feature gates
• active hooks
• arena counts
• arena list
• session counts
• reload-pending state
• important config values

The chat report includes a clickable copy button.

Build And Artifacts

Final artifacts include:

• Free universal
• Premium universal
• Free Linux
• Premium Linux
• Free Mac
• Premium Mac
• Free Windows
• Premium Windows

OS-specific artifacts filter SQLite native libraries for their target platform.

The validation command used during development is:

./gradlew test premiumJar validateArtifactMatrix

Current State

Implemented:

• Free core racing.
• Persistent SQLite stats.
• Arena setup commands.
• WorldEdit setup support.
• Config updater for default keys.
• Race UI and sounds.
• Music.
• Reconnect grace.
• Queued reload.
• Command rewards.
• Lobby items.
• Rebrand to Frostline Racing with /iceboat compatibility.
• Free/Premium artifact validation.
• Premium cosmetics.
• Premium setup tools.
• Premium ranked foundation.
• Premium PlaceholderAPI expansion.
• Free and Premium PlaceholderAPI config consumption.
• Admin diagnostics.

Known current product direction:

• Free gameplay is frozen aside from bugs and compatibility work.
• Premium roadmap focuses on network storage, ranked polish, advanced music, cosmetics/setup polish, dynamic arenas, and only then native reward integrations.
• A future compatibility pass may investigate Paper 1.20+ support.

Recommended next Premium priority:

1. Optional MySQL support for network-wide stats/ranked data if a concrete server needs it.
2. Ranked polish after live testing.
3. Advanced Premium music.
4. Cosmetics/setup polish based on feedback.
5. Dynamic arena instances and full multi-arena matchmaking.
6. Native reward integrations only if command rewards are insufficient.

Current Limitations

• Multiplayer testing still depends on live server owners/admins/players reporting issues.
• Free has no planned gameplay additions.
• MySQL/network storage is not implemented yet.
• Dynamic arena instances are scaffolded for future composition but not implemented.
• Advanced music playlists and phase-specific tracks are not implemented yet.
• Ranked seasons, divisions, and advanced matchmaking are not implemented yet.
• Native economy/crate/permission reward integrations are not implemented yet.
• Paper 1.20+ support is a future investigation, not a current support promise.