Frostline Racing - Ice Boat Minigame

Why Frostline Racing?

Frostline is designed as a complete reusable minigame rather than a single race command.

• Full race lifecycle with waiting, countdown, racing, finishing, DNF handling, and automatic reset.
• In-game arena setup with validation, safety checks, and optional WorldEdit selection support.
• Persistent competition through SQLite statistics, race history, fastest laps, and leaderboards.
• Portable arena identity through per-arena leaderboard-key metadata, preserving configuration compatibility with Premium network installations.
• Production-minded behavior including reconnect grace, queued reloads, player-state restoration, and additive config updates that preserve customized values.
• Native race music using Note Block Studio files or custom resource-pack sound keys.
• Safe rebrand migration from the legacy plugins/Iceboat folder without overwriting existing Frostline Racing data.
• Backward compatibility for legacy commands, permissions, PlaceholderAPI identifiers, and plugin-created items.
• No external DRM or license server required for the plugin to keep working.

Race System

• Waiting, countdown, racing, finish, and reset states
• Ordered checkpoints and multiple laps
• Optional per-arena randomized starting-grid assignment for each countdown attempt
• Placement tracking and finish validation
• DNF handling and configurable race timeouts
• Configurable delay after the first racer finishes
• Configurable behavior for the final remaining racer
• Automatic boat assignment and cleanup
• Out-of-bounds recovery
• Race damage protection and racer dismount blocking
• Player inventory, location, gamemode, health, food, potion effects, flight, collision, and other state restored after the session
• Reconnect grace for racers, queued players, and spectators
• Independent sessions for different arenas

Arena Setup and Validation

• Multiple configurable arenas
• Arena lobby and spectator spawn
• Multiple starting positions with launch direction
• Join-order or randomized racer assignment across the administrator-defined starting-grid order
• Cuboid arena bounds, ordered checkpoints, and finish regions
• Configurable laps, minimum and maximum players, countdowns, and race timeout
• Optional player-facing display names
• In-game setup commands
• Read-only arena validation before enabling a track
• Optional WorldEdit selection support
• Enabled arenas can be edited safely
• Live reloads are queued while races or waiting players are active
• Confirmation required for destructive setup and statistics commands
• Missing default config options are added automatically without overwriting existing custom values
• Legacy arena settings receive targeted migrations when new required fields are introduced

Player Experience

• Arena browser GUI
• Smart quick join
• Per-arena queues
• Queue management GUI
• Configurable lobby hotbar items
• Waiting-lobby leave item
• Spectator mode with flight and arena boundary protection
• Spectator navigation between racers
• Automatic spectator mode after finishing
• Configurable MiniMessage text with legacy color-code fallback

Race Presentation

• Configurable bossbars
• Configurable actionbars
• Configurable scoreboards
• Hidden scoreboard numbers
• Scoreboard line wrapping and minimum width
• Configurable race sounds
• Race and lap times displayed with two decimal places
• Smooth per-tick live timer presentation without increasing checkpoint scan frequency
• Configured race titles are sent once at race start, while bossbars, actionbars, and scoreboards continue updating during the race
• Configurable arena display names
• MiniMessage support across messages, GUIs, items, bossbars, actionbars, and scoreboards
• Configured messages, UI text, GUI labels, and item names can consume placeholders from installed PlaceholderAPI expansions
• PlaceholderAPI consumption is available in Free and Premium; Frostline's own %frostline_*% expansion remains Premium-only

Race Music

Each arena can have one race soundtrack.

• Native .nbs playback for Note Block Studio songs
• Custom resource-pack sound-key support for streamed .ogg music
• Per-arena volume and pitch
• Music starts when the race begins and stops during normal race cleanup
• Independent playback for simultaneous races in different arenas
• Reconnect-grace support
• Per-player toggle with /frostline music on|off
• Admin preview with /frostline admin previewmusic <arena>
• Tab completion for NBS files inside plugins/FrostlineRacing/music

Basic setup:

Players using resource-pack music must have the relevant resource pack enabled. Music uses the Jukebox/Note Blocks client volume category.

Statistics, Records, and Rewards

• Persistent SQLite storage through the shared stats repository boundary
• Wins, races played, finishes, and DNFs
• Best race times per arena
• Best lap times per arena
• Per-race result history
• Global and per-arena leaderboards
• JSON statistics export and import for backups or migrations
• Tab completion for available JSON import files
• Configurable command rewards for participation, finishes, DNFs, and placements

Main Commands

/frostline is the primary command namespace. The legacy /iceboat alias remains supported for existing workflows.

Administrative tools are available under:

Useful setup and testing commands include:

Some commands are edition-specific. Premium-only commands return the normal unavailable response when used in Free.

Permissions use the frostline.* namespace. Existing iceboat.* permissions remain compatible.

Optional Dependency

WorldEdit can be used to save arena bounds, checkpoints, and finish regions from an existing cuboid selection.

WorldEdit is not required for normal gameplay.

PlaceholderAPI is optional. When installed, both Free and Premium can consume placeholders from other expansions inside configured messages, UI text, GUI labels, and item names. Premium additionally exposes Frostline Racing values through the %frostline_*% expansion.

Documentation

The public Frostline Racing wiki includes installation, setup, commands, permissions, configuration, music, PlaceholderAPI, edition differences, updating, and troubleshooting documentation.

• Frostline Racing Wiki

Installation

1. Download the build for your server operating system, or use the Universal build.
2. Place the jar in the server's plugins folder.
3. Restart the server.
4. Create and configure an arena using /frostline admin.
5. Run /frostline admin validate <arena>.
6. Enable the arena after validation succeeds.

Configuration and data are generated inside:

Main files include:

• config.yml for general settings and lobby items
• arenas.yml for arena definitions
• messages.yml for chat and interface text
• sounds.yml for race sound effects
• ui.yml for bossbars, actionbars, and scoreboards
• stats.db for persistent race statistics
• music/ for Note Block Studio files

Upgrading from Beta 0.4 or Earlier

Beta 0.5 completed the public rebrand from Iceboat to Frostline Racing. These compatibility paths remain supported in release 1.0.

• /frostline is now the primary command; /iceboat remains a legacy alias
• frostline.* is now the primary permission namespace; iceboat.* remains compatible
• Existing plugins/Iceboat data is migrated automatically to plugins/FrostlineRacing
• If the new folder already contains data, Frostline copies only missing recognized paths and never overwrites existing files
• The old folder is preserved when a safe merge is required
• Legacy item markers remain recognized so lobby, session, spectator, and setup items created before the rebrand continue to work
• Premium PlaceholderAPI uses %frostline_*% while keeping %iceboat_*% aliases registered

Compatibility

Current builds target Paper 1.21.6 and newer, including 26.x.

• Use Java 21 on supported builds before Minecraft 26.1.
• Use Java 25 on Minecraft 26.1 and newer.

Official artifacts now use the FrostlineRacing-* naming scheme. There are four distribution builds:

• Linux
• Windows
• macOS
• Universal

The OS-specific builds only bundle the SQLite native libraries required by that platform. The Universal build supports all three platforms but is larger.

Frostline Racing is developed and tested on Linux. Windows and macOS builds are produced from the same codebase, but direct testing on those operating systems is currently limited.

Download other official builds

Premium Edition

Frostline Racing Premium includes the complete Free race system plus advanced server-owner and competitive features.

Currently available Premium systems include:

• Countdown, trail, lap, finish, and victory cosmetics
• Cosmetic selection and preview GUI
• Permission-based cosmetic unlocks
• Configurable cosmetic categories, GUI layout, particles, and custom-head icons
• Visual arena setup dashboard
• Interactive setup wand
• Per-player region and position previews
• Casual-only, ranked-only, or mixed arena modes
• Elo-style ratings, ranked statistics, and ranked leaderboards
• Configurable rating-derived divisions with deterministic threshold resolution
• Ranked player race history with deterministic pagination
• Administrator ranked race inspection with finisher and DNF review
• Optional MySQL storage for shared player statistics, race history, best times, ratings, and ranked history across multiple servers
• Per-arena leaderboard-key identity for combining replicas of the same track into one network-wide leaderboard
• Cached MySQL reads, asynchronous writes, backend health diagnostics, and fail-closed ranked availability
• Premium PlaceholderAPI expansion through %frostline_*%, with legacy %iceboat_*% aliases
• Top-10 race-time and lap-time leaderboard placeholders for every configured arena, including formatted time, milliseconds, player name, and UUID
• Dynamic arena-id support through patterns such as %frostline_top_race_<rank>_<arena_id>_time% and %frostline_top_lap_<rank>_<arena_id>_time%
• Detailed in-game diagnostics report with copy-to-clipboard support
• Advanced Music playlists for lobby, countdown, race, final-lap, and results phases
• Ordered, shuffled, and weighted one-track selection strategies
• Per-player phase playback while preserving the existing simple one-track arena workflow
• Premium setup-dashboard visibility and race-phase preview controls for loaded Advanced Music configs
• Premium setup-dashboard toggle for randomized starting-grid assignment
• Ranked division placeholders through %frostline_rank_division% and %frostline_rank_division_name%

The Free edition remains a complete casual racing plugin rather than a limited demo.

Support and Feedback

Frostline Racing 1.0 is the first stable release. Development continues with compatibility fixes, maintenance, and future feature work, but the core racing workflow and existing configuration compatibility are now treated as stable release behavior.

Configuration defaults are updated additively, existing custom values are preserved, and targeted migrations are used for newly required arena settings. Avoiding unnecessary manual rebuilds remains a development priority.

When reporting an issue, please include:

• Server software and version
• Java version
• Plugin version and platform build
• Relevant console errors
• Steps needed to reproduce the problem
• Arena configuration when relevant

Third-Party Software

Frostline Racing includes the Xerial SQLite JDBC Driver 3.51.0.0.

Its license texts are available here:

• Apache License 2.0
• Zentus BSD-style license