Skip to content
BranchesTags

Repository files navigation

MCSManager Bridge

通过 MCSManager API 在 Minecraft 游戏内管理服务器实例的 Paper 插件。

AI 辅助声明： 本项目代码及文档由 AI 辅助生成，经人工审查与测试。

环境要求

项目 要求
服务端 Paper 1.26.1+
Java 25+
MCSManager 已安装并运行
可选依赖 zMenu 1.1.5+、PlaceholderAPI 2.12.2+

安装

  1. 将 mcsm-bridge-<version>.jar 放入服务器的 plugins/ 目录
  2. 重启服务器
  3. 编辑 plugins/MCSManager-Bridge/config.json 或在游戏内使用命令配置

初次配置

/mcsm seturl http://你的面板地址:端口
/mcsm setkey 你的API密钥
/mcsm setdaemon 你的守护进程ID
/mcsm test

获取守护进程ID：在 MCSManager 面板的节点页面查看。

指令系统

所有命令需要 mcsm.admin 权限（OP 默认拥有）。

基础配置

命令 说明
/mcsm seturl <url> 设置 MCSManager API 地址（需包含 http:// 或 https://）
/mcsm setkey <key> 设置 API 密钥
/mcsm setdaemon <id> 设置默认守护进程ID
/mcsm test 测试 API 连接

实例管理

命令 说明
/mcsm list [daemonId] [page] 列出实例（每页8个，点击实例名复制UUID）
/mcsm start <name> 启动实例
/mcsm stop <name> 停止实例
/mcsm restart <name> 重启实例
/mcsm kill <name> 强制终止实例
/mcsm status <name> 查看实例状态
/mcsm cmd <name> <command> 向实例发送控制台命令

/mcsm list 底部提供快捷点击按钮：上一页、刷新、下一页、关闭。

实例绑定

命令 说明
/mcsm bind <name> <uuid> <daemonId> [nickname] 绑定实例
/mcsm unbind <name> 解绑实例
/mcsm bindings 列出所有已绑定实例
/mcsm bindall [daemonId] 清空后自动绑定所有实例（需确认）
/mcsm confirm 确认执行自动绑定
/mcsm abort 取消自动绑定

bindall 会先清空所有现有绑定，再按实例名逐一重新绑定。同名实例自动追加后缀（实例名_1、实例名_2）。

自定义物品映射

命令 说明
/mcsm setitem <uuid> <material> 设置实例在 zMenu 菜单中的显示物品
/mcsm removeitem <uuid> 移除物品映射
/mcsm items 列出所有物品映射

未设置映射的实例默认使用红色羊毛（已停止）/ 绿色羊毛（运行中）。运行中的实例自动添加附魔光效。

zMenu 联动

命令 说明
/mcsm refresh 重新生成 zMenu 配置并执行 zm reload
/mcsm menu 显示菜单打开方式

zMenu 联动逻辑

菜单结构

  • 容器规格：54 格（6行 x 9列）
  • 外圈：灰色玻璃板（不可选取）
  • 实例区域：内部 4行 x 7列 = 28 个槽位
  • 顶部中央（slot 4）：命令方块，显示运行实例数
  • 底部中央（slot 49）：关闭按钮
  • 底部右侧（slot 50）：页码信息
  • 左下角（slot 45）：上一页箭头
  • 右下角（slot 53）：下一页箭头

分页机制

  • 每页最多容纳 28 个实例
  • 实例数量超过 28 时自动生成下一页
  • 配置文件命名：mcsm_instances_1.yml、mcsm_instances_2.yml、mcsm_instances_3.yml...
  • 翻页通过执行 zm open mcsm_instances_<页码> 命令实现
  • 超出当前页数的旧配置文件会自动清理

实例显示规则

状态 默认物品 特效
运行中 (running) 绿色羊毛 附魔光效
已停止 (stopped) 红色羊毛 无
自定义物品 通过 /mcsm setitem 设置 运行中时附加附魔光效

点击实例物品：运行中点击停止，已停止点击启动。

同步时机

以下操作会自动同步 zMenu 菜单配置：

  • /mcsm list 执行时
  • /mcsm start / /mcsm stop / /mcsm restart / /mcsm kill 成功后
  • /mcsm refresh 手动刷新（同时执行 zm reload）

配置文件

配置文件路径：plugins/MCSManager-Bridge/config.json

{
  "apiBaseUrl": "http://localhost:23333",
  "apiKey": "",
  "defaultDaemonId": "",
  "boundInstances": {
    "生存服": {
      "instanceUuid": "dca64dd7960b46c8918ccdc16f3887ef",
      "daemonId": "4869dece94e44cd59bce0f9b6372c41e",
      "nickname": "生存服"
    }
  },
  "instanceItems": {
    "dca64dd7960b46c8918ccdc16f3887ef": "DIAMOND"
  }
}
字段 说明
apiBaseUrl MCSManager 面板地址（含 http:// 或 https://）
apiKey API 密钥（从面板设置中获取）
defaultDaemonId 默认守护进程ID
boundInstances 已绑定的实例映射（键为绑定名）
instanceItems 实例自定义物品映射（键为UUID，值为材质名）

构建

环境要求

  • JDK 25+
  • Gradle 9.0+（项目已包含 Gradle Wrapper）

构建步骤

# Windows
gradlew.bat build

# Linux/macOS
./gradlew build

构建产物位于 build/libs/mcsm-bridge-<version>.jar。

依赖来源

所有依赖均通过 Maven 仓库获取，无需本地 JAR 文件：

依赖 仓库 作用域
io.papermc.paper:paper-api PaperMC 官方仓库 compileOnly
me.clip:placeholderapi ExtendedClip 仓库 compileOnly
com.google.code.gson:gson Maven Central compileOnly

版本规则

采用 x.y.z 三段式版本号：

变更类型 版本变化
大版本重构 x+1
新增功能 y+1
修改/Bug修复 z+1

常见问题与解决方案

连接失败：Connection refused

原因： API 地址错误、端口错误、或面板未启动。

解决：

  • 确认 MCSManager 面板正在运行
  • 确认地址格式为 http://地址:端口，不要包含路径
  • 在服务器本机测试 http://localhost:23333
  • 如使用域名，确保域名解析正确且端口已开放

连接失败：unknown protocol

原因： API 地址缺少 http:// 或 https:// 协议前缀。

解决： 使用 /mcsm seturl http://你的地址:端口 重新设置。

连接失败：Not Found (404)

原因： API 端点路径不匹配（可能面板版本不同）。

解决： 确认 MCSManager 版本，插件使用 /api/service/remote_service_instances 端点获取实例列表。

令牌验证失败 (403)

原因： API 密钥错误。

解决：

  • 在 MCSManager 面板 → 设置 中获取正确的 API Key
  • 使用 /mcsm setkey <正确的密钥> 重新设置
  • 密钥通过 URL 查询参数 apikey 传递，不使用 Authorization 头

Validator failed: "daemonId" is required (400)

原因： 未设置守护进程ID。

解决： 在面板节点页面获取守护进程ID，执行 /mcsm setdaemon <daemonId>。

构建失败：Unsupported class file major version

原因： Java 版本与 Gradle 版本不兼容。

解决：

  • 确认安装了 JDK 25+
  • 确认 Gradle 版本为 9.0+
  • 检查 gradle/wrapper/gradle-wrapper.properties 中的 distributionUrl

构建失败：Could not resolve io.papermc.paper:paper-api

原因： Paper API 版本号与实际发布版本不匹配。

解决：

  • 访问 PaperMC 仓库 查看可用版本
  • 修改 build.gradle 中的版本号

zMenu 菜单无法打开

原因： zMenu 插件未安装、版本不兼容、或配置未生成。

解决：

  • 确认 zMenu 1.1.5+ 已安装
  • 执行 /mcsm refresh 重新生成配置并 reload
  • 检查 plugins/zMenu/inventories/ 目录下是否有 mcsm_instances_1.yml 文件
  • 手动执行 /zm open mcsm_instances_1 查看报错信息

zMenu 翻页无法切换到第一页

原因： 旧版本首页文件名为 mcsm_instances.yml（无 _1 后缀）。

解决： 更新到 2.0.5+ 版本，所有页码统一使用 _N 后缀。执行 /mcsm refresh 重新生成。

实例状态未同步到菜单

原因： 未执行刷新。

解决： 执行 /mcsm refresh 手动刷新。/mcsm list 和实例操作（start/stop/restart/kill）会自动触发同步。

/mcsm list 点击实例名无法复制 UUID

原因： 客户端版本不支持 copyToClipboard 点击事件，或被其他插件覆盖。

解决： 确保使用 Paper 1.26.1+，检查是否有其他插件冲突。

Gson 序列化异常 (Java 25/26)

原因： Gson 通过反射序列化包含 JavaPlugin 实例的对象时出错。

解决： 插件已将 plugin 字段标记为 transient，如果自定义代码中出现类似问题，对 JavaPlugin 类型字段添加 transient 关键字。

项目结构

mcsm-bridge/
├── build.gradle                          # 构建配置
├── gradle.properties                     # 版号配置
├── settings.gradle
├── gradlew.bat                           # Gradle Wrapper (Windows)
├── gradle/wrapper/
│   ├── gradle-wrapper.jar
│   └── gradle-wrapper.properties
└── src/main/
    ├── java/com/example/mcsmbridge/
    │   ├── MCSMBridgePlugin.java         # 插件主类
    │   ├── api/MCSMApiClient.java        # MCSManager API 客户端
    │   ├── command/MCSMCommand.java      # 命令处理
    │   ├── config/MCSMConfig.java        # 配置管理
    │   ├── gui/GUIInventory.java         # GUI 容器
    │   ├── gui/ChatInputListener.java    # 聊天输入监听
    │   ├── placeholder/MCSMPlaceholderExpansion.java  # PlaceholderAPI
    │   └── zmenu/ZMenuConfigGenerator.java  # zMenu 配置生成
    └── resources/
        └── plugin.yml                    # 插件描述文件

许可

本项目仅供学习交流使用。

About

用于在游戏内连接MCSmanager后台，并执行开关实例等操作。

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Used by

Contributors

Languages