TriggerVolumes

插件

· 作者 zfzfg

一个用于定义 3D 触发区域的 Spigot/Paper 插件,支持在玩家进入和离开时自动执行操作!

0 本站下载 0 关注 更新于 11 个月前

最新 1.0.4 · 26.2 · Bukkit / Paper

一键开服(送7天)

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 或更高
  • 权限插件:可选(用于权限管理)

安装

  1. 下载 TriggerVolumes-1.0.4.jar
  2. 将文件放入服务端的 plugins/ 文件夹中
  3. 启动或重启您的服务器
  4. 配置文件将在 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

故障排除

动作未触发

问题: 玩家穿过体积区域但没有任何反应

解决方案:

  1. 检查权限:玩家需要 triggervolumes.use 权限
  2. 验证动作是否存在:使用 /trigger info <name>
  3. 检查冷却时间:默认情况下,动作具有 3 秒的冷却时间
  4. 可视化体积区域:使用 /trigger visualize <name> 验证边界
  5. 检查控制台是否有错误信息

选择工具无法工作

问题: 点击不记录位置

解决方案:

  1. 确保你拥有正确的工具(默认:木锄)
  2. 检查你是否拥有 triggervolumes.admin 权限
  3. 尝试获取新工具:使用 /trigger tool
  4. 验证你点击的是方块而非空气

粒子效果未显示

问题: 执行 /trigger visualize 后没有显示粒子效果

解决方案:

  1. 检查客户端中的粒子设置(选项 > 视频设置 > 粒子效果)
  2. 验证体积区域是否存在:使用 /trigger info <name>
  3. 尝试站得更靠近体积区域
  4. 检查是否正在可视化另一个体积区域(一次只能可视化一个)

命令无法工作

问题: 命令返回错误或无法运行

解决方案:

  1. 检查权限:配置命令需要 triggervolumes.admin 权限
  2. 验证体积名称是否正确(不区分大小写)
  3. 对于包含空格的值使用引号:/trigger setaction MyVolume enter MESSAGE "Hello World"
  4. 检查控制台以获取详细的错误消息

性能问题

问题: 大量体积区域导致服务器卡顿

解决方案:

  1. 插件使用空间哈希技术(v1.0.3+),能够高效处理数千个体积区域
  2. 在 config.yml 中降低粒子密度
  3. 增加粒子更新间隔
  4. 在不必要时禁用可视化功能
  5. 增加冷却时间
  6. 注意:由于优化措施,体积区域导致的性能问题非常罕见

高级技巧

使用占位符

所有动作都支持以下占位符:

  • %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

  • Clone(克隆):根据你的选择创建新体积区域 + 复制动作

    • 需要使用工具进行选择
    • 创建新的体积区域
    • 可选:指定源和自定义名称
  • 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

报告错误

报告错误时,请包含以下内容:

  1. 服务器版本(Spigot/Paper)
  2. 插件版本
  3. 控制台的完整错误信息
  4. 重现问题的步骤
  5. 相关的配置文件

功能请求

有想法?在 GitHub 上提交 Issue,并附上:

  • 清晰的功能描述
  • 使用场景 / 为什么需要此功能
  • 它如何工作的示例

许可证

本插件按“原样”提供,适用于私有和公共 Minecraft 服务器。

致谢

  • 作者: zfzfg
  • 版本: 1.0.4
  • 构建工具: Maven, Spigot API, Java 17

由 zfzfg 制作

如需更新及其他插件,请访问我们的 GitHub 仓库。

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源