问题答疑群：1031761951（注明来意）

3.1.0版本修复若干问题，具体可前往https://github.com/Yuncan050115/ZMusicGUI/releases/tag/v3.1.0

3.0.2版本已支持Dominion和lands领地插件，并且支持全GUI自由编辑。

前置Mod https://modrinth.com/mod/zmusic

建议自行部署定制api https://github.com/Yuncan050115/ourcraft-music-api

由于本插件完全重置了原作代码为纯kotlin，因此3.0.0版本开始改为原创，但仍然保留与真心的交流记录：

ZMusicGUI

Ourcraft 服务器音乐 GUI 插件 (Kotlin) — 内置 Mod 通信，服务端无需外部音乐插件

功能

• 多平台点歌: 网易云 / 酷狗 / 酷我 (免登录, 仅免费歌曲)

• 歌单管理: 网易云/酷狗歌单搜索、导入、收藏；个人/全服公开双区

• 播放范围: 个人 / 领地 / 地皮 / 世界 / 全服 (Residence + PlotSquared 自动检测)

• 歌词同步: BossBar / ActionBar，每秒更新

• 点歌历史: 自动记录，置顶显示

• 全服点歌: 搜索歌曲分享给全服玩家

• Folia 兼容: 自动检测 RegionizedServer，跨平台调度

v3.0.0 起移除账号登录模块 (QQ/网易云 VIP 登录已删除), 仅播放免费歌曲。VIP 歌曲无法播放, 请尝试切换其他源或歌曲。

命令

| 命令 | 别名 | 说明 |

|------|------|------|

| /zmusicgui | /zmg, /点歌, /dg, /zm | 打开主菜单 |

| /zmg reload | — | 重载配置文件 (需 admin) |

| /zmg mode | — | 切换播放模式 |

| /zmg stop | — | 停止播放 |

| /zmg list | — | 查看播放列表 |

| /zmg pushplay <平台:歌单ID:推送者:模式> | — | 接收歌单推送 |

权限

| 权限节点 | 默认 | 说明 |

|----------|------|------|

| zmusicgui.use | 所有人 | 基础功能 (点歌/歌单/控制) |

| zmusicgui.admin | OP | 管理功能 (重载/全服播放/审批) |

| zmusicgui.bypass | 无 | 绕过点歌冷却 |

LuckPerms 示例:

/lp group default permission set zmusicgui.use true

/lp group admin permission set zmusicgui.admin true

配置文件

plugins/ZMusicGUI/config.yml:

# ZMusicGUI v3.0.0 配置文件

debug: false

prefix: "&b[ZMusicGUI]&r "



# API 服务端地址 (建议自行部署: https://github.com/Yuncan050115/ourcraft-music-api)

api:

  ourcraft: "https://music.yuncan.xyz"



# 点歌

music:

  cost: 10                    # 点歌费用

  cooldown-seconds: 5         # 点歌冷却

  default-source: "netease"   # 默认源: netease/kugou/kuwo

  search-limit: 10            # 搜索结果数量



# 歌词

lyric:

  default-enabled: true       # 新玩家默认开启歌词

  default-mode: "BOSSBAR"     # BOSSBAR / ACTIONBAR

  update-ticks: 10            # 更新延迟

  display-format: "LYRIC"     # LYRIC / LYRIC_SINGER / LYRIC_NEXT / FULL



# 播放范围

scope:

  approval-timeout-seconds: 30

  self:       { cost: 1.0,  require-approval: false }

  residence:  { cost: 20.0, require-approval: true }

  plot:       { cost: 20.0, require-approval: true }

  world:      { cost: 50.0, require-approval: true, payee-account: "" }

  server:     { cost: 100.0, require-approval: true, payee-account: "" }



# 歌单

playlist:

  default-private: true

  cache-ttl-seconds: 30

  songs-per-page: 21

  history-limit: 200



# GUI

gui:

  show-credits: true

  main-menu-title: "&6&l☄ Ourcraft &8▸ &b音乐中心"

  quick-play-title: "&6&l🎵 快捷点歌"

  playlist-title: "&6&l歌单浏览"

  control-title: "&6&l播放控制"

语言文件

plugins/ZMusicGUI/messages.yml — 所有提示信息均可翻译为任意语言，支持 & 颜色代码和 {变量} 占位符。

依赖

| 插件 | 版本 | 必需 | 说明 |

|------|------|------|------|

| 客户端 ZMusic Mod | 3.6.0+ | ✅ | 客户端音乐播放 (Fabric / NeoForge) |

| Vault + 经济插件 | 1.7+ | 软依赖 | 点歌扣费 |

| Residence | 6.x+ | 软依赖 | 领地范围 |

| PlotSquared | 7.x+ | 软依赖 | 地皮范围 |

无需 ZMusic 服务端插件 — 本插件内置 Mod 通信，服务端零外部依赖。

无需 PlaceholderAPI — 歌词显示直接从 MusicPlayer 读取。

兼容性

| Minecraft | Paper / Purpur | Folia | 状态 |

|-----------|---------------|-------|------|

| 1.13.x | 1.13+ | — | ✅ |

| 1.19.x | 1.19+ | 1.19+ | ✅ |

| 1.20.x | 1.20+ | 1.20+ | ✅ |

| 1.21.x | 1.21+ | 1.21+ | ✅ |

| 26.1.X | 26.1.X | 26.1.X | ✅ |

构建

git clone https://github.com/Yuncan050115/ZMusicGUI.git

cd ZMusicGUI

./gradlew shadowJar

# 输出: build/libs/ZMusicGUI-3.0.0.jar

要求: JDK 21+, Kotlin 2.1.20, Gradle 9.x + Shadow

服务端 API

使用 ourcraft-music-api 作为后端:

• 网易云: enhanced 模式，免登录可播放免费歌曲

• 酷狗/酷我: 公开接口，仅免费歌曲

bStats

本插件使用 bStats 收集匿名使用数据。可在 plugins/bStats/config.yml 中关闭。

更新日志

v3.0.0 (2026-06-28)

• 🗑️ 移除账号登录模块 — 因不可抗力，VIP 登录无法实现, 彻底删除账号绑定/扫码登录相关代码

• 🗑️ 因不可抗力，移除 QQ 音乐源支持 (SUPPORTED_SOURCES 不再包含 qq, normalizeSource 保留 qq→qq 兼容映射)

• ♻️ 简化 OurMusicApi.getSongDetail 签名 (移除 userId/token/cookie 参数)

• ♻️ 简化 SearchService.getSongDetailBySource (内部不再读取账号登录态)

• ♻️ 简化点歌失败提示为 "歌曲暂时无法播放, 请尝试其他源或歌曲"

• ♻️ PlaylistPushGui.startPlaylistForPlayer 移除 requester 参数

• 📝 更新 README, 移除账号绑定章节

v2.5.0 (2026-06-28)

• 🗑️ 移除酷狗/酷我账号登录 — 因不可抗力，服务器 IP 无法获取 VIP

• 🗑️ 移除酷狗/酷我 VIP 歌曲提醒，改为提示使用网易云兜底

• ✨ 新增网易云扫码登录支持 (网页扫码 → 6位绑定码 → 游戏输入)

• ✨ QQ音乐支持网页提交 Cookie 获取绑定码 (除原有 F12 直接输入外)

• ♻️ AccountManager 重构，仅保留 QQ + 网易云 两个平台

• 📝 更新 README，添加 SVG 徽章

v2.4.3 (2026-06-27)

• 🐛 修复 QQ音乐 cookie 透传问题

• 🔧 优化绑定流程，统一 F12 Cookie 复制方式

v2.4.0 (2026-05-30)

• ✨ 多平台 cookie 透传 (酷狗/酷我从字段解析改为完整 cookie)

• ✨ 服务端 song_full 端点 (1次请求获取 name+url+lyric+time)

• 📦 Shadow + relocate 打包 Kotlin stdlib

v2.2.1 (2026-05-28)

• 🌐 全版本兼容：Paper 1.13 / 1.19 / 1.20 / 1.21

• 🔧 BossBar 改为 Bukkit 原生 API

• 🔄 /zmg reload 命令重载配置文件

v2.0.0 (2026-05-27)

• 🎉 重写为独立 Kotlin 实现 (不再依赖 ZMusic CE 服务端插件)

• 📦 内置 Mod 通信

• 🎵 多平台点歌 + 歌单管理 + 歌词同步

贡献指南

欢迎提交 Issue 和 Pull Request!

1. Fork 本仓库

2. 创建分支 (git checkout -b feature/你的分支名字)

3. 提交更改 (git commit -m '你的分支名字')

4. 推送到分支 (git push origin feature/你的分支名字)

5. 创建 Pull Request

请确保代码风格一致，新功能有适当的配置项。

作者

• ZMusicGUI: Yuncan

• ZMusic Mod: ZMusic 开发团队

许可证

本项目基于 GPL-3.0 许可证开源。

ZMusicGUI — Ourcraft 服务器音乐 GUI 插件

Copyright (C) 2026 Yuncan



This program is free software: you can redistribute it and/or modify

it under the terms of the GNU General Public License as published by

the Free Software Foundation, either version 3 of the License, or

(at your option) any later version.



This program is distributed in the hope that it will be useful,

but WITHOUT ANY WARRANTY; without even the implied warranty of

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

GNU General Public License for more details.