TNT Run

Minimum Java Version: Java 25

TNT RUN

TNT Run is a fast-paced jump 'n run Minecraft minigame where players survive for as long as possible by parkouring across floors of disappearing blocks.

Players are placed on sand or gravel floors that fall away moments after they are touched. Falling sends players down to the next layer, until the final floor above the void eliminates them. The smaller the remaining space gets, the harder it becomes. The last player alive wins.

FEATURES

Classic TNT Run Gameplay: Run, jump, and outlast everyone else as the ground disappears beneath your feet.
Multi-Layer Arenas: Build arenas with multiple falling floors and let the void decide the final survivor.
Double Jumps: Give players a configurable number of double jumps, cooldowns, and permission-based amounts for clutch escapes.
Smart Block Restoration: Every removed block is tracked and restored automatically after each match, keeping arenas pristine and ready for the next round.
Spectator Tools: Eliminated players can spectate with player teleporting, speed controls, night vision, and visibility settings.
Arena Records & Statistics: Track wins, losses, streaks, longest survival time, personal arena bests, and global arena records.
Interactive GUI Setup: Create and manage arenas through visual in-game menus instead of manually editing files.
Arena Signs: Create clickable join signs that display live arena state and let players join instantly.
Scoreboards & BossBars: Keep players informed with fully configurable live game displays.
Highly Configurable: Customize messages, sounds, menus, items, block removal, scoreboards, boss bars, and gameplay behavior.
PlaceholderAPI & Leaderboards: Display live player, arena, record, and leaderboard data on holograms, scoreboards, or other plugins.
Flat File & MySQL Storage: Start with simple local storage or scale player data across your network with MySQL.
Developer API: Hook into game lifecycle, player flow, eliminations, and statistic changes through a public event API.

ARENA SETUP GUIDE

Setting up a TNT Run arena is intuitive with the in-game GUI editor. Follow these steps:

Step 1: Create the Arena
Initialize a new arena with a unique ID.

Code:

/tr create <arena_id>

Step 2: Open Setup Menu
Enter the edit mode to access the full configuration GUI.

Code:

/tr edit <arena_id>

Step 3: Set Locations
Use the setup menu to configure the required arena locations.

Lobby: Where players wait before the game starts.
Start: Where players spawn when the match begins.
End: Where players are sent after leaving or when the game finishes.

Step 4: Set Player Amounts
Configure the minimum number of players required to start and the maximum capacity of the arena.

Step 5: Set Optional Settings
Fine-tune the arena from the setup menu. Optional settings include the map name, per-arena scoreboard and boss bar toggles, potion effects, and resetting arena records.

Step 6: Create a Game Sign (Optional)
Place a sign, look directly at it, then click the Sign item in the setup menu to link it to the arena.

Step 7: Register & Join
Click the Firework item to save, register, and activate the arena. Players can then join via command or the linked game sign.

How to Join:

Command:
Code:
```
/tr join <arena_id>
```
Sign: Right-click a linked TNT Run arena sign.

GAMEPLAY FLOW

Join the Arena: Players join a waiting arena with a command or by right-clicking a linked arena sign.
Wait for the Countdown: Once the minimum player requirement is reached, the countdown begins and everyone is prepared for the match.
Keep Moving: Sand and gravel blocks disappear shortly after players run or stand on them, so stopping is never safe.
Fall Through the Floors: Missing a jump sends players to the floor below, where they must find a new route before it disappears too.
Use Double Jumps: Time a double jump to cross gaps, escape a collapsing route, or save a run at the last moment.
Spectate After Elimination: When players reach the void, they can watch the remaining runners with built-in spectator tools.
Claim the Win: The last surviving player wins, earns statistics, and can set a new arena survival record.

COMMANDS & PERMISSIONS

All commands can be used via /tntrun or /tr.

Gameplay Commands
No permissions required by default.

/tr join <arena>

Join a specific TNT Run arena lobby. If the match is already running, the plugin joins you as a spectator.
/tr leave

Safely leave the current arena and restore your normal player state.
/tr stats [player]

Open the in-game statistics menu for yourself or a cached online/offline player.

Arena Setup & Management
Requires tntrun.arena.* for full access.

/tr create <arena_id>

Permission: tntrun.arena.create
Create a new arena with the specified unique ID.
/tr delete <arena_id> [--confirm] [--cancel]

Permission: tntrun.arena.delete
Delete an arena after confirming the action.
/tr edit <arena_id>

Permission: tntrun.arena.edit
Open the in-game GUI editor for arena setup.
/tr list

Permission: tntrun.arena.list
Display all registered arenas and their setup status.

Main Administration Commands
Requires tntrun.admin.* for full access.

/tr help

Permission: tntrun.command.help
Display the TNT Run command help menu.
/tr start [arena]

Permission: tntrun.admin.start
Force-start the current arena or a specified arena, bypassing the countdown.
/tr stop [arena]

Permission: tntrun.admin.stop
Stop the current or specified active game.
/tr kick <player>

Permission: tntrun.admin.kick
Remove a player from an active arena and send them to its end location.
/tr reload

Permission: tntrun.admin.reload
Reload configuration files, messages, items, sounds, signs, and game settings without restarting the server.
Break arena signs

Permission: tntrun.sign.break
Allow breaking TNT Run arena signs.

Advanced Troubleshooting
Requires tntrun.debug.* for full access.

Note: Debug commands are intended for testing and troubleshooting.

/tr debug join <arena> [--players=p1,p2,...]

Permission: tntrun.debug.join
Join an arena for testing, optionally adding named online players.
/tr debug timer [arena] <time>

Permission: tntrun.debug.timer
Set the remaining timer for the current or selected active arena.
/tr debug component <message> [--path=message.path]

Permission: tntrun.debug.component
Preview MiniMessage text or a configured message path in-game.
/tr debug dump

Permission: tntrun.debug.dump
Generate an event timing report for troubleshooting performance issues.

STATS & LEADERBOARDS

TNT Run is built to reward players who keep coming back. Track wins, losses, win streaks, longest survival time, per-arena personal bests, and arena records—then put the best players on display with live leaderboards.

PLACEHOLDERS

To use these placeholders, you must have PlaceholderAPI installed on your server.

Individual Player Stats
These placeholders display statistics for the player viewing them.

Code:

%tntrun_name%                 - Returns the player's name
%tntrun_uuid%                 - Returns the player's unique ID
%tntrun_wins%                 - Total number of games won
%tntrun_win_streak%           - Current win streak
%tntrun_longest_win_streak%   - Highest win streak ever reached
%tntrun_losses%               - Total number of games lost
%tntrun_games_played%         - Total games participated in
%tntrun_longest_survive%      - Longest survival time
%tntrun_win_rate%             - Win percentage

Real-Time Arena Data
Fetch live data from specific arenas. Replace <id> with your arena identifier (e.g., arena1).

Live Game Data

Code:

%tntrun_arena:<id>:players%          - Current player count
%tntrun_arena:<id>:players_left%     - Players still alive
%tntrun_arena:<id>:state%            - Game state
%tntrun_arena:<id>:record_holder%    - Arena record holder
%tntrun_arena:<id>:record_time%      - Arena record time

Arena Settings

Code:

%tntrun_arena:<id>:min_players%      - Min required players
%tntrun_arena:<id>:max_players%      - Max allowed players
%tntrun_arena:<id>:map_name%         - Configured map name
%tntrun_arena:<id>:ready%            - Whether the arena is ready

Leaderboard System
Display your server's top-performing players on scoreboards or holograms.

Syntax

Code:

%tntrun_leaderboard:<statistic>:<position>:<type>%

1. Parameters

<statistic>: The stat to be ranked (see list below).
<position>: The rank position (1, 2, 3...).
<type>:
Code:
```
name
```
(username)
Code:
```
value
```
(score)
Code:
```
uuid
```
or
Code:
```
formatted_value
```

2. Available Statistics
You can use these stats for ranking:

wins (Total wins)
losses (Total losses)
win_streak (Current streak)
longest_win_streak (Best streak)
longest_survive (Longest survival time)
arena_time_<arena_id> (Best survival time in a specific arena)

3. Usage Examples

Code:

# Name of the 1st place winner (Most Wins)
%tntrun_leaderboard:wins:1:name%

# Score of the 1st place winner
%tntrun_leaderboard:wins:1:value%

# Name of the 3rd place for longest survival time
%tntrun_leaderboard:longest_survive:3:name%

# Name of the fastest player on a specific arena
%tntrun_leaderboard:arena_time_arena1:1:name%

bStats METRICS

This plugin collects anonymous usage statistics through bStats.

This data (such as player count, server version, and Java version) helps us understand how the plugin is being used and allows us to make better development decisions. No private information is collected.

Enjoying the plugin?

We spend hundreds of hours making TNT Run the best minigame experience for your server.
If you like the plugin, please consider leaving a 5-star review!

A huge thank you to everyone who has supported the project so far!

TNT Run v1.0.0

Overview History