True Combat Manager

# True Combat Manager

Professional combat tracking with interactive GUIs, persistent statistics, dual grace period protection, and modern Minecraft server optimization.





—

## Overview

True Combat Manager is a feature-rich combat management system designed for competitive Minecraft PvP servers. It focuses on accurate combat detection, preventing PvP abuse, providing clear player feedback, interactive statistics GUIs, and persistent data tracking.

—

## ✨ What’s New in v1.2.1

### Dual Grace Period System

The disconnect protection system has been completely overhauled.

– **Bad-internet grace period** — longer, more lenient window for players who lost connection unexpectedly. Detected automatically from the quit reason.
– **Intentional grace period** — shorter window for players who pressed Disconnect or closed the game.
– Each type has its own `grace-seconds`, messages, and can be enabled/disabled independently.

### Repeat-Logout Abuse Prevention

– Tracks each player’s disconnect history in a rolling time window.
– If a player disconnects too many times within the window, they are killed immediately on the next logout — no grace period.
– Fully configurable: `max-count`, `window-seconds`, messages.

### Bypass-Totem Config

– `bypass-totem: true` (default) — punishment kills bypass the Totem of Undying.
– `bypass-totem: false` — a held totem can proc and save the player.

### Per-Player Theme Persistence

– Theme selections saved to the database and restored across sessions.
– `/combat toggle-style` works both in and out of combat.

### Sound Profile Hot-Reload

– `/combat reload` now correctly updates sound profiles without a restart.

### Bug Fixes

– Fixed inventory duplication (armor dropped twice due to `getContents()` including armor slots)
– Fixed double bossbar on reconnect
– Fixed player not killed after grace period (config loaded before ConfigManager was ready)
– Fixed concurrent update race in player data
– Fixed `plugin.getConfig()` stale after reload

—

## Core Features

### Combat System

– Real-time combat detection
– Dual grace period disconnect protection (bad-internet vs intentional)
– Repeat-logout abuse prevention with kill-on-login
– Lag compensation using server TPS
– Thread-safe combat architecture

### Interactive GUI System

– **Player Stats GUI** — overall record, damage stats, combat stats
– **Weapon Stats GUI** — per-weapon breakdown (swords, axes, ranged)
– **Server Overview GUI** — admin panel with network-wide statistics
– Fully configurable via `gui.yml`
– Back buttons and seamless navigation

### Database System

– SQLite (default, no setup required)
– MySQL for larger networks
– Persistent player statistics and theme preferences
– Automatic database migration

### Smart Restrictions

– Ender pearl cooldown control
– Trident usage restrictions
– Elytra combat limitations
– Golden apple cooldown system
– Teleport command blocking
– Safezone protection support

### Visual Interface

– 6 built-in themes with per-player persistence
– BossBar combat indicators
– ActionBar status display
– 6 sound profiles with hot-reload
– HEX color customization

### Protection Systems

– Newbie protection for unarmored players
– Timed immunity system with admin commands
– WorldGuard safe zone integration
– Configurable bypass permissions

—

## Disconnect Protection Flow

**Grace period expires, player still offline:**
1. Inventory dropped at disconnect location immediately
2. Win/loss recorded, opponent notified and rewarded
3. `pendingPunishments` entry stored — player killed on next login

**Player rejoins with pending punishment:**
1. Live inventory cleared
2. Player killed (totem bypass configurable)
3. Opponent receives reminder message

—

## Commands

### Player Commands

“`
/combat status – View your combat status
/combat stats – Open your combat statistics GUI
/combat summary – View latest fight summary
/combat toggle-style – Change visual theme (works anytime)
“`

### Admin Commands

“`
/combat reload – Reload configuration
/combat inspect – View real-time combat info
/combat summary – Open player’s stats GUI
/combatadmin stats – Open server statistics GUI
/combat clear – Force-end combat
/combat protection – Grant immunity
/combat debug – Toggle debug mode
/combat logging – Toggle console logging
“`

—

## Configuration Example

“`yaml
combat:
duration: 10
disconnect-protection:
enabled: true
bad-internet:
grace-seconds: 30
intentional:
grace-seconds: 10
repeat-logout:
enabled: true
max-count: 2
window-seconds: 240
punishment:
drop-inventory: true
bypass-totem: true

visual:
themes:
default-theme: “clean”
sounds:
profile: “default”

database:
type: “sqlite”

logging:
console-enabled: false
“`

All settings reload instantly with `/combat reload`.

—

## PlaceholderAPI Support

“`
%pvpcombat_in_combat%
%pvpcombat_time_left%
%pvpcombat_opponent%
%pvpcombat_wins%
%pvpcombat_losses%
%pvpcombat_kd_ratio%
%pvpcombat_win_rate%
%pvpcombat_total_damage_dealt%
%pvpcombat_total_damage_received%
“`

—

## Installation

1. Download the plugin JAR
2. Place it inside the `plugins` folder
3. Restart the server
4. Configure settings if needed
5. Run `/combat reload`

**No additional setup required** — SQLite works out of the box.

—

## Requirements

Minecraft **1.18+** · Java **17+** (21 recommended) · Paper or Spigot

**Optional:** PlaceholderAPI · WorldGuard · ProtocolLib

—

## Support

https://github.com/muzlik-gm/True-Combat-Manager/issues

—

© 2026 muzlik · Made for the Minecraft PvP community

True Chaos Cubes

Adds more Sulfur Cube Archetypes to the game

**TNT** – Ignites when moved, any fast movement will delay the explosion

**Honey Block** – Sticks to ceilings

**Slime Block** – Bounces higher

**Piston** – Launches upwards when powered by redstone

**Soul Sand** – Propelled upwards when in water

**Magma Block** – Propelled downwards when in water

**Sponge** – Becomes Wet Sponge after 1 minute in water

**Concrete Powder** – Places concrete if in water, splitting the Sulfur Cube

ThrowableTNT

# Overview
A tiny lightweight plugin that lets players throw TNT with a left-click.
Fully configurable: power, fuse-time, explode-radius, damage, block breaking, hot-reload, and custom identification to avoid mixing with vanilla TNT.
Zero dependencies, designed for Spigot/Paper 1.17 and up

## Key Features

– Left-click to throw TNT (configurable power & fuse)

– Custom radius & max damage with distance falloff

– Toggle block breaking per explosion

– Optional custom ID in lore to distinguish “our TNT” from vanilla (ON by default)

– /throwabletnt reload to reload configs & messages

– Multi-language via messages_(language).yml

– Zero dependencies, small footprint, event-driven, no schedulers
## Commands & Permissions

– /throwabletnt reload – Reload config & messages (permission: throwabletnt.reload)
– /throwabletnt give – Give throwable TNT (permission: throwabletnt.give)

**Config Preview:**

“`# =============== Throwable TNT ===============#
# After writing the code below, the plugin will load plugins/ThrowableTNT/messages_.yml
# If the file doesn't exist, it falls back to messages_default.yml
language: default

throw:
# Throw power multiplier (launch speed)
launch-speed: 1.2
# Fuse seconds (integer) before explosion
fuse-seconds: 3

explosion:
# Explosion radius: affects shockwave coverage and damage falloff distance
range: 4.0

# Max damage at the explosion center; linearly decreases to 0 by 'range'
max-damage: 18.0

# Allow breaking blocks (false = damage only, no terrain damage)
allow-block-break: false

item:
# Whether to use a "custom identification tag" in the item's lore.
# true: Only "our TNT" (with the custom-id lore) can be thrown with left-click.
# false: Any TNT (including vanilla TNT) can be thrown with left-click.
use-custom-id: true

# The custom identification line written to the item's lore (supports & color codes)
custom-id: "&8ID: THROW-TNT"

# Visuals used only for the /give command (Server owner can rename and change description as needed)
name: "&cThrowable TNT"
lore: "&7Left-click to throw, explodes after a few seconds"

# Cancel players from right-clicking to place "our TNT" on the ground
# Only takes effect when use-custom-id=true; does not take effect when identification is off to avoid interfering with vanilla gameplay.
cancel-right-click-place: true
```
## How to Add Your Own Language
Copy messages_default.yml → messages_your-language.yml

Translate the messages

Set language: your_CODE in config.yml

/throwabletnt reload

TriviaChallengeX

TriviaChallengeX is a trivia plugin that either triggers automatically or manually. It is easy to set up and you can also change questions!

Challenge Types:

Trivia questions with configurable question bank
Math problems with adjustable difficulty
CAPTCHA-style challenges with customizable settings

Automatic Challenges:

Challenges trigger automatically at intervals set in the config
Requires a minimum number of players online

Reward System:

Customizable rewards per challenge type
Support for both item rewards and command rewards
Economy integration through command execution

User Experience:

Players answer directly in chat (no commands needed)
Colorful, formatted messages for better visibility
Challenge timeout with auto-expiration

Administration:

Full permission system
Admin commands for manual challenge control
Configuration reloading without server restart

Other Features:

Cooldown system to prevent reward farming
Basic GUI menu for easy access (expandable)
Fully customizable messages and colors

Trivia Buzzers

# TriviaBuzzers
**Interconnected buzzers** for live **trivia shows** on your Minecraft server.
Perfect for events: first buzz locks others, host can validate/refuse, winners are teleported to a validation zone—with fireworks & sounds.

## 🧭 Quick Start

“`
/triviabuzzers give player [number] # give player buzzers (buttons), place them
/triviabuzzers activate # open buzzing for the world

/triviabuzzers validate # Player had the right answer! Will need a new activation for the next question.
# or:
/triviabuzzers refuse # Player had the wrong answer.
“`

## 🔶 Commands

“`

# Give items
/triviabuzzers give player # Gives a player buzzer
/triviabuzzers give host # Gives a host buzzer
/triviabuzzers give wand # Gives a wand to break/remove buzzers when left click or right click on them.

# Host controls (per world)
/triviabuzzers activate # Enables the buzzer
/triviabuzzers deactivate # Disables the buzzer
/triviabuzzers validate # Validate answer
/triviabuzzers refuse # Refuse answer

# Validation zone
/triviabuzzers validationzone set [x y z] # Sets a zone where validated players will be tp’d. If no zone is set, players won’t get tp’d
/triviabuzzers validationzone reset # Resets the current validation zone
/triviabuzzers validationzone tp [player] # Tp to validation zone

# Maintenance
/triviabuzzers list # Shows all the buzzers
/triviabuzzers purge # Removes all the buzzers

“`

## 🔐 Permissions

> trivia.host

Use host commands (activate/deactivate/validate/refuse), and interact with host buzzers. OP by default.

> trivia.admin

Use the Buzzer Wand to remove any registered buzzer; receive the wand. Can Give themselves all sort of buzzers, and can define the validation zone. OP by default.

TrimSMP-S2

> **Disclaimer:** This is an unofficial remake of the TrimSMP plugin concept. I am not affiliated with the original TrimSMP server or team. This plugin is a fan-made recreation and I do not claim any credit for the original gameplay concept.

# ![TrimSMP](https://cdn.modrinth.com/data/cached_images/785b492adbe12c80b0ff401c040d70ff26f4ab4f.png) TrimSMP

Craft unique trimmed swords using armor trim templates at the smithing table. Each trim gives a completely different combat ability. 20 abilities, 10 materials, 1 sword limit per player.

![Join the Discord](https://discord.gg/lusik)

## Get an Accurate 1:1 TrimSMP-S2 Replica Click Here

# 🔹 Features

– **20 Unique Abilities**
Every armor trim template creates a sword with its own ability. Silence traps enemies in a sculk sphere. Ward fires a sonic beam. Vex shrinks you. Flow lets you ride a wind charge. Each one plays differently.

– **Smithing Table Crafting**
Combine a trim template + diamond sword + material at the smithing table. The material changes the sword’s color. The template decides the ability.

– **Cooldown & Duration System**
Abilities have configurable cooldowns and durations. The action bar shows your current state with custom unicode icons. Cooldown Dial halves your cooldown. Reverse Dial doubles nearby enemies’ cooldowns.

– **Fully Configurable**
Every cooldown, duration, damage value, radius, velocity, and message is configurable. Permission nodes for abilities, admin commands, and item access. Hot reload without server restart.

—

## Abilities Overview

| Trim | Ability |
| —- | ——- |
| Silence | Sculk sphere prison |
| Raiser | Forward dash |
| Rib | Damage multiplier buff |
| Shaper | Shapeshift into killed mob |
| Spire | Throw an ender pearl |
| Host | Copy another player’s ability |
| Wayfinder | Track nearest player with glowing |
| Ward | Warden sonic beam |
| Eye | Save location, teleport back |
| Coast | Drown the next player you hit |
| Wild | Haste VII + faster attack speed |
| Sentry | Resistance II + XP generation |
| Tide | Knockback all nearby players |
| Vex | Shrink to vex size |
| Dune | Pin a player into the ground |
| Bolt | Lightning strike area damage |
| Flow | Ride a wind charge |
| Snout | Extra hearts |
| Magnet | Pull entities or push on sneak |
| Dragon Egg | Glide + explosion on landing |

—

## Commands & Permissions

| Command | Permission | Description |
| ——- | ———- | ———– |
| /ability | — | Activate your trim sword ability |
| /resetcd [player] | op | Reset a player’s cooldowns |
| /trimsmp trims | op | Open the sword selection GUI |
| /trimsmp reload | op | Hot reload the config |
| /triminfo | — | View all ability descriptions |

—

## How It Works

1. **Get a trim template** → Any vanilla armor trim template works
2. **Smithing table** → Template + Diamond Sword + Material = Trimmed Sword
3. **Right click or /ability** → Activate your sword’s ability
4. **Cooldown starts** → Wait for it to expire, then use again
5. **One sword limit** → You can only carry one trimmed sword at a time

—

## Special Items

– **Cooldown Dial** — Keep it in your inventory to halve all ability cooldowns
– **Reverse Dial** — Right click to double every nearby enemy’s current cooldown
– **Magnet Trim** — Right click to Summon an Magnet that pulls nearby enemy’s

—

![Reverse Dial](https://discord.gg/lusik)
# Get the Texture Pack from my Discord Server

—

Need help or have suggestions? Feel free to reach out via my Discord Server.

**Remade by Lusik21556** (@lusik_2155)
**Textures by Sethasaures** (@sethasaures)

Trims Overhaul

![](https://cdn.modrinth.com/data/cached_images/edc7b63bd1a8673cc36f1a3902fee1a3b1faa228.png)

> #### Lightweight datapack that gives every trim unique powers, obtainable through one-time objectives.

Installation Guides

## ——- Datapack & Resource Pack ——————————-
– Download the second file in the versions tab. (Should look like `trims_overhaul-DP_RP-vX.X.X.zip`)

– For the datapack; Open your world folder (`.minecraft/saves/world`)
– Drop the zip into the `datapacks` folder as-is
– Then restart the server or world – `/reload` won’t work
– > **When updating:** Do not disable the datapack or some progress will be lost. Close the server, delete and replace the datapack file, then reopen it.

– For the resource pack; In Minecraft, go to Options > Resource Packs
– Drag the zip file into your Minecraft window
– Click the arrow on the new pack to enable it

## — Mod (Bundle for mod loaders) ——————————–
– Download the first file within the versions tab, then drag it into your mods folder (`.minecraft/mods`)
– The `.zip` can also be renamed to `.jar` to use it directly as a mod

### Join the Discord for any help or issues – Check out the Wiki for more information whenever

#### Translations; English, Español, Français, Deutsch, Polski, Italiano, Português, Türkçe, Русский, 한국어, 日本語, and 简体中文 ⁽ᴺᵒᵗ ᴾᵉʳᶠᵉᶜᵗ⁾

– If you’re interested in staying up to date, or enjoy the project, then please consider following.
– Feel free to use this datapack however you like, just with credit when possible.

Trimmed – An Addon for Completionist

An Addon for **Completionist** by **Jaycee7C**

Allows for all trimmed armor pieces (excluding dyed leather) to count for worldborder expansions.

NOTE: This is a very resource intensive datapack and will very much slow down the world.

TriHunt | Trilleo’s Manhunt Plugin

# 🧭 TriHunt — Minecraft Manhunt Plugin

**TriHunt** is a Manhunt plugin for Minecraft 26.1.2 **Paper** server, developed by **Trilleo**. One team runs. The
other hunts. The game ends when the Speedrunnersunners beat the chosen boss — or when the Hunters stop them first.

—

## ⚔️ How It Works

The classic Manhunt experience, brought to life on your server:

– 🏃 **Speedrunners** race to defeat the boss as fast as possible.
– 🗡️ **Hunters** relentlessly track them down to prevent it.
– 👀 **Spectators** watch the game at ease.
– Every second counts. Every decision matters.

—

## 🌟 What Makes TriHunt Special

– **Smooth & Modern** — Built from the ground up with a clean, polished experience in mind.
– **Team Selection** — Easily choose your side and jump straight into action.
– **In-Game Menus** — Intuitive, interactive menus make managing your game effortless.
– **GameRule Modifier** — Change Minecraft game rules directly in a GUI.
– **Custom Items** — Unique items and recipes to spice up the gameplay.

—

## 🎯 Game Modes

### Special Modes

– **Regular Mode**: The classic Manhunt experience.
– **Infested Mode**: If a speedrunner dies, he will become a hunter.

### Boss Modes

– **Ender Dragon**: The classic boss. Defeat it to win.
– **Wither**: A more challenging boss. Can you handle it?
– **Warden**: The ultimate challenge. Only the best can defeat it.

—

## 🧩 Features

All features can be toggled in **Settings**

### Auto-Refresh Compass

The compass will automatically refresh every 30 seconds.

### Speedrunner Bonus Time

When the game starts, the speedrunners can have escape time before hunters are released.

### Custom Items / Recipes

Custom items and recipes to enhance the gameplay experience.

—

## 🎮 Getting Started

Install the plugin and use the hotbar item to start!

—

## 📢 IMPORTANT

The plugin is still in **EARLY** development, with many features planned. You can report bugs or suggestions in
our GitHub page.

—

## 📝 Planned Features

### SPECIAL Modes

**Armed**, **Infested** and **Assassin** mode.

### Shop

Exchange powerful weapons/utilities.

### Hunter Freeze

Speedrunners can freeze hunters several times.

### One-Hit Axe

A weapon to instantly kill hunters. Limited durability!

### MORE Loot

Modify block/mob drop to speed up the pace.

TriggerVolumes

# TriggerVolumes Plugin

A powerful Spigot/Paper plugin for creating 3D trigger volumes with customizable actions that execute when players enter or leave defined areas.

## Features

– **Selection System**: Tool-based selection of cubic regions with visual feedback
– **Trigger Volumes**: Store and manage named volumes with precise coordinates
– **Volume Groups**: Group multiple volumes together for batch operations
– **Clone & Copy**: Clone volumes with actions or copy actions between existing volumes
– **Enter/Leave Actions**: Execute different actions when players enter or leave volumes
– **Action Types**:
– `PLAYER_COMMAND`: Execute commands as the player
– `CONSOLE_COMMAND`: Execute commands from console
– `MESSAGE`: Send colored messages to players
– `TELEPORT`: Teleport players to specific coordinates
– **Particle Visualization**: Real-time particle effects showing volume boundaries
– **Cooldown System**: Prevent action spam with configurable cooldowns
– **Spatial Hashing**: Optimized performance for servers with hundreds of volumes
– **Multi-Language**: Support for 7 languages (EN, DE, FR, PL, RU, JA, ES)
– **Persistent Storage**: Volumes and actions saved in YAML format
– **Reload Command**: Update configurations without server restart

## Requirements

– **Server**: Spigot or Paper 1.19+
– **Java**: Version 17 or higher
– **Permissions Plugin**: Optional (for permission management)

## Installation

1. Download `TriggerVolumes-1.0.4.jar`
2. Place the file in your server’s `plugins/` folder
3. Start or restart your server
4. Configuration files will be generated automatically in `plugins/TriggerVolumes/`

## Configuration

### Main Configuration (`config.yml`)

“`yaml
# Language Configuration
language:
default: en # Available: en, de, fr, pl, ru, ja, es

# Particle Settings
particles:
update-interval: 5 # Ticks between particle updates
density: 0.5 # Distance between particles (blocks)
visualization-duration: 30 # Duration in seconds

# Cooldown System
cooldowns:
enabled: true
default-cooldown: 3 # Cooldown in seconds

# Selection Tool
selection-tool:
material: WOODEN_HOE
name: “&6Selection Tool”
lore:
– “&7Left-click: Set position 1”
– “&7Right-click: Set position 2”
“`

### Changing Language

Edit `config.yml` and change the language setting:
“`yaml
language:
default: de # Change to your preferred language code
“`

Then reload: `/trigger reload`

## Commands

### Basic Commands

| Command | Description | Permission |
|———|————-|————|
| `/trigger tool` | Get the selection tool | `triggervolumes.admin` |
| `/trigger create ` | Create volume from selection | `triggervolumes.admin` |
| `/trigger define ` | Create volume with coordinates | `triggervolumes.admin` |
| `/trigger delete ` | Delete a volume | `triggervolumes.admin` |
| `/trigger clone [source] [name]` | Clone volume or create from selection | `triggervolumes.admin` |
| `/trigger copypaste ` | Copy actions between volumes | `triggervolumes.admin` |
| `/trigger list` | List all volumes | `triggervolumes.admin` |
| `/trigger info ` | Show volume details and groups | `triggervolumes.admin` |
| `/trigger reload` | Reload configurations | `triggervolumes.admin` |
| `/trigger help` | Show help message | `triggervolumes.admin` |

### Action Commands

| Command | Description | Permission |
|———|————-|————|
| `/trigger setaction enter ` | Add enter action | `triggervolumes.admin` |
| `/trigger setaction leave ` | Add leave action | `triggervolumes.admin` |
| `/trigger clearactions [enter|leave|all]` | Clear actions | `triggervolumes.admin` |

### Volume Groups Commands

| Command | Description | Permission |
|———|————-|————|
| `/trigger creategroup […]` | Create volume group (min 2) | `triggervolumes.admin` |
| `/trigger deletegroup ` | Delete group (volumes remain) | `triggervolumes.admin` |
| `/trigger groupadd ` | Add volume to existing group | `triggervolumes.admin` |
| `/trigger groupremove ` | Remove volume from group | `triggervolumes.admin` |
| `/trigger setaction ` | Apply action to all volumes in group | `triggervolumes.admin` |
| `/trigger clearactions [enter|leave|all]` | Clear actions from group | `triggervolumes.admin` |

### Visualization Commands

| Command | Description | Permission |
|———|————-|————|
| `/trigger visualize ` | Show volume particles (30s) | `triggervolumes.admin` |
| `/trigger hide ` | Stop showing particles | `triggervolumes.admin` |

## Action Types

### PLAYER_COMMAND
Executes a command as if the player typed it.

**Examples:**
“`
/trigger setaction MyVolume enter PLAYER_COMMAND /heal
/trigger setaction MyVolume enter PLAYER_COMMAND /spawn
/trigger setaction MyVolume leave PLAYER_COMMAND /back
“`

**Note:** The player must have permission to execute the command!

### CONSOLE_COMMAND
Executes a command from the console (with OP privileges).

**Examples:**
“`
/trigger setaction MyVolume enter CONSOLE_COMMAND give %player% diamond 1
/trigger setaction MyVolume enter CONSOLE_COMMAND effect give %player% speed 30 1
/trigger setaction MyVolume leave CONSOLE_COMMAND clear %player%
“`

**Placeholders:**
– `%player%` – Player’s name
– `%uuid%` – Player’s UUID

### MESSAGE
Sends a colored message to the player.

**Examples:**
“`
/trigger setaction MyVolume enter MESSAGE &aWelcome to the safe zone!
/trigger setaction MyVolume enter MESSAGE &6You are now in the &cDanger Zone&6!
/trigger setaction MyVolume leave MESSAGE &7You left the protected area.
“`

**Color Codes:**
– `&0-9, a-f` – Standard Minecraft colors
– `&l` – Bold, `&o` – Italic, `&n` – Underline
– `&m` – Strikethrough, `&k` – Obfuscated
– `&r` – Reset formatting

### TELEPORT
Teleports the player to specified coordinates.

**Format:** `x y z [yaw] [pitch]`

**Examples:**
“`
/trigger setaction MyVolume enter TELEPORT 100 64 200
/trigger setaction MyVolume enter TELEPORT 0 70 0 90 0
/trigger setaction MyVolume leave TELEPORT -50 65 -50 180 45
“`

**Note:** Teleport coordinates are in the same world as the volume!

## Usage Workflow

### 1. Creating a Volume

#### Method A: Using the Selection Tool
“`bash
# Get the selection tool
/trigger tool

# Select two corners by clicking blocks
# Left-click for position 1
# Right-click for position 2

# Create the volume
/trigger create MyFirstVolume
“`

#### Method B: Using Coordinates
“`bash
# Define volume with exact coordinates
/trigger define MyFirstVolume 100 60 100 150 80 150
“`

### 2. Adding Actions

#### Enter Actions (triggered on entering)
“`bash
# Send a welcome message
/trigger setaction MyFirstVolume enter MESSAGE &aWelcome!

# Give the player an item
/trigger setaction MyFirstVolume enter CONSOLE_COMMAND give %player% diamond 1

# Apply a potion effect
/trigger setaction MyFirstVolume enter CONSOLE_COMMAND effect give %player% speed 30 1
“`

#### Leave Actions (triggered on leaving)
“`bash
# Send a goodbye message
/trigger setaction MyFirstVolume leave MESSAGE &cGoodbye!

# Remove potion effects
/trigger setaction MyFirstVolume leave CONSOLE_COMMAND effect clear %player%

# Teleport player back
/trigger setaction MyFirstVolume leave TELEPORT 0 64 0
“`

### 3. Testing and Visualization

“`bash
# Visualize the volume with particles
/trigger visualize MyFirstVolume

# Walk into the volume – enter actions will execute
# Walk out of the volume – leave actions will execute

# Stop visualization
/trigger hide MyFirstVolume
“`

### 4. Managing Volumes

“`bash
# View all volumes
/trigger list

# Check volume details
/trigger info MyFirstVolume

# Clear specific actions
/trigger clearactions MyFirstVolume enter # Clear only enter actions
/trigger clearactions MyFirstVolume leave # Clear only leave actions
/trigger clearactions MyFirstVolume all # Clear all actions

# Delete volume
/trigger delete MyFirstVolume
“`

## Practical Examples

### Example 1: Safe Zone
Create a safe zone that heals players and prevents PvP:

“`bash
/trigger create SafeZone
/trigger setaction SafeZone enter MESSAGE &a&lYou entered a safe zone!
/trigger setaction SafeZone enter CONSOLE_COMMAND effect give %player% regeneration 999999 1 true
/trigger setaction SafeZone enter CONSOLE_COMMAND effect give %player% resistance 999999 4 true
/trigger setaction SafeZone leave MESSAGE &cYou left the safe zone!
/trigger setaction SafeZone leave CONSOLE_COMMAND effect clear %player%
“`

### Example 2: Shop Entrance
Display information when entering a shop:

“`bash
/trigger create ShopEntrance
/trigger setaction ShopEntrance enter MESSAGE &6&l=== SHOP ===
/trigger setaction ShopEntrance enter MESSAGE &eWelcome to the market!
/trigger setaction ShopEntrance enter MESSAGE &7Type /shop to browse items
/trigger setaction ShopEntrance enter PLAYER_COMMAND /shop
“`

### Example 3: Danger Zone
Warn players entering a dangerous area:

“`bash
/trigger create DangerZone
/trigger setaction DangerZone enter MESSAGE &c&l⚠ WARNING ⚠
/trigger setaction DangerZone enter MESSAGE &cYou entered a dangerous area!
/trigger setaction DangerZone enter MESSAGE &cProceed with caution!
/trigger setaction DangerZone enter CONSOLE_COMMAND playsound entity.ender_dragon.growl player %player%
/trigger setaction DangerZone leave MESSAGE &aYou are now safe.
“`

### Example 4: Teleport Hub
Create a portal that teleports players:

“`bash
/trigger create TeleportHub
/trigger setaction TeleportHub enter MESSAGE &6Teleporting to spawn…
/trigger setaction TeleportHub enter TELEPORT 0 64 0 0 0
“`

### Example 5: Resource Zone
Give players items when entering a mining area:

“`bash
/trigger create MiningZone
/trigger setaction MiningZone enter MESSAGE &6You received mining equipment!
/trigger setaction MiningZone enter CONSOLE_COMMAND give %player% iron_pickaxe 1
/trigger setaction MiningZone enter CONSOLE_COMMAND give %player% torch 16
/trigger setaction MiningZone leave MESSAGE &7Your mining equipment was removed.
/trigger setaction MiningZone leave CONSOLE_COMMAND clear %player% iron_pickaxe
/trigger setaction MiningZone leave CONSOLE_COMMAND clear %player% torch
“`

### Example 6: Cloning Volumes
Clone a volume’s actions to a new area:

“`bash
# Select new area with the tool
/trigger tool
# Left-click and right-click to select

# Clone an existing volume to the new selection
/trigger clone SafeZone MySafeZone2
# This creates MySafeZone2 with all actions from SafeZone

# Or create a volume without actions
/trigger clone
# Creates volume_1, volume_2, etc.

# Or clone with auto-generated name
/trigger clone SafeZone
# Creates SafeZone_clone, SafeZone_clone1, etc.
“`

### Example 7: Copying Actions Between Volumes
Copy actions from one volume to another without selection:

“`bash
# Copy all actions from DangerZone to AnotherDangerZone
/trigger copypaste DangerZone AnotherDangerZone
# Both enter and leave actions are copied
“`

### Example 8: Volume Groups
Manage multiple volumes as a group:

“`bash
# Create a group of shop volumes
/trigger creategroup AllShops Shop1 Shop2 Shop3

# Add more volumes to the group later
/trigger groupadd AllShops Shop4
/trigger groupadd AllShops Shop5

# Apply actions to all volumes in the group at once
/trigger setaction AllShops enter MESSAGE &6Welcome to the shop!
/trigger setaction AllShops enter CONSOLE_COMMAND effect give %player% glowing 10
/trigger setaction AllShops leave MESSAGE &7Thanks for visiting!

# Remove a volume from the group
/trigger groupremove AllShops Shop1

# Clear actions from all volumes in group
/trigger clearactions AllShops all

# Delete the group (volumes remain intact)
/trigger deletegroup AllShops
# Note: If a group has less than 2 volumes after removal, it’s automatically deleted
“`

## Permissions

### Admin Permissions
– `triggervolumes.admin` – Access to all commands (default: OP)
– Create, delete, and manage volumes
– Set and clear actions
– Visualize volumes
– Reload configuration

### User Permissions
– `triggervolumes.use` – Trigger actions when entering/leaving volumes (default: all players)

### Permission Examples

**Using LuckPerms:**
“`bash
# Give admin permission to specific player
/lp user PlayerName permission set triggervolumes.admin true

# Give admin permission to a group
/lp group admin permission set triggervolumes.admin true

# Remove trigger permission from guest group
/lp group guest permission set triggervolumes.use false
“`

**Using PermissionsEx:**
“`bash
# Give admin permission
/pex user PlayerName add triggervolumes.admin

# Give to group
/pex group admin add triggervolumes.admin
“`

## Cooldown System

The cooldown system prevents actions from being triggered too frequently when players repeatedly enter/exit volumes.

### How it Works
– **Separate Cooldowns**: Enter and leave actions have independent cooldowns
– **Per-Volume**: Each volume has its own cooldown timer per player
– **Configurable**: Default cooldown time can be set in `config.yml`

### Configuration
“`yaml
cooldowns:
enabled: true # Enable/disable cooldown system
default-cooldown: 3 # Cooldown duration in seconds
“`

### Behavior
– When a player triggers an action, they cannot trigger the same action type (enter/leave) for that volume again until the cooldown expires
– Cooldowns are cleared when players leave the server
– This prevents spam from players walking back and forth across volume boundaries

## Particle Visualization

Volumes can be visualized with colored particle effects to help with positioning and verification.

### Colors
– **Green** (VILLAGER_HAPPY): Volumes with actions
– **Red** (REDSTONE): Volumes without actions
– **Blue** (WATER_SPLASH): Currently being visualized

### Settings
“`yaml
particles:
update-interval: 5 # Ticks between updates (20 ticks = 1 second)
density: 0.5 # Block spacing between particles
visualization-duration: 30 # Auto-hide after X seconds
“`

### Usage
“`bash
# Show particles for 30 seconds
/trigger visualize MyVolume

# Stop showing particles
/trigger hide MyVolume
“`

## Performance Optimization

The plugin uses **spatial hashing** to efficiently handle hundreds or thousands of volumes without performance impact.

### How It Works
– The world is divided into 16×16 block chunks (Minecraft’s standard chunk size)
– Each volume is registered in all chunks it overlaps
– When checking if a player is in a volume, only volumes in the current chunk are checked

### Performance Comparison
| Number of Volumes | Without Optimization | With Spatial Hashing | Speedup |
|——————-|———————|———————|———-|
| 10 volumes | 10 checks | 2-3 checks | 3-5× faster |
| 100 volumes | 100 checks | 5-8 checks | 12-20× faster |
| 1000 volumes | 1000 checks | 5-10 checks | 100-200× faster |

### Benefits
– **Scalable**: Handles thousands of volumes without lag
– **Efficient**: O(k) instead of O(n) where k = volumes per chunk
– **Automatic**: No configuration needed, works out of the box
– **Real-time**: Updates instantly when volumes are created/deleted

### Best Practices
– No special configuration required
– Works best when volumes don’t span too many chunks
– Automatically rebuilds spatial index when needed

## File Structure

“`
plugins/TriggerVolumes/
├── config.yml # Main configuration
├── triggervolumes.yml # Stored volumes and actions
└── lang/ # Language files
├── en.yml # English (default)
├── de.yml # German
├── fr.yml # French
├── pl.yml # Polish
├── ru.yml # Russian
├── ja.yml # Japanese
└── es.yml # Spanish
“`

## Volume Groups

Volume groups allow you to manage multiple volumes as a single unit, making it easy to apply the same actions to multiple areas.

### Creating Groups
“`bash
# Create a group with at least 2 volumes
/trigger creategroup MyGroup Volume1 Volume2 Volume3
“`

### Using Groups
Groups can be used wherever you would use a volume name:

“`bash
# Apply actions to all volumes in a group
/trigger setaction MyGroup enter MESSAGE &aWelcome!
/trigger setaction MyGroup leave MESSAGE &cGoodbye!

# Clear actions from all volumes in a group
/trigger clearactions MyGroup enter
/trigger clearactions MyGroup all
“`

### Managing Groups
“`bash
# Add a volume to an existing group
/trigger groupadd MyGroup NewVolume

# Remove a volume from a group
/trigger groupremove MyGroup OldVolume

# View which groups a volume belongs to
/trigger info Volume1
# Shows: “Groups: MyGroup, AnotherGroup”

# Delete a group (volumes are not deleted)
/trigger deletegroup MyGroup
“`

**Important Notes:**
– Groups require a minimum of 2 volumes
– When removing a volume leaves less than 2 volumes, the group is automatically deleted
– A volume can belong to multiple groups simultaneously
– Removing a volume from a group doesn’t delete the volume itself

### Key Features
– **Batch Operations**: Apply actions to multiple volumes simultaneously
– **Independent Volumes**: Deleting a group doesn’t delete the volumes
– **Multiple Membership**: A volume can belong to multiple groups
– **Persistent**: Groups are saved and loaded with the plugin

## Storage Format

Volumes and groups are stored in `triggervolumes.yml`:

“`yaml
volumes:
MyVolume:
world: world
minX: 100.0
minY: 60.0
minZ: 100.0
maxX: 150.0
maxY: 80.0
maxZ: 150.0
enterActions:
0:
type: MESSAGE
value: “&aWelcome!”
1:
type: CONSOLE_COMMAND
value: “effect give %player% speed 30 1”
leaveActions:
0:
type: MESSAGE
value: “&cGoodbye!”
groups:
MyGroup:
name: MyGroup
volumes:
– Volume1
– Volume2
– Volume3
“`

## Troubleshooting

### Actions Not Triggering

**Problem:** Player walks through volume but nothing happens

**Solutions:**
1. Check permissions: Player needs `triggervolumes.use`
2. Verify actions exist: `/trigger info `
3. Check cooldown: Actions have a 3-second cooldown by default
4. Visualize volume: `/trigger visualize ` to verify boundaries
5. Check console for errors

### Selection Tool Not Working

**Problem:** Clicks don’t register positions

**Solutions:**
1. Ensure you have the correct tool (default: Wooden Hoe)
2. Check you have `triggervolumes.admin` permission
3. Try getting a new tool: `/trigger tool`
4. Verify you’re clicking blocks, not air

### Particles Not Showing

**Problem:** `/trigger visualize` doesn’t show particles

**Solutions:**
1. Check your particle settings in client (Options > Video Settings > Particles)
2. Verify the volume exists: `/trigger info `
3. Try standing closer to the volume
4. Check if another volume is being visualized (only one at a time)

### Commands Not Working

**Problem:** Commands return errors or don’t work

**Solutions:**
1. Check permission: `triggervolumes.admin` for setup commands
2. Verify volume name is correct (case-insensitive)
3. Use quotes for values with spaces: `/trigger setaction MyVolume enter MESSAGE “Hello World”`
4. Check console for detailed error messages

### Performance Issues

**Problem:** Server lag with many volumes

**Solutions:**
1. The plugin uses spatial hashing (v1.0.3+) which handles thousands of volumes efficiently
2. Reduce particle density in `config.yml`
3. Increase particle update interval
4. Disable visualization when not needed
5. Increase cooldown times
6. Note: Performance issues with volumes are rare due to optimization

## Advanced Tips

### Using Placeholders
All actions support these placeholders:
– `%player%` – Player’s name
– `%uuid%` – Player’s UUID

Example:
“`bash
/trigger setaction Welcome enter CONSOLE_COMMAND tellraw @a {“text”:”Player %player% entered spawn!”,”color”:”gold”}
“`

### Multiple Actions
Volumes support unlimited actions per trigger type:
“`bash
/trigger setaction MyVolume enter MESSAGE &aWelcome!
/trigger setaction MyVolume enter MESSAGE &eEnjoy your stay!
/trigger setaction MyVolume enter CONSOLE_COMMAND give %player% diamond 1
/trigger setaction MyVolume enter PLAYER_COMMAND /heal
“`

All actions execute in the order they were added.

### Overlapping Volumes
Players can be in multiple volumes simultaneously. Each volume’s actions will trigger independently when the player enters/leaves.

### World-Specific Volumes
Volumes are world-specific. A volume in “world” won’t trigger for players in “world_nether”.

### Volume Groups for Organization
Use groups to organize related volumes:
“`bash
# Group all spawn protection zones
/trigger creategroup SpawnZones SpawnSafe1 SpawnSafe2 SpawnSafe3

# Group all shop areas
/trigger creategroup Shops MainShop ArmorShop FoodShop

# Apply consistent actions across related areas
/trigger setaction SpawnZones enter MESSAGE &aYou are now in spawn!
“`

### Dynamic Group Management
Groups can be modified after creation:
“`bash
# Create initial group
/trigger creategroup ActiveShops Shop1 Shop2

# Add new shops as they’re built
/trigger groupadd ActiveShops Shop3
/trigger groupadd ActiveShops Shop4

# Remove shops temporarily (e.g., during renovation)
/trigger groupremove ActiveShops Shop2

# Add them back when ready
/trigger groupadd ActiveShops Shop2

# If you remove volumes until less than 2 remain, the group auto-deletes
/trigger groupremove ActiveShops Shop1 # Group still exists (3 volumes)
/trigger groupremove ActiveShops Shop3 # Group still exists (2 volumes)
/trigger groupremove ActiveShops Shop4 # Group auto-deleted (would have 1 volume)
“`

### Clone vs CopyPaste
– **Clone**: Creates a new volume from your selection + copies actions
– Requires selection with tool
– Creates new volume
– Optional: specify source and custom name

– **CopyPaste**: Copies actions between existing volumes
– No selection needed
– Works with existing volumes only
– Faster for duplicating actions

### Backup and Migration
Simply copy the `triggervolumes.yml` file to backup or transfer volumes to another server. Groups are also saved in this file.

## API for Developers

### Maven Dependency
“`xml

de.zfzfg
TriggerVolumes
1.0.4
provided

“`

### Getting the Plugin Instance
“`java
TriggerVolumesPlugin plugin = (TriggerVolumesPlugin) Bukkit.getPluginManager().getPlugin(“TriggerVolumes”);
“`

### Checking if a Location is in a Volume
“`java
TriggerVolumeManager manager = plugin.getVolumeManager();
List volumes = manager.getVolumesAtLocation(location);

if (!volumes.isEmpty()) {
// Location is in at least one volume
}
“`

### Creating a Volume Programmatically
“`java
TriggerVolumeManager manager = plugin.getVolumeManager();
manager.createVolume(“MyVolume”, “world”, 0, 60, 0, 100, 80, 100);

// Add actions
TriggerAction action = new TriggerAction(ActionType.MESSAGE, “&aHello!”);
manager.addEnterAction(“MyVolume”, action);
“`

## Support & Contributing

### Getting Help
– Check this documentation first
– Look for errors in console logs
– Ask in the Spigot forums
– Open an issue on GitHub

### Reporting Bugs
When reporting bugs, please include:
1. Server version (Spigot/Paper)
2. Plugin version
3. Full error message from console
4. Steps to reproduce the issue
5. Relevant configuration files

### Feature Requests
Have an idea? Open an issue on GitHub with:
– Clear description of the feature
– Use case / why it’s needed
– Example of how it would work

## License

This plugin is provided as-is for private and public Minecraft servers.

## Credits

– **Author**: zfzfg
– **Version**: 1.0.4
– **Built with**: Maven, Spigot API, Java 17

—

**Made by zfzfg**

For updates and more plugins, visit our GitHub Repository.