Nexal TNT Run

A classic TNT Run minigame: blocks disappear beneath players' feet, last player standing wins. Every game plays in a fresh copy of the arena, pasted from a schematic with WorldEdit, so the map is whole again for every match and a full or running game never stops others from playing the same arena.

Features

1. Classic TNT Run Mechanics - Blocks disappear after players step on them, with a configurable delay (default 8 ticks). The block below goes too when it is collapsible (sand on TNT).
2. Multi-Layer Arenas - Build as many layers as you like; falling through one lands you on the next. Players below the arena's death level are eliminated.
3. Double Jump - Per-arena toggle, cooldown and power, set from the admin menu.
4. Fresh Arena Copies - Each game pastes its own copy of the arena schematic into a void world and removes it afterwards. Up to game.max-concurrent-games-per-arena games of one arena run at once.
5. Spectator Mode - Eliminated players watch the rest of the game from the spectator spawn. Players in a lobby or a game, spectators included, cannot teleport or use commands other than /tntrun leave (see command-whitelist), and anyone who falls off the arena outside a game is put back.
6. Optional Time Limit - Off by default: a game runs until one player is left. With a limit set (per arena, or game-duration for new arenas), the players still standing when it runs out take the top places, ranked by blocks broken.
7. Position-Based Rewards - Console commands and Vault money for 1st, 2nd and 3rd place: defaults in config.yml, per-arena commands with /tntrun admin addcmd.
8. Scheduled Games - Give an arena a cron schedule and it opens a lobby at those times and announces it to the server.
9. Statistics - Wins, games played, podiums, blocks removed, survival time and best time.
10. Leaderboards - Top 10 in chat, a paginated leaderboard menu, and top-N PlaceholderAPI placeholders for holograms.
11. Arena Menu - /tntrun gui lists the arenas with their lobbies and running games; click to join.
12. Admin Menu - /tntrun admin manages arenas (enable, open a lobby, force start, stop, delete, settings) and the plugin-wide configuration.
13. Inventory Safety - Players get back exactly what they had when they leave, disconnect or the game ends; after a server crash it is restored when they next join.
14. Dual Storage - JSON or SQL (MariaDB/MySQL), with export and import to move between them.
15. Firework Celebrations - Configurable fireworks for the winner.
16. Game Records - Every game is stored with its placements (in data.json or the tntrun_game_records table).

Technologies

• Spigot/Paper API 1.20.1+ - Minecraft server API
• Utilizer - Configuration, messages, items, tasks, menus
• ACF - Command framework
• nexal-core - Arena cloning, JSON and SQL persistence (MariaDB/MySQL), help menus
• WorldEdit or FastAsyncWorldEdit (required) - Saves arena regions and pastes every game's copy
• cron4j - Scheduled games
• PlaceholderAPI - Placeholder integration (optional)
• Vault - Money rewards through an economy plugin (optional)

Commands

Player Commands

Command	Description	Permission
/tntrun or /tr	Show help	nexaltntrun.use
/tntrun join [arena]	Join an arena; without one, the fullest open lobby or the first ready arena	nexaltntrun.join
/tntrun leave	Leave the current game (alias quit)	nexaltntrun.join
/tntrun gui	Browse arenas in a menu and join (alias arenas)	nexaltntrun.join
/tntrun stats [player]	View statistics, also of offline players	nexaltntrun.stats
/tntrun leaderboard [wins|blocks|games|time]	Top 10 in chat (alias lb)	nexaltntrun.leaderboard
/tntrun top [wins|blocks|games|time]	Leaderboards in a paginated menu	nexaltntrun.leaderboard

Admin Commands

Admin commands are hidden from players without the nexaltntrun.admin permission.

Command	Description	Permission
/tntrun admin	Open the admin menu (admin help from the console)	nexaltntrun.admin
/tntrun admin help [page]	Show the admin commands	nexaltntrun.admin
/tntrun admin create \<name>	Create an arena with the defaults from config.yml	nexaltntrun.admin.create
/tntrun admin delete \<arena>	Delete an arena and its schematic	nexaltntrun.admin.delete
/tntrun admin list	List all arenas	nexaltntrun.admin
/tntrun admin info \<arena>	View an arena's configuration and what it is missing	nexaltntrun.admin
/tntrun admin setregion \<arena>	Select the arena (click two corners) and save it as a schematic	nexaltntrun.admin.setup
/tntrun admin cancel	Cancel region selection	nexaltntrun.admin.setup
/tntrun admin setlobby \<arena>	Set the lobby spawn at your position	nexaltntrun.admin.setup
/tntrun admin setspectator \<arena>	Set the spectator spawn at your position	nexaltntrun.admin.setup
/tntrun admin setspawn \<arena> [index]	Set a game spawn at your position (the next free one without an index)	nexaltntrun.admin.setup
/tntrun admin setdeath \<arena>	Set the death level at your feet	nexaltntrun.admin.setup
/tntrun admin setdelay \<arena> \<ticks>	Block disappear delay (1-200)	nexaltntrun.admin.setup
/tntrun admin setmin \<arena> \<players>	Minimum players (2 to the maximum)	nexaltntrun.admin.setup
/tntrun admin setmax \<arena> \<players>	Maximum players (the minimum to 200)	nexaltntrun.admin.setup
/tntrun admin setdoublejump \<arena> <true|false>	Toggle double jump	nexaltntrun.admin.setup
/tntrun admin setname \<arena> \<display name>	Set the name players see	nexaltntrun.admin.setup
/tntrun admin setblocks \<arena> \<blocks>	Set the blocks that fall, e.g. SAND,TNT	nexaltntrun.admin.setup
/tntrun admin addcmd \<arena> \<place> \<command>	Add a reward command for place 1, 2 or 3	nexaltntrun.admin.setup
/tntrun admin clearcmd \<arena> [place]	Clear the arena's reward commands (the defaults apply again)	nexaltntrun.admin.setup
/tntrun admin setschedule \<arena> <cron|off>	Open a lobby on a schedule	nexaltntrun.admin.setup
/tntrun admin enable \<arena>	Enable an arena	nexaltntrun.admin.setup
/tntrun admin disable \<arena>	Disable an arena	nexaltntrun.admin.setup
/tntrun admin start \<arena>	Open a lobby	nexaltntrun.admin.start
/tntrun admin forcestart \<arena>	Start the fullest lobby in 5 seconds, below the minimum player count. A game started with one player is practice: no winner, stats or rewards	nexaltntrun.admin.start
/tntrun admin stop \<arena>	Stop every game of an arena (no stats recorded)	nexaltntrun.admin.stop
/tntrun admin reload	Reload config.yml and messages.yml	nexaltntrun.admin.reload
/tntrun admin export	Export all data to export/	nexaltntrun.admin
/tntrun admin import	Import data from export/	nexaltntrun.admin

Admin Menu

/tntrun admin opens a hub:

• Arenas: every arena with its status. An arena's screen enables or disables it, opens a lobby, force starts, stops its games and deletes it. Its Settings screen holds everything that belongs to the arena: block delay, minimum and maximum players, lobby countdown, time limit, double jump (toggle, cooldown, power), the lobby, spectator and game spawns and the death level (set at your position), the falling blocks (left click adds the block in your hand, right click removes it), and shows its display name, rewards and schedule.
• Configuration: the plugin-wide settings: rewards and the Vault money for each of the top three, winner fireworks and their count, block particles (and their count) and sound, scheduled games, games per arena and the empty lobby timeout.
• Stop All Games, Export Data, Import Data and Reload Config.

Numbers: left click +1, right click -1, shift for the bigger step.

Permissions

Permission	Description	Default
nexaltntrun.use	View the help menu	true
nexaltntrun.join	Join and leave games, open the arena menu	true
nexaltntrun.stats	View statistics	true
nexaltntrun.leaderboard	View the leaderboards	true
nexaltntrun.admin	Admin menu, list, info, export, import; includes every nexaltntrun.admin.* node below	op
nexaltntrun.admin.create	Create arenas	op
nexaltntrun.admin.delete	Delete arenas	op
nexaltntrun.admin.setup	Set up arenas: region, spawns, settings, rewards, schedule, enable and disable	op
nexaltntrun.admin.start	Open lobbies and force start games	op
nexaltntrun.admin.stop	Stop games	op
nexaltntrun.admin.reload	Reload configuration	op
nexaltntrun.bypass.commands	Use any command during games	op
nexaltntrun.bypass.full	Join a full game	op

Placeholders

Requires PlaceholderAPI.

Player Statistics

Placeholder	Description
%tntrun_wins%	Total wins
%tntrun_games%	Games played (also %tntrun_games_played%)
%tntrun_second_place%	2nd place finishes
%tntrun_third_place%	3rd place finishes
%tntrun_blocks%	Total blocks removed (also %tntrun_blocks_removed%)
%tntrun_survival_time%	Total survival time
%tntrun_best_time%	Best survival time
%tntrun_winrate%	Win percentage
%tntrun_avg_blocks%	Average blocks per game
%tntrun_rank%	Rank by wins

Current Game

Placeholder	Description
%tntrun_in_game%	"yes" or "no"
%tntrun_current_arena%	Current arena ID
%tntrun_current_alive%	Players alive in the current game
%tntrun_current_total%	Players in the current game
%tntrun_current_state%	WAITING, STARTING, ACTIVE or ENDING
%tntrun_current_blocks%	Blocks removed this game
%tntrun_current_eliminated%	"yes" or "no"

Global

Placeholder	Description
%tntrun_arena_count%	Number of arenas
%tntrun_active_games%	Number of lobbies and games

Arena Info

Work with or without a player. Arena ids may contain underscores and match any capitalisation.

Placeholder	Description
%tntrun_arena_\<id>_status%	IDLE, or the state of the arena's fullest lobby or a running game
%tntrun_arena_\<id>_players%	Players in all of the arena's games
%tntrun_arena_\<id>_alive%	Players alive in that game
%tntrun_arena_\<id>_max%	Maximum players
%tntrun_arena_\<id>_games%	Lobbies and games of the arena
%tntrun_arena_\<id>_name%	Display name

Leaderboards

\<pos> is 1-100. _count works as an alias of _value.

Placeholder	Description
%tntrun_top_wins_\<pos>_name% / _value%	By wins
%tntrun_top_games_\<pos>_name% / _value%	By games played
%tntrun_top_blocks_\<pos>_name% / _value%	By blocks removed
%tntrun_top_time_\<pos>_name% / _value%	By best survival time

Configuration

config.yml

storage:
  type: "json"          # or "sql"
  sql:
    host: "localhost"
    port: 3306
    database: "minecraft"
    username: "root"
    password: ""

# Defaults for newly created arenas; each arena keeps its own copy (admin menu > arena > Settings)
game:
  lobby-countdown: 30
  game-duration: 0            # seconds, 0 = no limit
  block-disappear-delay: 8    # ticks
  min-players: 4
  max-players: 24
  collapsible-blocks: ["SAND", "TNT", "RED_SAND", "GRAVEL"]
  max-concurrent-games-per-arena: 5
  empty-lobby-timeout: 120    # seconds an empty lobby stays open

# Double jump defaults for newly created arenas (the sound is in messages.yml)
double-jump:
  enabled: true
  cooldown: 100               # ticks
  power: 0.8

effects:
  particle:
    enabled: true
    type: "BLOCK"             # BLOCK_CRACK on servers before 1.20.5
    count: 20
  sound:
    enabled: true
    type: "BLOCK_SAND_BREAK"
    volume: 0.5
    pitch: 1.0

arena:
  target-world: "tntrun_arenas"   # void world the copies are pasted into, created on first use

rewards:
  enabled: true
  money:                      # paid through Vault
    1: 1000
    2: 500
    3: 250
  default:                    # console commands; %player%, %position%, %arena%, %blocks%
    1: ["give %player% diamond 5"]
    2: ["give %player% iron_ingot 10"]
    3: ["give %player% gold_ingot 5"]

fireworks:
  enabled: true
  count: 5
  delay-ticks: 10

scheduling:
  enabled: true               # pauses every arena schedule when false

command-whitelist: []          # commands players may use during games

Rewards are handed out after each player gets their own inventory back. A player who leaves a running game (/tntrun leave, disconnecting or a kick) counts as eliminated at that moment and takes the place that gives them. They get its reward once, when the game ends: at once if they are online and not in another game, otherwise the money at once and the reward commands when they next join. A game stopped by an admin (/tntrun admin stop, Stop All Games) pays no rewards, leavers included.

Existing arenas keep their own time limit; game-duration only sets it for arenas created afterwards.

Schedules

/tntrun admin setschedule \<arena> \<cron> takes a five-field cron pattern: minute, hour, day of month, month, day of week. 0 20 * * * opens a lobby every day at 20:00, */30 * * * * every 30 minutes, 0 18 * * 5 every Friday at 18:00. off removes the schedule.

messages.yml

Every message players see is in messages.yml, in MiniMessage format, with optional title, subtitle, action bar and sound. Colors are listed at the top of the file for find-and-replace. Messages missing from an older file fall back to the built-in text.

game-win:
  message:
    - "        <gradient:#FF7A1A:#FF9A4D>\<bold>WINNER!\</bold>\</gradient>"
    - "  <gradient:#FFB27A:#FFC99E>%player%\</gradient> \<gray>won the game!\</gray>"
  title: "<gradient:#FF7A1A:#FF9A4D>\<bold>VICTORY!\</bold>\</gradient>"
  subtitle: "<gradient:#FFB27A:#FFC99E>%player%\</gradient> \<gray>wins!\</gray>"
  sound: "UI_TOAST_CHALLENGE_COMPLETE"

Arena Setup Guide

1. Build the arena with layers of collapsible blocks (sand on TNT is classic).
2. Create it: /tntrun admin create \<name>
3. Save the region: /tntrun admin setregion \<name>, then click two opposite corners. This saves schematics/\<name>.schem.
4. Set the lobby and spectator spawns: stand there and run /tntrun admin setlobby \<name> and /tntrun admin setspectator \<name>.
5. Add game spawns (optional): /tntrun admin setspawn \<name> at each start position. Without any, players start at the lobby spawn.
6. Set the death level: stand below the lowest layer and run /tntrun admin setdeath \<name>.
7. Adjust settings (optional) in /tntrun admin > Arenas > your arena > Settings.
8. Add rewards (optional): /tntrun admin addcmd \<name> 1 give %player% diamond 3
9. Check and enable: /tntrun admin info \<name> lists anything missing; then /tntrun admin enable \<name>.

To move between JSON and SQL storage: /tntrun admin export, change storage.type, restart the server (storage is read at startup, a reload is not enough), then /tntrun admin import.

Spawns and the death level are stored relative to the arena, so they follow every pasted copy.

Installation

1. Install WorldEdit (or FastAsyncWorldEdit).
2. Place the JAR in plugins/ and restart the server.
3. Adjust config.yml and messages.yml if you like.
4. Set up arenas with the guide above.

Database Schema

With SQL storage the plugin creates these tables.

tntrun_arena_templates

Column	Type	Description
id	VARCHAR(64) PK	Arena identifier
display_name	VARCHAR(64)	Display name
enabled	BOOLEAN	Whether the arena is enabled
type	VARCHAR(32)	Arena type (SCHEMATIC)
schematic_path	VARCHAR(255)	Path to the schematic file
world_name	VARCHAR(255)	Unused by TNT Run (SLIME_WORLD arenas only)
target_world	VARCHAR(64)	World for the arena copies (empty: arena.target-world)
metadata	TEXT	JSON: origin, spawns, bounds
layer_count	INT	Unused, kept for older data
block_disappear_delay	INT	Block removal delay (ticks)
death_y_level	DOUBLE	Death level, in the coordinates of the world the arena was built in
double_jump_enabled	BOOLEAN	Double jump toggle
double_jump_cooldown	INT	Double jump cooldown (ticks)
double_jump_power	DOUBLE	Double jump velocity
min_players	INT	Minimum players to start
max_players	INT	Maximum players
lobby_countdown	INT	Lobby countdown (seconds)
start_countdown	INT	Unused, kept for older data
game_duration	INT	Time limit (seconds)
cron_schedule	VARCHAR(50)	Cron pattern for scheduled games
reward_commands	TEXT	JSON map of place to commands
collapsible_blocks	TEXT	JSON list of block types

tntrun_player_stats

Column	Type	Description
playerId	VARCHAR(36) PK	Player UUID
player_name	VARCHAR(16)	Player's username
games_played	INT	Games played
wins	INT	Wins
second_place	INT	2nd place finishes
third_place	INT	3rd place finishes
total_blocks_removed	INT	Blocks removed
total_survival_time	BIGINT	Total survival time (ms)
best_survival_time	BIGINT	Best survival time (ms)
updated_at	BIGINT	Last update

tntrun_game_records

Column	Type	Description
gameId	VARCHAR(64) PK	Random unique game id
arena_id	VARCHAR(64)	Arena played
start_time	BIGINT	Start timestamp
end_time	BIGINT	End timestamp
winner_id	VARCHAR(36)	Winner's UUID
winner_name	VARCHAR(16)	Winner's username
player_count	INT	Participants
total_blocks_removed	INT	Blocks removed in the game
placements	TEXT	JSON array of placements