HypeTnT — Documentation

💣 Plugin Documentation

HYPETNT

A feature-rich, high-performance and fully configurable TNT plugin built for large servers. Throw TNT, watch blocks fly, see them regenerate — zero lag, total control.

Paper 1.21+ Java 21+ v2.0 1000+ Players EN / TR

🏠

OVERVIEW

HypeTnT completely transforms the vanilla TNT experience on your Paper server. Every feature is toggleable, every value is tunable, and the entire message system supports both English and Turkish out of the box.

Core Feature Set

🚀

TNT Throwing

Right-click while holding TNT to launch it as a projectile with configurable velocity.

🔥

Auto-Ignite

TNT placed on the ground ignites instantly — no flint and steel needed.

🔁

Block Regeneration

Exploded blocks restore themselves with animated SEQUENTIAL or instant ALL_AT_ONCE modes.

📦

No-Regen Blocks

Certain blocks (e.g. chests) drop their contents and are permanently destroyed — never restored.

🌊

Realistic Explosion

Blocks physically fly through the air as FallingBlock entities, creating cinematic explosions.

🪨

Obsidian Breaker

Obsidian requires multiple TNT hits before breaking, with a 5-minute counter reset.

⚡

TNT Jump Mode

Zero damage but full knockback — perfect for jump courses and minigame servers.

🌍

Multi-Language

English and Turkish included. Add any language by creating a simple YAML file.

Architecture Highlights

✅

Zero disk I/O on hot pathsAll config values are cached in memory by ConfigManager. Event handlers read only primitive fields — no FileConfiguration calls per event.

✅

Thread-safe cooldown mapConcurrentHashMap with a periodic async cleanup task prevents memory leaks even with thousands of players.

✅

Bounded regen task queuemax-concurrent-tasks limits simultaneous regen jobs. Extras wait in a FIFO queue and start automatically when a slot opens.

📦

INSTALLATION

Requirements

Requirement	Version	Note
Paper / Purpur	1.21+	Spigot is NOT supported
Java	21+	Required for modern API features

Step-by-Step

Download the JAR

Download HypeTnT.jar from Modrinth and place it in your server's /plugins folder.

Start your server

config.yml, lang/en.yml and lang/tr.yml are created automatically in plugins/HypeTnT/.

Set your language

Open config.yml and set language: "en" for English or language: "tr" for Turkish.

Configure and reload

Adjust any settings in config.yml then run /hypetnt reload — no server restart required.

Folder Structure

shell

plugins/
└── HypeTnT/
    ├── config.yml       # Main configuration
    ├── lang/
    │   ├── en.yml       # English messages
    │   └── tr.yml       # Turkish messages

💣

TNT MECHANICS

Throwing

Hold TNT in your hand and right-click (air or block) to launch it as a projectile. The throw velocity is configurable. Creative mode players keep their TNT stack.

ℹ️

Cooldown SystemA per-player cooldown prevents spamming. While waiting, an Action Bar countdown is shown. When ready, a notification appears. Both messages are fully translatable.

Auto-Ignite

When auto-ignite: true, placing a TNT block immediately spawns a primed TNT entity at that location without requiring a flint and steel.

Custom Fuse Timer

Set fuse-ticks to control exactly how long TNT takes to explode. 20 ticks = 1 second. Default is 80 ticks (4 seconds).

Live Countdown Display

When custom-name.enabled: true, a floating name above the TNT shows the remaining fuse time. Supports full colour codes and the %timer% placeholder.

yaml

tnt-settings:
  throw-enabled:  true
  throw-velocity: 1.5
  auto-ignite:    true
  fuse-ticks:     80
  custom-name:
    enabled:         true
    names:
      - "&c%timer%s &4💣"
    update-interval: 10

🔁

BLOCK REGENERATION

Regen Types

⬆️

SEQUENTIAL

Blocks restore one by one from bottom to top with configurable per-block interval. Plays sound and particle effects at each block.

⚡

ALL_AT_ONCE

Every block snaps back at exactly the same moment after the delay. Ideal for fast-paced PvP servers.

No-Regen Blocks

Add blocks to no-regen-blocks to mark them as permanently destructible. These blocks are broken by TNT and their contents drop as items, but they never regenerate.

⚠️

ImportantDo NOT add blocks to both blacklist and no-regen-blocks. Blacklisted blocks cannot be broken at all, so the no-regen rule would never apply.

yaml

regen-settings:
  min-delay:            3
  max-delay:            5
  type:                 SEQUENTIAL
  interval:             2
  play-effects:         true
  max-concurrent-tasks: 15
  no-regen-blocks:
    - CHEST
    - TRAPPED_CHEST
    - BARREL

💥

EXPLOSION CONTROL

Blacklist

Blocks in the blacklist are completely immune to TNT. They will never be broken regardless of explosion strength.

Whitelist Mode

Enable whitelist.enabled: true to flip the logic — only blocks in the whitelist can be broken; everything else is protected.

Realistic Explosion

When enabled, blocks do not vanish instantly. Instead they spawn as FallingBlock entities that fly outward from the explosion centre and disappear on landing.

🎯

max-blocks

Caps the number of FallingBlock entities spawned per explosion. Keeps entity count safe on busy servers.

💢

hurt-entities

Toggle whether flying blocks deal damage to players and mobs they hit mid-air.

yaml

explosion-settings:
  radius:        5.0
  cause-fire:    false
  break-blocks:  true
  max-blocks:    200
  blacklist:
    - BEDROCK
    - OBSIDIAN
  whitelist:
    enabled: false
  realistic:
    enabled:       false
    max-blocks:    40
    hurt-entities: true

🪨

OBSIDIAN BREAKER

The Obsidian Breaker adds a multi-hit mechanic to obsidian. Instead of being permanently immune, obsidian weakens with each TNT hit and breaks after a configurable number of hits.

How It Works

TNT explodes near obsidian

The plugin increments the hit counter for that specific block location.

Nearby players are notified

An Action Bar message shows remaining hits required.

Block breaks on final hit

The obsidian block is removed and the counter is cleared for that location.

Counter resets after 5 minutes

If no hit arrives within 5 minutes, the counter resets to 0 automatically.

⚠️

No blacklist changes neededObsidian does NOT need to be removed from the blacklist. When obsidian-breaker.enabled: true, the plugin automatically bypasses the blacklist check for obsidian.

yaml

obsidian-breaker:
  enabled:        true
  hits:           3
  notify-player: true

⚡

TNT JUMP

TNT Jump mode lets players use TNT explosions to launch themselves without taking any damage. Full knockback is always preserved.

Configuration

Setting	Default	Description
player-damage	false	Set to true for normal damage. False = zero damage, full knockback.
tnt-damage-divisor	1.0	Divide TNT damage by this value. 2.0 = half damage.
fall-damage-divisor	5.0	Reduce landing damage for 8s after being launched by TNT.

🚀

Recommended TNT Jump SetupSet player-damage: false (default) and configure fall-damage-divisor: 10.0 for a smooth experience where players can land safely.

yaml

damage-settings:
  player-damage:       false
  tnt-damage-divisor:  1.0
  fall-damage-divisor: 5.0

⚙️

CONFIG REFERENCE

All Options at a Glance

Key	Default	Description
language	en	Plugin language (en / tr)
tnt-settings.throw-enabled	true	Enable right-click throwing
tnt-settings.throw-velocity	1.5	Projectile speed multiplier
tnt-settings.auto-ignite	true	Ignite TNT on placement
tnt-settings.fuse-ticks	80	Ticks until explosion (20 = 1s)
cooldown-settings.enabled	true	Enable per-player cooldown
cooldown-settings.seconds	3.0	Cooldown duration in seconds
explosion-settings.radius	5.0	Explosion strength
explosion-settings.cause-fire	false	Spawn fire on explosion
explosion-settings.break-blocks	true	Allow block destruction
explosion-settings.max-blocks	200	Block cap per explosion
explosion-settings.disable-drops	false	Suppress item drops
explosion-settings.realistic.enabled	false	Flying-block explosion mode
regen-settings.type	SEQUENTIAL	SEQUENTIAL or ALL_AT_ONCE
regen-settings.min-delay	3	Minimum regen start delay (s)
regen-settings.max-delay	5	Maximum regen start delay (s)
regen-settings.max-concurrent-tasks	15	Max simultaneous regen jobs
damage-settings.player-damage	false	TNT deals damage to players
damage-settings.fall-damage-divisor	5.0	Post-TNT fall damage reduction
obsidian-breaker.enabled	false	Multi-hit obsidian breaking
obsidian-breaker.hits	3	Hits required to break obsidian
minecart-tnt.enabled	true	Apply rules to TNT Minecarts

ℹ️

/hypetnt reloadAll config values and language files are reloaded live. No server restart is ever needed.

🛠️

COMMANDS

Command	Permission	Description
/hypetnt reload	hypetnt.admin	Reload config.yml and all language files live — no restart needed

Usage Example

console

/hypetnt reload
# Output:
[HypeTnT] Configuration successfully reloaded!

🔑

PERMISSIONS

Permission	Default	Description
hypetnt.admin	OP	Access to /hypetnt reload command

ℹ️

No permission needed for TNT useThrowing, placing, and all TNT mechanics are available to all players by default. Only the reload admin command is gated behind a permission.

🌍

MULTI-LANGUAGE

Supported Languages

🇬🇧

English

language: en

🇹🇷

Türkçe

language: tr

Adding a Custom Language

Copy the English file

Duplicate plugins/HypeTnT/lang/en.yml and rename it to xx.yml (e.g. de.yml for German).

Translate every value

Change the text on the right side of each key. Do not rename or remove any keys.

Update config.yml

Set language: "xx" in config.yml and run /hypetnt reload.

✅

Automatic fallbackIf a key is missing from your custom language file, the plugin automatically uses the English value. You will never see a raw key in-game.

❓

FREQ. ASKED QUESTIONS

Does HypeTnT work with TNT Minecarts? ▶

Yes. Enable minecart-tnt.enabled: true in config.yml. All explosion rules apply equally to TNT Minecart explosions.

Will the regeneration system lag my server? ▶

No. The max-concurrent-tasks setting limits the number of regen jobs running simultaneously. All additional jobs are queued and start as soon as a slot opens.

Can I make chests permanently destroyable? ▶

Yes. Add CHEST and TRAPPED_CHEST to the no-regen-blocks list. When TNT breaks them, their items drop on the ground and the blocks never come back.

How do I set up TNT Jump mode? ▶

Set player-damage: false (already the default) and configure fall-damage-divisor to a high value like 5.0 or 10.0. Players will be launched with full knockback but take little or no damage on landing.

Can I disable the plugin in specific worlds? ▶

Yes. Add the world name to the disabled-worlds list in config.yml. No TNT mechanics will apply in those worlds at all.

Does obsidian need to be removed from the blacklist? ▶

No. When obsidian-breaker.enabled: true, the plugin automatically bypasses the blacklist check for obsidian.

Can I add my own language? ▶

Yes. Copy lang/en.yml to lang/xx.yml, translate every value, and set language: "xx" in config.yml. Missing keys fall back to English automatically.

Does this work on Spigot? ▶

No. HypeTnT uses Paper-exclusive APIs. Paper or Purpur 1.21+ is required.

📊

PERFORMANCE

HypeTnT is designed from the ground up for large servers. Here is a summary of every optimization built into the plugin.

Memory

🧹

Cooldown Auto-Cleanup

An async task runs every 5 minutes and removes expired cooldown entries. The map never grows unbounded even with thousands of players.

🔒

ConcurrentHashMap

All player-keyed maps use ConcurrentHashMap, safe for multi-threaded access without external synchronisation.

📏

max-blocks Cap

Each explosion is limited to max-blocks BlockState snapshots. Unlimited block capture would cause out-of-memory errors.

CPU

⚡

Zero I/O on Hot Paths

ConfigManager caches all values as primitives. Event handlers never call FileConfiguration — they read only local fields.

🎯

O(1) Blacklist Lookup

Blacklist and whitelist are stored as Set<Material>. contains() is O(1) instead of the O(n) cost of a List.

📋

Task Queue

max-concurrent-tasks prevents task flooding. Regen jobs beyond the limit wait in a FIFO queue and start as slots open.

Recommended Settings for Large Servers

yaml — 500+ players

explosion-settings:
  max-blocks:     150
  realistic:
    max-blocks:   20
regen-settings:
  max-concurrent-tasks: 10
  interval:             3