TriggerVolumes 插件
一个功能强大的 Spigot/Paper 插件,用于创建 3D 触发体积,并支持自定义在玩家进入或离开定义区域时执行的操作。
功能
- 选择系统:基于工具选择立方体区域,并提供视觉反馈
- 触发体积:存储和管理带有精确坐标的命名体积
- 体积组:将多个体积组合在一起以进行批量操作
- 克隆与复制:克隆带有操作的体积,或在现有体积之间复制操作
- 进入/离开操作:当玩家进入或离开体积时执行不同的操作
- 操作类型:
PLAYER_COMMAND:以玩家身份执行命令
CONSOLE_COMMAND:从控制台执行命令
MESSAGE:向玩家发送彩色消息
TELEPORT:将玩家传送至特定坐标
- 粒子可视化:实时粒子效果显示体积边界
- 冷却系统:通过可配置的冷却时间防止操作滥用
- 空间哈希:针对拥有数百个体积的服务器的优化性能
- 多语言:支持 7 种语言(EN, DE, FR, PL, RU, JA, ES)
- 持久化存储:体积和操作以 YAML 格式保存
- 重载命令:无需重启服务器即可更新配置
要求
- 服务端:Spigot 或 Paper 1.19+
- Java:版本 17 或更高
- 权限插件:可选(用于权限管理)
安装
- 下载
TriggerVolumes-1.0.4.jar
- 将文件放入服务端的
plugins/ 文件夹中
- 启动或重启您的服务器
- 配置文件将在
plugins/TriggerVolumes/ 中自动生成
配置
主配置文件 (config.yml)
# 语言配置
language:
default: en # 可用选项:en, de, fr, pl, ru, ja, es
# 粒子设置
particles:
update-interval: 5 # 粒子更新之间的刻数
density: 0.5 # 粒子之间的距离(方块)
visualization-duration: 30 # 持续时间(秒)
# 冷却系统
cooldowns:
enabled: true
default-cooldown: 3 # 冷却时间(秒)
# 选择工具
selection-tool:
material: WOODEN_HOE
name: "&6Selection Tool"
lore:
- "&7左键点击:设置位置 1"
- "&7右键点击:设置位置 2"
更改语言
编辑 config.yml 并更改语言设置:
language:
default: de # 更改为您首选的语言代码
然后重载:/trigger reload
命令
基本命令
| 命令 |
描述 |
权限 |
/trigger tool |
获取选择工具 |
triggervolumes.admin |
/trigger create <name> |
从选择范围创建体积 |
triggervolumes.admin |
/trigger define <name> <x1> <y1> <z1> <x2> <y2> <z2> |
使用坐标创建体积 |
triggervolumes.admin |
/trigger delete <name> |
删除一个体积 |
triggervolumes.admin |
/trigger clone [source] [name] |
克隆体积或从选择范围创建 |
triggervolumes.admin |
/trigger copypaste <copy> <paste> |
在体积之间复制操作 |
triggervolumes.admin |
/trigger list |
列出所有体积 |
triggervolumes.admin |
/trigger info <name> |
显示体积详情和分组 |
triggervolumes.admin |
/trigger reload |
重载配置 |
triggervolumes.admin |
/trigger help |
显示帮助信息 |
triggervolumes.admin |
操作命令
| 命令 |
描述 |
权限 |
/trigger setaction <name> enter <type> <value> |
添加进入操作 |
triggervolumes.admin |
/trigger setaction <name> leave <type> <value> |
添加离开操作 |
triggervolumes.admin |
/trigger clearactions <name> [enter|leave|all] |
清除操作 |
triggervolumes.admin |
体积组命令
| 命令 |
描述 |
权限 |
/trigger creategroup <name> <vol1> <vol2> [...] |
创建体积组(至少 2 个) |
triggervolumes.admin |
/trigger deletegroup <name> |
删除组(体积保留) |
triggervolumes.admin |
/trigger groupadd <group> <volume> |
将体积添加到现有组 |
triggervolumes.admin |
/trigger groupremove <group> <volume> |
从组中移除体积 |
triggervolumes.admin |
/trigger setaction <group> <trigger> <type> <value> |
对组内所有体积应用操作 |
triggervolumes.admin |
/trigger clearactions <group> [enter|leave|all] |
清除组中的操作 |
triggervolumes.admin |
可视化命令
| 命令 |
描述 |
权限 |
/trigger visualize <name> |
显示体积粒子(30 秒) |
triggervolumes.admin |
/trigger hide <name> |
停止显示粒子 |
triggervolumes.admin |
操作类型
PLAYER_COMMAND
以玩家输入命令的方式执行命令。
示例:
/trigger setaction MyVolume enter PLAYER_COMMAND /heal
/trigger setaction MyVolume enter PLAYER_COMMAND /spawn
/trigger setaction MyVolume leave PLAYER_COMMAND /back
注意: 玩家必须拥有执行该命令的权限!
CONSOLE_COMMAND
从控制台执行命令(具有 OP 权限)。
示例:
/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%
占位符:
%player% - 玩家名称
%uuid% - 玩家的 UUID
MESSAGE
向玩家发送彩色消息。
示例:
/trigger setaction MyVolume enter MESSAGE &a欢迎来到安全区!
/trigger setaction MyVolume enter MESSAGE &6您现在处于 &c危险区域&6!
/trigger setaction MyVolume leave MESSAGE &7您已离开受保护区域。
颜色代码:
&0-9, a-f - 标准 Minecraft 颜色
&l - 加粗,&o - 斜体,&n - 下划线
&m - 删除线,&k - 随机乱码
&r - 重置格式
传送 (TELEPORT)
将玩家传送到指定的坐标。
格式: x y z [yaw] [pitch]
示例:
/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
注意: 传送坐标与体积所在的维度相同!
使用流程
1. 创建体积 (Volume)
方法 A:使用选择工具
# 获取选择工具
/trigger tool
# 通过点击方块选择两个角
# 左键点击作为位置 1
# 右键点击作为位置 2
# 创建体积
/trigger create MyFirstVolume
方法 B:使用坐标
# 使用精确坐标定义体积
/trigger define MyFirstVolume 100 60 100 150 80 150
2. 添加动作
进入动作(触发于进入时)
# 发送欢迎消息
/trigger setaction MyFirstVolume enter MESSAGE &aWelcome!
# 给予玩家物品
/trigger setaction MyFirstVolume enter CONSOLE_COMMAND give %player% diamond 1
# 应用药水效果
/trigger setaction MyFirstVolume enter CONSOLE_COMMAND effect give %player% speed 30 1
离开动作(触发于离开时)
# 发送告别消息
/trigger setaction MyFirstVolume leave MESSAGE &cGoodbye!
# 移除药水效果
/trigger setaction MyFirstVolume leave CONSOLE_COMMAND effect clear %player%
# 将玩家传送回原点
/trigger setaction MyFirstVolume leave TELEPORT 0 64 0
3. 测试与可视化
# 使用粒子效果可视化体积
/trigger visualize MyFirstVolume
# 走进体积 - 将执行进入动作
# 走出体积 - 将执行离开动作
# 停止可视化
/trigger hide MyFirstVolume
4. 管理体积
# 查看所有体积
/trigger list
# 检查体积详情
/trigger info MyFirstVolume
# 清除特定动作
/trigger clearactions MyFirstVolume enter # 仅清除进入动作
/trigger clearactions MyFirstVolume leave # 仅清除离开动作
/trigger clearactions MyFirstVolume all # 清除所有动作
# 删除体积
/trigger delete MyFirstVolume
实用示例
示例 1:安全区
创建一个能治疗玩家并防止 PvP 的安全区:
/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%
示例 2:商店入口
在进入商店时显示信息:
/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
示例 3:危险区域
警告玩家进入危险区域:
/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.
示例 4:传送枢纽
创建一个传送玩家的传送门:
/trigger create TeleportHub
/trigger setaction TeleportHub enter MESSAGE &6Teleporting to spawn...
/trigger setaction TeleportHub enter TELEPORT 0 64 0 0 0
示例 5:资源区
在进入采矿区域时给予玩家物品:
/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
示例 6:克隆体积
将体积的动作克隆到新区域:
# 使用工具选择新区域
/trigger tool
# 左键和右键点击进行选择
# 将现有体积克隆到新的选择区域
/trigger clone SafeZone MySafeZone2
# 这将创建一个名为 MySafeZone2 的体积,包含来自 SafeZone 的所有动作
# 或者创建一个没有动作的体积
/trigger clone
# 创建 volume_1, volume_2 等
# 或者使用自动生成的名称进行克隆
/trigger clone SafeZone
# 创建 SafeZone_clone, SafeZone_clone1 等
示例 7:在体积之间复制动作
无需选择即可将一个体积的动作复制到另一个体积:
# 将 DangerZone 的所有动作复制到 AnotherDangerZone
/trigger copypaste DangerZone AnotherDangerZone
# 进入和离开动作都会被复制
示例 8:体积组
将多个体积作为一组进行管理:
# 创建一个商店体积组
/trigger creategroup AllShops Shop1 Shop2 Shop3
# 稍后将更多体积添加到该组
/trigger groupadd AllShops Shop4
/trigger groupadd AllShops Shop5
# 一次性对组内的所有体积应用动作
/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!
# 从组中移除一个体积
/trigger groupremove AllShops Shop1
清除组内所有容积中的操作
/trigger clearactions AllShops all
删除该组(容积保持完整)
/trigger deletegroup AllShops
注意:如果移除后组内的容积少于 2 个,它将被自动删除
## 权限
### 管理员权限
- `triggervolumes.admin` - 访问所有命令(默认:OP)
- 创建、删除和管理容积
- 设置和清除操作
- 可视化容积
- 重载配置
### 用户权限
- `triggervolumes.use` - 进出容积时触发操作(默认:所有玩家)
### 权限示例
**使用 LuckPerms:**
```bash
# 为特定玩家授予管理员权限
/lp user PlayerName permission set triggervolumes.admin true
# 为群组授予管理员权限
/lp group admin permission set triggervolumes.admin true
# 从访客群组中移除触发权限
/lp group guest permission set triggervolumes.use false
使用 PermissionsEx:
# 授予管理员权限
/pex user PlayerName add triggervolumes.admin
# 授予给群组
/pex group admin add triggervolumes.admin
冷却系统
冷却系统防止玩家在反复进出容积时过于频繁地触发操作。
工作原理
- 独立冷却:进入和离开操作拥有独立的冷却时间
- 按容积计算:每个容积对每位玩家都有独立的冷却计时器
- 可配置:可以在
config.yml 中设置默认冷却时间
配置
cooldowns:
enabled: true # 启用/禁用冷却系统
default-cooldown: 3 # 冷却持续时间(秒)
行为
- 当玩家触发某项操作后,在该容积的冷却结束前,无法再次触发相同类型的操作(进入/离开)
- 玩家离开服务器时,冷却时间会被清除
- 这可以防止玩家在容积边界来回走动造成的刷屏行为
粒子可视化
容积可以通过彩色粒子效果进行可视化,以帮助定位和验证。
颜色
- 绿色 (VILLAGER_HAPPY):包含操作的容积
- 红色 (REDSTONE):不包含操作的容积
- 蓝色 (WATER_SPLASH):当前正在可视化的容积
设置
particles:
update-interval: 5 # 更新间隔(刻度),20 刻度 = 1 秒
density: 0.5 # 粒子之间的方块间距
visualization-duration: 30 # X 秒后自动隐藏
用法
# 显示粒子 30 秒
/trigger visualize MyVolume
# 停止显示粒子
/trigger hide MyVolume
性能优化
插件使用空间哈希技术,能够在不影响性能的情况下高效处理数百甚至数千个容积。
工作原理
- 世界被划分为 16×16 方块的区块(Minecraft 的标准区块大小)
- 每个容积都会被注册到与其重叠的所有区块中
- 在检查玩家是否位于容积内时,仅检查当前区块内的容积
性能对比
| 容积数量 |
无优化 |
使用空间哈希 |
加速比 |
| 10 个容积 |
10 次检查 |
2-3 次检查 |
快 3-5 倍 |
| 100 个容积 |
100 次检查 |
5-8 次检查 |
快 12-20 倍 |
| 1000 个容积 |
1000 次检查 |
5-10 次检查 |
快 100-200 倍 |
优势
- 可扩展:能够处理数千个容积而不会卡顿
- 高效:复杂度为 O(k) 而非 O(n),其中 k = 每区块内的容积数
- 自动化:无需配置,开箱即用
- 实时:容积创建/删除时即时更新
最佳实践
- 无需特殊配置
- 当容积不跨越过多区块时效果最佳
- 需要时会自动重建空间索引
文件结构
plugins/TriggerVolumes/
├── config.yml # 主配置文件
├── triggervolumes.yml # 存储的容积和操作
└── lang/ # 语言文件
├── en.yml # 英语(默认)
├── de.yml # 德语
├── fr.yml # 法语
├── pl.yml # 波兰语
├── ru.yml # 俄语
├── ja.yml # 日语
└── es.yml # 西班牙语
容积组
容积组允许您将多个容积作为一个单元进行管理,从而轻松地将相同的操作应用于多个区域。
创建组
# 创建至少包含 2 个容积的组
/trigger creategroup MyGroup Volume1 Volume2 Volume3
使用组
组可以在任何需要使用容积名称的地方使用:
# 将操作应用到组内的所有容积
/trigger setaction MyGroup enter MESSAGE &a欢迎!
/trigger setaction MyGroup leave MESSAGE &c再见!
# 清除组内所有容积的操作
/trigger clearactions MyGroup enter
/trigger clearactions MyGroup all
管理组
# 将容积添加到现有组
/trigger groupadd MyGroup NewVolume
# 从组中移除容积
/trigger groupremove MyGroup OldVolume
# 查看容积属于哪些组
/trigger info Volume1
# 显示:"Groups: MyGroup, AnotherGroup"
# 删除组(容积不会被删除)
/trigger deletegroup MyGroup
重要提示:
- 组至少需要 2 个容积
- 当移除容积导致组内容积少于 2 个时,该组将被自动删除
- 一个容积可以同时属于多个组
- 从组中移除容积并不会删除容积本身
主要功能
- 批量操作:同时向多个容积应用操作
- 独立容积:删除组不会删除其中的容积
- 多重归属:一个容积可以属于多个组
- 持久化:组会随着插件一起保存和加载
存储格式
容积和组存储在 triggervolumes.yml 中:
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
故障排除
动作未触发
问题: 玩家穿过体积区域但没有任何反应
解决方案:
- 检查权限:玩家需要
triggervolumes.use 权限
- 验证动作是否存在:使用
/trigger info <name>
- 检查冷却时间:默认情况下,动作具有 3 秒的冷却时间
- 可视化体积区域:使用
/trigger visualize <name> 验证边界
- 检查控制台是否有错误信息
选择工具无法工作
问题: 点击不记录位置
解决方案:
- 确保你拥有正确的工具(默认:木锄)
- 检查你是否拥有
triggervolumes.admin 权限
- 尝试获取新工具:使用
/trigger tool
- 验证你点击的是方块而非空气
粒子效果未显示
问题: 执行 /trigger visualize 后没有显示粒子效果
解决方案:
- 检查客户端中的粒子设置(选项 > 视频设置 > 粒子效果)
- 验证体积区域是否存在:使用
/trigger info <name>
- 尝试站得更靠近体积区域
- 检查是否正在可视化另一个体积区域(一次只能可视化一个)
命令无法工作
问题: 命令返回错误或无法运行
解决方案:
- 检查权限:配置命令需要
triggervolumes.admin 权限
- 验证体积名称是否正确(不区分大小写)
- 对于包含空格的值使用引号:
/trigger setaction MyVolume enter MESSAGE "Hello World"
- 检查控制台以获取详细的错误消息
性能问题
问题: 大量体积区域导致服务器卡顿
解决方案:
- 插件使用空间哈希技术(v1.0.3+),能够高效处理数千个体积区域
- 在
config.yml 中降低粒子密度
- 增加粒子更新间隔
- 在不必要时禁用可视化功能
- 增加冷却时间
- 注意:由于优化措施,体积区域导致的性能问题非常罕见
高级技巧
使用占位符
所有动作都支持以下占位符:
%player% - 玩家名称
%uuid% - 玩家 UUID
示例:
/trigger setaction Welcome enter CONSOLE_COMMAND tellraw @a {"text":"Player %player% entered spawn!","color":"gold"}
多个动作
每个触发类型支持无限数量的动作:
/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
所有动作将按照添加的顺序依次执行。
重叠的体积区域
玩家可以同时处于多个体积区域内。当玩家进入或离开时,每个体积区域的动作将独立触发。
世界特定的体积区域
体积区域是特定于世界的。位于 "world" 的体积区域不会对在 "world_nether" 中的玩家触发。
用于组织的体积区域组
使用组来组织相关的体积区域:
# 将所有出生点保护区域分组
/trigger creategroup SpawnZones SpawnSafe1 SpawnSafe2 SpawnSafe3
# 将所有商店区域分组
/trigger creategroup Shops MainShop ArmorShop FoodShop
# 对相关区域应用一致的动作
/trigger setaction SpawnZones enter MESSAGE &aYou are now in spawn!
动态组管理
创建组后可以对其进行修改:
# 创建初始组
/trigger creategroup ActiveShops Shop1 Shop2
# 随着新商店建成,将其添加到组中
/trigger groupadd ActiveShops Shop3
/trigger groupadd ActiveShops Shop4
# 暂时移除商店(例如,在装修期间)
/trigger groupremove ActiveShops Shop2
# 准备就绪时重新添加
/trigger groupadd ActiveShops Shop2
# 如果移除体积区域后剩余数量少于 2 个,该组将自动删除
/trigger groupremove ActiveShops Shop1 # 组仍然存在(3 个体积区域)
/trigger groupremove ActiveShops Shop3 # 组仍然存在(2 个体积区域)
/trigger groupremove ActiveShops Shop4 # 组自动删除(将只剩 1 个体积区域)
Clone vs CopyPaste
备份与迁移
只需复制 triggervolumes.yml 文件即可进行备份或将体积区域传输到其他服务器。组也保存在此文件中。
开发者 API
Maven 依赖
<dependency>
<groupId>de.zfzfg</groupId>
<artifactId>TriggerVolumes</artifactId>
<version>1.0.4</version>
<scope>provided</scope>
</dependency>
获取插件实例
TriggerVolumesPlugin plugin = (TriggerVolumesPlugin) Bukkit.getPluginManager().getPlugin("TriggerVolumes");
检查位置是否在体积区域内
TriggerVolumeManager manager = plugin.getVolumeManager();
List<TriggerVolume> volumes = manager.getVolumesAtLocation(location);
if (!volumes.isEmpty()) {
// 该位置至少在一个体积区域内
}
以编程方式创建体积区域
TriggerVolumeManager manager = plugin.getVolumeManager();
manager.createVolume("MyVolume", "world", 0, 60, 0, 100, 80, 100);
// 添加动作
TriggerAction action = new TriggerAction(ActionType.MESSAGE, "&aHello!");
manager.addEnterAction("MyVolume", action);
支持与贡献
获取帮助
- 首先查阅本文档
- 查看控制台日志中的错误
- 在 Spigot 论坛提问
- 在 GitHub 上提交 Issue
报告错误
报告错误时,请包含以下内容:
- 服务器版本(Spigot/Paper)
- 插件版本
- 控制台的完整错误信息
- 重现问题的步骤
- 相关的配置文件
功能请求
有想法?在 GitHub 上提交 Issue,并附上:
- 清晰的功能描述
- 使用场景 / 为什么需要此功能
- 它如何工作的示例
许可证
本插件按“原样”提供,适用于私有和公共 Minecraft 服务器。
致谢
- 作者: zfzfg
- 版本: 1.0.4
- 构建工具: Maven, Spigot API, Java 17
由 zfzfg 制作
如需更新及其他插件,请访问我们的 GitHub 仓库。
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
- Download
TriggerVolumes-1.0.4.jar
- Place the file in your server's
plugins/ folder
- Start or restart your server
- Configuration files will be generated automatically in
plugins/TriggerVolumes/
Configuration
Main Configuration (config.yml)
# 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:
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 <name> |
Create volume from selection |
triggervolumes.admin |
/trigger define <name> <x1> <y1> <z1> <x2> <y2> <z2> |
Create volume with coordinates |
triggervolumes.admin |
/trigger delete <name> |
Delete a volume |
triggervolumes.admin |
/trigger clone [source] [name] |
Clone volume or create from selection |
triggervolumes.admin |
/trigger copypaste <copy> <paste> |
Copy actions between volumes |
triggervolumes.admin |
/trigger list |
List all volumes |
triggervolumes.admin |
/trigger info <name> |
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 <name> enter <type> <value> |
Add enter action |
triggervolumes.admin |
/trigger setaction <name> leave <type> <value> |
Add leave action |
triggervolumes.admin |
/trigger clearactions <name> [enter|leave|all] |
Clear actions |
triggervolumes.admin |
Volume Groups Commands
| Command |
Description |
Permission |
/trigger creategroup <name> <vol1> <vol2> [...] |
Create volume group (min 2) |
triggervolumes.admin |
/trigger deletegroup <name> |
Delete group (volumes remain) |
triggervolumes.admin |
/trigger groupadd <group> <volume> |
Add volume to existing group |
triggervolumes.admin |
/trigger groupremove <group> <volume> |
Remove volume from group |
triggervolumes.admin |
/trigger setaction <group> <trigger> <type> <value> |
Apply action to all volumes in group |
triggervolumes.admin |
/trigger clearactions <group> [enter|leave|all] |
Clear actions from group |
triggervolumes.admin |
Visualization Commands
| Command |
Description |
Permission |
/trigger visualize <name> |
Show volume particles (30s) |
triggervolumes.admin |
/trigger hide <name> |
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
# 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
# Define volume with exact coordinates
/trigger define MyFirstVolume 100 60 100 150 80 150
2. Adding Actions
Enter Actions (triggered on entering)
# 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)
# 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
# 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
# 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:
/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:
/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:
/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:
/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:
/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:
# 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:
# 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:
# 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:
# 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:
# 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
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
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
# 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
# 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:
# 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
# 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:
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:
- Check permissions: Player needs
triggervolumes.use
- Verify actions exist:
/trigger info <name>
- Check cooldown: Actions have a 3-second cooldown by default
- Visualize volume:
/trigger visualize <name> to verify boundaries
- Check console for errors
Selection Tool Not Working
Problem: Clicks don't register positions
Solutions:
- Ensure you have the correct tool (default: Wooden Hoe)
- Check you have
triggervolumes.admin permission
- Try getting a new tool:
/trigger tool
- Verify you're clicking blocks, not air
Particles Not Showing
Problem: /trigger visualize doesn't show particles
Solutions:
- Check your particle settings in client (Options > Video Settings > Particles)
- Verify the volume exists:
/trigger info <name>
- Try standing closer to the volume
- Check if another volume is being visualized (only one at a time)
Commands Not Working
Problem: Commands return errors or don't work
Solutions:
- Check permission:
triggervolumes.admin for setup commands
- Verify volume name is correct (case-insensitive)
- Use quotes for values with spaces:
/trigger setaction MyVolume enter MESSAGE "Hello World"
- Check console for detailed error messages
Performance Issues
Problem: Server lag with many volumes
Solutions:
- The plugin uses spatial hashing (v1.0.3+) which handles thousands of volumes efficiently
- Reduce particle density in
config.yml
- Increase particle update interval
- Disable visualization when not needed
- Increase cooldown times
- 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:
/trigger setaction Welcome enter CONSOLE_COMMAND tellraw @a {"text":"Player %player% entered spawn!","color":"gold"}
Multiple Actions
Volumes support unlimited actions per trigger type:
/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:
# 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:
# 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
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
<dependency>
<groupId>de.zfzfg</groupId>
<artifactId>TriggerVolumes</artifactId>
<version>1.0.4</version>
<scope>provided</scope>
</dependency>
Getting the Plugin Instance
TriggerVolumesPlugin plugin = (TriggerVolumesPlugin) Bukkit.getPluginManager().getPlugin("TriggerVolumes");
Checking if a Location is in a Volume
TriggerVolumeManager manager = plugin.getVolumeManager();
List<TriggerVolume> volumes = manager.getVolumesAtLocation(location);
if (!volumes.isEmpty()) {
// Location is in at least one volume
}
Creating a Volume Programmatically
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:
- Server version (Spigot/Paper)
- Plugin version
- Full error message from console
- Steps to reproduce the issue
- 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.
评论 0
登录后参与评分
还没有评论,来抢沙发吧