❄️ IceBoatRacing

A professional-grade Minecraft Paper plugin for competitive ice boat racing — precision checkpoints, live scoreboards, automatic track generation, mandatory pit stops, and full race management.

---

🎯 What Is This?

IceBoatRacing turns your Minecraft server into a competitive ice boat racing platform. Create races, design tracks, register boats, enforce pit stops, and run events with live timing — all without leaving the game.

Built for servers running competitive racing events (like Grands Prix by Mini Jeux Entre Potes).

---

✨ Features

Category	Features
Race Management	Interactive creation wizard · Prepare/start/end races · Configurable lap counts · Auto-end when last player finishes
Checkpoints	BOX (simple cuboid) or PLANE (oriented rectangle for curved tracks) · Alternate bypass routes · Sector timing gates
AutoTrace	Drive one lap → plugin generates precise PLANE checkpoints automatically · Particle preview · Edit individual gates before saving
Pit Stops	Mandatory, configurable pit-stop count per race · Timed pit boxes with a live countdown · Team-livery color themes (11 real F1 team gradients) · Automatic disqualification for racers who skip them
Live Scoreboard	Real-time sidebar showing lap, checkpoint progress, and position for every racer
Race Lights	Optional 6-stage stained-glass starting lights (Brown → Red → Orange → Yellow → Lime → Green) synced with countdown
Car System	Register boats per player (all wood types, rafts, chest variants) · Custom names · Auto-spawn on prepare · Invulnerable
Multi-Language	English & French built-in · Extensible via YAML · MiniMessage formatting (gradients, hover/click events)
Persistence	One self-contained YAML file per race · Easy backup/migration

---

📦 Installation

1. Download the latest .jar
2. Place it in your server's plugins/ folder
3. Restart the server (or run /ibr reload)
4. First run generates:
   • plugins/IceBoatRacing/config.yml
   • plugins/IceBoatRacing/lang/en_US.yml & fr_FR.yml
   • plugins/IceBoatRacing/races/ (race data folder)

---

⚙️ Configuration Highlights

Edit plugins/IceBoatRacing/config.yml:

language: en_US              # en_US or fr_FR (add your own in lang/)

race:
  allowRejoin: true          # Let players rejoin mid-race after logout
  racingGameMode: ADVENTURE  # GameMode during race
  enforceRacingGameMode: true
  spectateOnFinish: true     # Put finishers in spectator mode
  removeCarWhenLoggingOut: false

  lights:
    enabled: false           # Set true + configure from/to coords to enable
    from: { x: 0, y: 0, z: 0 }
    to:   { x: 0, y: 0, z: 0 }

  startRotation: 0           # Boat yaw on start (degrees)

Tip: Race lights require a 3D region defined by from/to coordinates. The plugin fills it with stained glass during the 5-second countdown.

Tip: Pit stop count is set per-race, not globally — use /race setPitStops <race> <amount> (defaults to 1).

---

⌨️ Commands

Command	Description	Permission
/race create	Interactive race creation wizard	iceboatracing.race.create
/race start [name]	Start race with 5s countdown + lights	iceboatracing.command.race
/race prepare [name]	Spawn cars, teleport players, set Adventure mode	iceboatracing.command.race
/race end [name]	End race, broadcast final standings	iceboatracing.command.race
/race delete [name]	Delete race permanently	iceboatracing.race.create
/race setLapCount [name] <amount>	View/change lap count	iceboatracing.command.race
/race setPitStops [name] <amount>	View/change required pit-stop count	iceboatracing.command.race
/checkpoint create <race> [SECTOR]	Create BOX checkpoint from shovel selection	iceboatracing.command.checkpoint
/checkpoint setFinish <race>	Set separate finish line from shovel selection	iceboatracing.command.checkpoint
/checkpoint remove [race] [id]	Remove checkpoint by ID or nearest to player	iceboatracing.command.checkpoint
/checkpoint view <race>	Toggle particle preview of all checkpoints	iceboatracing.command.checkpoint
/checkpoint list [page]	List all checkpoints (paginated, clickable)	iceboatracing.command.checkpoint
/checkpoint autotrace start <race> [...]	Begin recording a lap for AutoTrace	iceboatracing.command.checkpoint
/checkpoint autotrace accept	Save generated checkpoints to race	iceboatracing.command.checkpoint
/checkpoint autotrace preview	Toggle particle preview of generated checkpoints	iceboatracing.command.checkpoint
/checkpoint autotrace sector	Add sector gate at nearest preview checkpoint	iceboatracing.command.checkpoint
/checkpoint autotrace resize	Resize nearest preview checkpoint	iceboatracing.command.checkpoint
/checkpoint autotrace delete	Delete nearest preview checkpoint	iceboatracing.command.checkpoint
/checkpoint autotrace cancel	Cancel AutoTrace session	iceboatracing.command.checkpoint
/checkpoint addAlternate <race> <id>	Add bypass gate to checkpoint (shovel selection)	iceboatracing.command.checkpoint
/checkpoint clearAll <race>	Delete all checkpoints (10s confirmation)	iceboatracing.command.checkpoint
/pitbox create <race>	Interactive pit box creation wizard	iceboatracing.command.pitbox
/pitbox list <race>	List all pit boxes (clickable edit/color/TP/remove)	iceboatracing.command.pitbox
/pitbox remove <race> <id>	Remove a pit box	iceboatracing.command.pitbox
/pitbox setAllowed <race> <id> <names|*>	Change which players may use a pit box	iceboatracing.command.pitbox
/pitbox setColor <race> <id> <color>	Change a pit box's color/team livery	iceboatracing.command.pitbox
/car create	Register a boat for a player (3-step wizard)	iceboatracing.command.car
/car list [page]	List all cars (clickable TP/remove/owner)	iceboatracing.command.car
/car remove <id> <race>	Remove a car from a race	iceboatracing.command.car
/car changeOwner <id> <race> <player>	Change car owner	iceboatracing.command.car
/ibr reload	Reload config, languages, races, scoreboard	iceboatracing.command.plugin
/ibr info	Show plugin info	iceboatracing.command.plugin

Aliases: /ibr = /iceboatracing · Tab completion works for all subcommands, race names, and player names.

---

🔑 Permissions

Permission	Description	Default
iceboatracing.*	All permissions	op
iceboatracing.command.*	All commands	op
iceboatracing.command.race	/race commands	false
iceboatracing.command.checkpoint	/checkpoint commands	false
iceboatracing.command.pitbox	/pitbox commands	false
iceboatracing.command.car	/car commands	false
iceboatracing.command.plugin	/ibr commands	false
iceboatracing.race.create	Create/delete races	false
iceboatracing.race.checkpoints	Manage checkpoints	false
iceboatracing.race.cars	Manage cars	false

Recommendation: Give staff iceboatracing.* or specific children like iceboatracing.race.*.

---

✅ Compatibility

Requirement	Version
Minecraft	1.21.4+
Paper	1.21.4+
Java	21

Notes:

• Paper is required — uses Paper-specific APIs (Brigadier commands, Adventure components). Spigot/Purpur/Folia are not supported.
• No external dependencies — only Paper API (compile-only).
• Published on Modrinth and CurseForge.

---

❓ FAQ

Why does it require Paper instead of Spigot?

It uses Paper's Brigadier command API, Adventure text/title/sound/particle APIs, and modern NMS mappings — none of which exist on Spigot forks.

My boats face the wrong direction on start.

Change `race.startRotation` in `config.yml` (degrees: 0=South, 90=West, 180=North, 270=East), then `/ibr reload`.

AutoTrace missed a turn / generated checkpoints in wrong order.

Drive a clean, continuous lap without backtracking. Adjust `spacing` (default 3 blocks) — higher for long straights, lower for tight corners. Use `/checkpoint autotrace resize`/`delete` to fix individual gates before `/accept`.

Players get "Illegal GameMode!" in action bar.

The plugin enforces `racingGameMode` (default ADVENTURE) during races. Either disable `enforceRacingGameMode` or ensure your server doesn't force a different gamemode.

What happens if a player skips a pit stop?

They're automatically disqualified when they cross the finish line without completing the race's required pit-stop count, and are listed separately at the bottom of the final standings marked DSQ.

Can I make a pit box available to only one team?

Yes — /pitbox setAllowed <race> <id> <names...> restricts a box to specific player names, or use * to allow anyone racing. Only one player can occupy a box at a time.

Can I run multiple races at once?

Yes — each race tracks independently. Use the race name argument to target a specific one.

How do I backup or move races to another server?

Copy the `plugins/IceBoatRacing/races/` folder (each `.yml` is a complete race, including its pit boxes). Copy `config.yml` and `lang/` for full setup.

Are chest boats and bamboo rafts supported?

Yes — all vanilla boat types including `*_CHEST_BOAT`, `BAMBOO_CHEST_RAFT`, and `PALE_OAK_BOAT` (1.21.5+). Just hold the item during `/car create`.

---

❤️ Support & Links

• Modrinth: modrinth.com/plugin/ibr
• CurseForge: curseforge.com/minecraft/bukkit-plugins/ice-boat-racing
• Source Code: github.com/mattmunichYT/IceBoatRacing
• Issues / Bug Reports: GitHub Issues

---

📄 License

MIT License — free for any use, including commercial servers. See LICENSE.

---