Heartbound

A Paper plugin for Minecraft 1.21.x that implements a shared health pool across all players with automatic world reset on death. Includes a full speedrun timer and scoreboard system.

Features

• Shared Health Pool: All players share a single health pool. When any player takes damage, it affects the global health.
• Shared Hunger & Saturation: Food and saturation are synced across all players. Hunger depletion and eating benefits apply to everyone equally.
• Shared Healing: Healing is applied to the shared pool and divided by player count to prevent multiplication exploits.
• Automatic World Reset: When the shared health reaches 0, the world automatically resets after a configurable delay.
• Speedrun Timer: Live timer tracks the duration of each attempt.
• Ender Dragon Goal: Main goal is defeating the Ender Dragon — timer stops when the dragon is killed.
• Best Time Tracking: Automatically saves your best dragon kill time.
• Attempt History: Keeps track of your last 3 attempts with times and outcomes.
• Sidebar Scoreboard: Always-visible sidebar showing:
  • Current timer (updates live every second)
  • Attempt number
  • Best time (if dragon was killed)
  • Last 3 attempt times with success/fail indicators
• Limbo World: Players are safely teleported to a void world during reset.
• Spawn Chunk Preloading: Configurable radius of chunks to preload around spawn for smoother starts.
• Configurable: All settings can be customized via config file.

Commands

All commands require OP. Use /heartbound or /hb:

Command	Description
/hb trigger	Manually trigger a world reset
/hb attempts	Show current attempt count
/hb reset-counter	Reset attempt counter to 0 (clears history and best time)
/hb set-counter <value>	Set counter to specific value
/hb health	Show current global health
/hb sethealth <amount>	Set global health
/hb status	Show full status (timer, health, attempts, best time, reset status)
/hb timer	Show current timer status
/hb timer-start	Manually start/restart the timer
/hb timer-stop	Manually stop the timer
/hb best	Show best dragon kill time
/hb history	Show last 3 attempt times
/hb reload	Reload configuration

Scoreboard Display

The sidebar scoreboard displays:

    Speedrun
⏱ 12:34          <- Current timer (updates live)

Attempt #5       <- Current attempt number
Best: 45:23.456  <- Best dragon kill time

Last Attempts:   <- History of last 3 attempts
✓ #4 45:23       <- Green checkmark = dragon killed
✗ #3 23:45       <- Red X = failed attempt
✗ #2 12:34

Configuration

Config file is located at plugins/Heartbound/config.yml:

# Reset delay in milliseconds after death
reset-delay-ms: 3000

# Seed mode: "random" or "fixed"
seed-mode: random

# Fixed seed to use when seed-mode is "fixed"
fixed-seed: 12345

# Enable limbo world during reset
limbo-enabled: true

# Maximum shared health
max-health: 20.0

# Which dimensions to reset
reset-overworld: true
reset-nether: true
reset-end: true

# Spawn chunk preloading (overworld only)
# Radius in chunks around spawn to preload and keep loaded
# A radius of 3 = 7x7 = 49 chunks, radius of 5 = 11x11 = 121 chunks
spawn-preload-radius: 3

# Messages (supports & color codes)
messages:
  prefix: "&c[Heartbound]&r "
  death: "&4All players have fallen! Resetting world in {delay} seconds..."
  reset-start: "&6World reset in progress... Please wait."
  reset-complete: "&aWorld reset complete! Attempt #{attempt} begins!"
  limbo: "&7You are in limbo while the world resets..."

# Silent mode - disable all messages
silent-mode: false

# Show speedrun scoreboard on sidebar
show-attempts-sidebar: true

Installation

1. Install Paper 1.21.x server
2. Place the plugin JAR in the server's plugins/ folder
3. Start the server
4. (Optional) Edit plugins/Heartbound/config.yml and restart

How It Works

1. Timer Start: Timer begins when the server starts or after each reset.
2. Separate Game Worlds: The plugin creates separate game_world, game_nether, and game_end worlds for gameplay.
3. Damage Sharing: All player damage is routed through a shared health pool.
4. Hunger Sharing: Food level, saturation, and exhaustion are synced across all players every tick.
5. Healing Normalization: Healing is divided by player count so multiple players regenerating health doesn't multiply the effect.
6. Death Prevention: Individual player deaths are prevented; only global death triggers reset.
7. Dragon Detection: When the Ender Dragon is killed in game_end, the timer stops with success.
8. Reset Sequence:
   • Timer is stopped and attempt is recorded
   • Players teleported to limbo world (set to spectator mode)
   • Game worlds are unloaded and deleted
   • New worlds are created with a new seed
   • Spawn chunks are preloaded
   • Players returned to new spawn (set to survival mode)
   • Health and hunger reset to full
   • Attempt counter incremented
   • Timer starts for new attempt

Data Storage

Attempt data is saved to plugins/Heartbound/attempts.yml and includes:

• Total attempt count
• Last 3 attempt records (time, success/fail, timestamp)
• Best dragon kill time