原创 - 脚本 - XYScript —— 小雨牌脚本触发器

版权类型: 原创

插件中文名称: 小雨脚本

插件英文名称: XYScript

原帖地址: #

支持的核心（服务端）

Spigot
Paper
Purpur
Leaves

语言支持: 中文（简体）

前置组件: [可选]XYLogin https://www.minebbs.com/resources/xylogin.13974/

适配版本（Java）

1.21
1.20
1.19
1.18
1.17

XYScript
强大的 Minecraft 服务器脚本系统

插件简介

XYScript 是一款功能强大的 Minecraft 服务器脚本系统插件，让服务器管理员无需编程即可创建复杂的自动化脚本。

核心特性：
• 基于 YAML 的简单配置
• 支持多种游戏事件监听
• 强大的条件判断系统
• 灵活的命令执行机制
• 定时任务支持
• 异步 WEB API 支持
• HTTP POST 请求支持
• 完整的调试模式

通过简单的配置文件，即可实现复杂的服务器自动化功能和外部 API 联动！

核心特性

事件监听系统

玩家加入服务器 (join)
玩家退出服务器 (quit)
玩家登录账号 (login) - 需要 XYLogin 插件
玩家登出账号 (logout) - 需要 XYLogin 插件
玩家聊天消息 (chat)
定时执行任务 (tick)

条件判断系统

逻辑运算：AND（与）、OR（或）、NOT（非）
时间判断：时间段检测、特定日期、日期范围
玩家判断：权限、世界、游戏模式、生命值
变量判断：支持上下文变量比较
网络判断：WEB_JSON - 从 Web API 获取数据并判断
反向条件：支持 ! 前缀反转条件结果

命令执行系统

[console] - 控制台执行命令
[player] - 玩家执行命令
[message] - 向玩家发送消息
[broadcast] - 全服广播消息
[http_post] - 发送 HTTP POST 请求到外部 API
玩家变量：%player%、%player_uuid%

指令与权限

管理员命令

命令	权限	说明
/xyscript help	xyscript.admin	显示帮助信息
/xyscript reload	xyscript.admin	重载所有脚本
/xyscript list	xyscript.admin	查看已加载的脚本列表
/xyscript info <脚本名>	xyscript.admin	查看脚本详细信息
/xyscript debug <on\|off>	xyscript.admin	开启/关闭调试模式

配置文件详解

config.yml - 主配置

YAML：

# 调试模式 - 在控制台输出详细的执行日志
# true = 开启调试  false = 关闭调试
debug: false

脚本文件结构

YAML：

# 脚本是否启用
enabled: true

# 脚本描述
description: "这是一个示例脚本"

# 监听器配置
listeners:
  # 事件类型（join/quit/login/logout/chat/tick）
  join:
    # 条件判断（可选）
    condition:
      type: "条件类型"
      # 其他条件参数...
   
    # 条件满足时执行的命令
    success_commands:
      - "[message] &a欢迎来到服务器！"
      - "[console] give %player% diamond 1"
   
    # 条件不满足时执行的命令（可选）
    failure_commands:
      - "[message] &c你不满足条件"

条件类型详解

1. 逻辑运算 - AND（所有条件都满足）

YAML：

condition:
  type: AND
  conditions:
    - type: TIME
      start: "08:00"
      end: "18:00"
    - type: PERMISSION
      permission: "vip.join"

2. 逻辑运算 - OR（任一条件满足）

YAML：

condition:
  type: OR
  conditions:
    - type: PERMISSION
      permission: "vip.level1"
    - type: PERMISSION
      permission: "vip.level2"

3. 逻辑运算 - NOT（条件取反）

YAML：

condition:
  type: NOT
  condition:
    type: PERMISSION
    permission: "banned.group"

4. 时间判断 - TIME（时间段检测）

YAML：

condition:
  type: TIME
  start: "08:00"  # 开始时间（24小时制）
  end: "18:00"    # 结束时间
# 支持跨越午夜：start: "22:00", end: "06:00"

5. 日期判断 - DATE（特定日期）

YAML：

condition:
  type: DATE
  date: "2025-12-25"  # 格式：yyyy-MM-dd

6. 权限判断 - PERMISSION

YAML：

condition:
  type: PERMISSION
  permission: "vip.join"  # 权限节点

7. 世界判断 - WORLD

YAML：

condition:
  type: WORLD
  world: "world_nether"  # 世界名称

8. 网络判断 - WEB_JSON（从 API 获取数据）

YAML：

condition:
  type: WEB_JSON
  url: "https://api.example.com/player/%player%"  # API 地址
  path: "data.status"                              # JSON 路径
  value: "active"                                  # 期望值
  compare: "equals"  # 可选，默认 equals
  # compare 支持：equals, not_equals, contains, starts_with, ends_with
  #              greater_than, less_than, greater_or_equal, less_or_equal

9. 反向条件（使用 ! 前缀）

YAML：

condition:
  type: "!PERMISSION"  # 不拥有权限时满足
  permission: "banned.group"

命令格式说明

1. 控制台命令

YAML：

success_commands:
  - "[console] give %player% diamond 1"
  - "[console] tp %player% 0 100 0"

2. 玩家命令

YAML：

success_commands:
  - "[player] spawn"
  - "[player] help"

3. 发送消息

YAML：

success_commands:
  - "[message] &a欢迎 %player% 来到服务器！"
  - "[message] &e你的UUID：%player_uuid%"

4. 全服广播

YAML：

success_commands:
  - "[broadcast] &6玩家 %player% 获得了钻石！"

5. HTTP POST 请求

YAML：

success_commands:
  - '[http_post] https://api.example.com/webhook {"player":"%player%","event":"login"}'
  # 格式：[http_post] <URL> <JSON数据>

6. 默认命令（控制台执行）

YAML：

success_commands:
  - "give %player% iron_ingot 10"  # 不加前缀默认为控制台命令

可用占位符：
• %player% - 玩家名称
• %player_uuid% - 玩家UUID
• %变量名% - 上下文变量（如聊天事件中的 %message%）

Tick 定时任务

YAML：

listeners:
  tick:
    # 执行间隔（单位：tick，20 tick = 1 秒）
    interval: 100  # 每 5 秒执行一次
   
    # 条件判断
    condition:
      type: TIME
      start: "12:00"
      end: "13:00"
   
    # 执行命令
    success_commands:
      - "[broadcast] &e现在是午餐时间！"
      - "[console] effect give @a minecraft:regeneration 10 1"

常用间隔值：
• 20 ticks = 1 秒
• 100 ticks = 5 秒
• 200 ticks = 10 秒
• 1200 ticks = 1 分钟
• 6000 ticks = 5 分钟

配置示例

示例 1：VIP 玩家欢迎系统

YAML：

enabled: true
description: "VIP 玩家在白天加入时获得欢迎礼包"

listeners:
  join:
    condition:
      type: AND
      conditions:
        - type: TIME
          start: "08:00"
          end: "18:00"
        - type: PERMISSION
          permission: "vip.join"
   
    success_commands:
      - "[message] &a&l欢迎 VIP 玩家 %player%！"
      - "[message] &e这是您的每日礼包！"
      - "[console] give %player% diamond 5"
      - "[console] give %player% golden_apple 3"
      - "[broadcast] &6VIP 玩家 &b%player% &6加入了服务器！"
   
    failure_commands:
      - "[message] &7欢迎 %player% 加入服务器！"

示例 2：在线白名单验证（Web API）

YAML：

enabled: true
description: "通过外部 API 验证玩家是否在白名单中"

listeners:
  login:
    condition:
      type: WEB_JSON
      url: "https://api.yourserver.com/whitelist/check?player=%player%"
      path: "data.allowed"
      value: true
      compare: "equals"
   
    success_commands:
      - "[message] &a白名单验证通过！欢迎 %player%！"
      - '[http_post] https://api.yourserver.com/log {"player":"%player%","action":"login_success","time":"2025-12-29"}'
   
    failure_commands:
      - "[message] &c你不在白名单中！"
      - "[console] kick %player% 白名单验证失败"
      - '[http_post] https://api.yourserver.com/log {"player":"%player%","action":"login_failed"}'

示例 3：Discord Webhook 通知

YAML：

enabled: true
description: "玩家加入时发送 Discord 通知"

listeners:
  join:
    success_commands:
      - "[message] &a欢迎 %player% 加入服务器！"
      - '[http_post] https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_TOKEN {"content":"玩家 **%player%** 加入了服务器！","username":"服务器机器人"}'

示例 4：玩家签到系统（API 联动）

YAML：

enabled: true
description: "玩家登录时检查是否已签到，未签到则发放奖励"

listeners:
  login:
    condition:
      type: WEB_JSON
      url: "https://api.yourserver.com/checkin/status?player=%player_uuid%&date=2025-12-29"
      path: "data.checked_in"
      value: false
      compare: "equals"
   
    success_commands:
      - "[message] &a每日签到成功！"
      - "[message] &e获得奖励：钻石 x3"
      - "[console] give %player% diamond 3"
      - '[http_post] https://api.yourserver.com/checkin/record {"uuid":"%player_uuid%","player":"%player%","date":"2025-12-29"}'
   
    failure_commands:
      - "[message] &7你今天已经签到过了！"

示例 5：圣诞节特别活动

YAML：

enabled: true
description: "圣诞节期间的特殊欢迎"

listeners:
  join:
    condition:
      type: DATE
      date: "2025-12-25"
   
    success_commands:
      - "[message] &c&l🎄 圣诞快乐！%player% 🎄"
      - "[message] &a这是圣诞老人送给你的礼物！"
      - "[console] give %player% minecraft:diamond 10"
      - "[console] give %player% minecraft:cake 5"
      - "[console] title %player% title {\"text\":\"圣诞快乐！\",\"color\":\"red\"}"
      - "[broadcast] &c%player% 收到了圣诞礼物！"

示例 6：定时全服提醒

YAML：

enabled: true
description: "每小时整点提醒玩家备份物品"

listeners:
  tick:
    interval: 72000  # 1小时 = 72000 ticks
   
    success_commands:
      - "[broadcast] &e&l⚠ 提醒：请定期将重要物品存入箱子！"
      - "[broadcast] &7服务器可能随时重启，请做好准备。"
      - "[console] playsound minecraft:block.note_block.bell master @a ~ ~ ~ 1 1"

示例 7：VIP 等级检测（API）

YAML：

enabled: true
description: "根据外部 API 返回的 VIP 等级发放不同奖励"

listeners:
  login:
    condition:
      type: WEB_JSON
      url: "https://api.yourserver.com/vip/level?uuid=%player_uuid%"
      path: "data.level"
      value: 3
      compare: "greater_or_equal"  # 等级 >= 3
   
    success_commands:
      - "[message] &6&l尊贵的高级VIP %player%！"
      - "[message] &e您的等级：高级VIP"
      - "[console] give %player% diamond 10"
      - "[console] give %player% golden_apple 5"
   
    failure_commands:
      - "[message] &a欢迎 %player%！"
      - "[console] give %player% iron_ingot 5"

示例 8：聊天关键词触发

YAML：

enabled: true
description: "玩家说出关键词时触发奖励"

listeners:
  chat:
    condition:
      type: VARIABLE
      name: "message"
      operator: "=="
      value: "我爱这个服务器"
   
    success_commands:
      - "[message] &a&l感谢你的支持！这是给你的奖励！"
      - "[console] give %player% diamond 3"
      - "[broadcast] &e%player% &a说：我爱这个服务器！"

WEB_JSON 条件详解

什么是 WEB_JSON？
WEB_JSON 允许你从外部 Web API 获取 JSON 数据，并根据返回的数据判断条件。这让你的服务器可以与外部系统（网站、数据库、其他服务）进行联动。

基础配置

YAML：

condition:
  type: WEB_JSON
  url: "https://api.example.com/endpoint"  # API 地址
  path: "data.status"                      # JSON 数据路径
  value: "active"                          # 期望的值
  compare: "equals"                        # 比较方式（可选）

支持的比较方式（compare）

equals - 相等（默认）
not_equals - 不相等
contains - 包含
starts_with - 以...开头
ends_with - 以...结尾
greater_than - 大于（数字）
less_than - 小于（数字）
greater_or_equal - 大于等于（数字）
less_or_equal - 小于等于（数字）

JSON 路径说明
假设 API 返回以下 JSON：

JSON：

{
  "data": {
    "user": {
      "name": "Steve",
      "vip": true,
      "level": 5
    },
    "items": [
      {"id": 1, "name": "diamond"},
      {"id": 2, "name": "gold"}
    ]
  }
}

路径示例：

data.user.name → "Steve"
data.user.level → 5
data.items[0].name → "diamond"

使用场景举例

在线白名单 - 从你的网站获取白名单状态
VIP 验证 - 检查玩家是否购买了 VIP
签到系统 - 检查玩家今天是否已签到
等级限制 - 根据玩家在其他系统的等级决定权限
封禁检测 - 从中心服务器获取封禁状态
活动状态 - 检查服务器活动是否正在进行

性能优化

自动缓存 5 秒，相同请求不会重复访问
异步执行，不会阻塞服务器主线程
支持超时设置（5秒）
自动管理缓存大小（最多 100 条）

占位符支持
URL 中可以使用以下占位符：

%player% - 玩家名称
%player_uuid% - 玩家 UUID
其他上下文变量

示例：

YAML：

url: "https://api.example.com/check?player=%player%&uuid=%player_uuid%"

HTTP POST 命令详解

什么是 HTTP POST？
HTTP POST 命令允许你向外部 API 发送数据，实现服务器事件通知、数据同步等功能。

基础格式

YAML：

success_commands:
  - '[http_post] <URL> <JSON数据>'

简单示例

YAML：

success_commands:
  - '[http_post] https://api.example.com/log {"player":"%player%","action":"login"}'

使用场景举例

1. Discord Webhook 通知

YAML：

success_commands:
  - '[http_post] https://discord.com/api/webhooks/ID/TOKEN {"content":"玩家 %player% 上线了！"}'

2. 记录玩家行为

YAML：

success_commands:
  - '[http_post] https://api.yourserver.com/log {"uuid":"%player_uuid%","name":"%player%","event":"login","time":"2025-12-29"}'

3. 数据同步

YAML：

success_commands:
  - '[http_post] https://api.yourserver.com/sync {"player":"%player%","server":"survival","online":true}'

4. 积分系统

YAML：

success_commands:
  - '[http_post] https://api.yourserver.com/points/add {"uuid":"%player_uuid%","points":10,"reason":"daily_login"}'

5. 统计数据

YAML：

success_commands:
  - '[http_post] https://api.yourserver.com/stats {"player":"%player%","playtime":3600,"kills":50}'

复杂 JSON 示例

YAML：

success_commands:
  - '[http_post] https://api.example.com/event {"event":"player_join","data":{"player":{"name":"%player%","uuid":"%player_uuid%"},"server":"survival","timestamp":1234567890}}'

特性说明

异步执行 - 不会阻塞服务器
超时保护 - 5秒连接/读取超时
错误处理 - 请求失败不影响其他命令
占位符支持 - 支持 %player%、%player_uuid% 等
JSON 格式 - 自动设置 Content-Type: application/json

Debug 模式
开启 debug 后可以看到：

请求的 URL
发送的 JSON 数据
响应状态码
响应内容

常见问题 FAQ

Q1: 如何实现多个条件的复杂判断？

代码：

A: 使用 AND、OR、NOT 组合：
   - AND：所有条件都必须满足
   - OR：任一条件满足即可
   - NOT：条件取反
   可以无限嵌套实现复杂逻辑

Q2: WEB_JSON 会影响服务器性能吗？

代码：

A: 不会！
   1. 自动缓存 5 秒，相同请求不会重复
   2. 异步执行，不阻塞主线程
   3. 超时保护，最多等待 5 秒
   4. 自动管理缓存大小

Q3: HTTP POST 请求失败怎么办？

代码：

A:
   1. 请求失败会在日志中记录
   2. 不会影响其他命令的执行
   3. 开启 debug 模式查看详细错误信息
   4. 检查 API 地址是否正确
   5. 确保服务器可以访问外网

Q4: 如何调试脚本？

代码：

A:
   1. 使用命令：/xyscript debug on
   2. 或在 config.yml 设置 debug: true
   3. 控制台会输出详细的执行过程
   4. 可以看到条件判断、命令执行等信息

Q5: 能否与其他插件联动？

代码：

A: 可以！
   1. XYLogin - 支持 login/logout 事件
   2. 权限插件 - 通过 PERMISSION 条件
   3. 任何插件 - 通过执行命令联动
   4. 外部系统 - 通过 WEB_JSON 和 HTTP POST

Q6: JSON 路径怎么写？

代码：

A:
   - 对象属性：data.user.name
   - 数组元素：data.items[0].name
   - 嵌套结构：data.user.profile.level
   示例：{"data":{"user":{"name":"Steve"}}}
   路径：data.user.name → 返回 "Steve"

Q7: 占位符不生效？

代码：

A: 注意：
   1. 占位符区分大小写：%player% 而非 %Player%
   2. 确保占位符被包含在 % % 中
   3. 玩家相关占位符需要有玩家对象
   4. 变量占位符需要在上下文中存在

Q8: Tick 任务会消耗性能吗？

代码：

A:
   1. 合理设置 interval 值（建议 ≥ 100）
   2. 避免在 tick 中执行大量命令
   3. 使用条件限制执行频率
   4. 尽量使用事件而非 tick
   5. 开启 debug 查看执行频率

Q9: 如何实现玩家首次加入才触发？

代码：

A: 建议配合其他插件实现：
   1. 使用 PERMISSION 条件
   2. 在 success_commands 中给予权限
   3. 下次加入时因为有权限而不满足条件
   或使用 WEB_JSON 从数据库检查

Q10: 可以发送到哪些外部服务？

代码：

A: HTTP POST 支持任何接受 JSON 的 API：
   1. Discord Webhook
   2. Slack Webhook
   3. 自己的网站/API
   4. 统计服务
   5. 数据库（通过 API）
   6. 其他游戏服务器

与 XYLogin 联动

XYScript 完美支持 XYLogin 插件的登录事件！

支持的事件：

login - 玩家成功登录账号时触发
logout - 玩家登出账号时触发

联动示例 - 登录欢迎与奖励

YAML：

enabled: true
description: "玩家登录时根据VIP等级发放奖励"

listeners:
  login:
    condition:
      type: PERMISSION
      permission: "vip.premium"
   
    success_commands:
      - "[message] &6&l高级VIP %player% 登录成功！"
      - "[message] &e这是您的登录奖励！"
      - "[console] give %player% diamond 5"
   
    failure_commands:
      - "[message] &a欢迎回来，%player%！"

联动示例 - 登录日志记录

YAML：

enabled: true
description: "记录玩家登录信息到外部系统"

listeners:
  login:
    success_commands:
      - "[message] &a登录成功！"
      - '[http_post] https://api.yourserver.com/player/login {"uuid":"%player_uuid%","name":"%player%","time":"2025-12-29","ip":"127.0.0.1"}'
 
  logout:
    success_commands:
      - '[http_post] https://api.yourserver.com/player/logout {"uuid":"%player_uuid%","name":"%player%","time":"2025-12-29"}'

性能优化建议

WEB_JSON 性能优化

合理使用缓存 - 系统自动缓存 5 秒，相同请求不会重复
避免频繁请求 - 不要在 tick 中使用 WEB_JSON（除非 interval 很大）
优化 API 响应速度 - 确保你的 API 服务器响应快速（< 1秒）
使用 CDN - 如果可能，将 API 部署在 CDN 上

HTTP POST 优化

批量发送 - 不要在短时间内发送大量请求
异步处理 - 系统已自动异步，无需担心阻塞
错误重试 - 如果需要重试，在你的 API 端实现
数据压缩 - JSON 数据尽量精简

Tick 任务优化

合理的 interval - 建议最小 100（5秒）
使用条件限制 - 用 TIME 等条件减少执行次数
避免重复逻辑 - 多个脚本不要有相同的 tick 任务
优先使用事件 - 能用事件就不用 tick

Debug 模式

开发时开启 - debug: true 或 /xyscript debug on
生产环境关闭 - 避免日志过多影响性能
定期检查日志 - 查看是否有异常请求

开发计划

✓ 多事件支持（join/quit/login/logout/chat/tick）
✓ 条件判断系统（AND/OR/NOT/TIME/DATE/PERMISSION/WORLD）
✓ 命令执行系统（console/player/message/broadcast）
✓ WEB_JSON 条件（异步 API 集成）
✓ HTTP POST 命令（发送数据到外部 API）
✓ Debug 模式（详细日志输出）
○ PlaceholderAPI 支持
○ 更多事件支持（方块破坏、实体击杀、玩家死亡）
× 更多条件类型（经济、等级、统计数据）
× 脚本变量系统（临时变量存储）
× 冷却系统（防止刷奖励）

说明：✓ = 已完成 ○ = 开发中 × = 计划中

更新日志

v1.2.0 (2025-12-29)

新增 WEB_JSON 条件 - 支持从外部 API 获取数据
新增 HTTP POST 命令 - 支持向外部 API 发送数据
新增 Debug 命令 - /xyscript debug <on|off>
优化异步处理机制 - 所有网络请求异步执行
优化缓存系统 - WEB_JSON 自动缓存 5 秒
修复 ConfigurationSection 解析问题
修复条件判断逻辑错误

v1.1.0

新增 XYLogin 插件联动
新增 Info 命令 - /xyscript info <脚本名>
新增聊天事件支持
优化配置文件加载逻辑

v1.0.0

发布首个正式版本
新增基础事件监听
新增条件判断系统

支持与反馈

如果你在使用过程中遇到任何问题，或者有新的功能建议，欢迎：

在本帖下方回复
加入我们的交流群
提交 Issue 到 GitHub

感谢使用 XYScript！

如果觉得这个插件有帮助，请给个评分和回复支持！

XYScript - 让服务器管理更简单
Powered by Thexiaoyu

反馈： Taoisa

原创脚本 XYScript —— 小雨牌脚本触发器 1.2.0-fix

评分

Thexiaoyu 的其他资源

分享资源

最新更新

1.2.0-fix

1.2.0

我们重视您的隐私

原创 脚本 XYScript —— 小雨牌脚本触发器 1.2.0-fix

评分

Thexiaoyu 的其他资源

分享资源

最新更新

1.2.0-fix

1.2.0

我们重视您的隐私

原创脚本 XYScript —— 小雨牌脚本触发器 1.2.0-fix