OOMusic¶
OOMusic 是喵托邦 / Meowopia 的音乐项目，分类为附属（Extensions）。目标是在游戏中浏览音乐、管理队列、显示歌词，并由服务端协调一起听。
当前状态：开发中，尚无正式稳定版。 现有开发代码不等于可直接安装使用的完整音乐客户端。普通服主请等待正式发行与安装说明，不要将开发构建用于生产服。
已实现功能 / Implemented¶
暂无正式版；以下仅为 0.1.0-SNAPSHOT 开发版实现。 尚无面向服主验收的实机兼容组合，不代表安装即可听歌。需要匹配的 OOCore、OOEngine 和授权测试环境。
| 已有开发实现 | 验证范围与用户边界 |
|---|---|
| 队列、切歌、暂停状态、进度、音量与播放模式 | 已验证状态逻辑；不等于客户端已发声或端到端播放已完成。 |
| 搜索、发现、收藏、歌单与最近播放基础 | 已有逻辑与开发验证；默认没有音乐来源，不能直接搜索完整曲库，退出后的数据保留不作保证。 |
| 歌词解析、时间轴、翻译回退与缓存 | 已验证离线处理逻辑；尚未验收真实游戏内音画及歌词同步体验。 |
/oo music 窗口入口与可选配置接入 |
已有接入代码与开发验证；前置存在不等于完整界面或配置持久生效已完成。 |
| 房间与同步时钟基础 | 已有领域逻辑；尚未完成真实多人一起听的使用闭环。 |
未实现功能 / Not implemented¶
- 未交付： 默认可用音源与完整客户端音频播放链，当前不能承诺装上即可听歌。
- 部分实现： 完整播放器、迷你播放器和游戏内歌词同步，只有基础逻辑或入口不算完成。
- 部分实现： 一起听邀请、房主转移、断线重连与漂移校正，尚不能作为已发布的多人功能使用。
- 尚不可用： 分享歌曲、歌单及一起听邀请到 OOChat 的交互卡片，没有分享命令。
- 未完成： 队列、收藏与配置的可靠持久化恢复；配置表单更新不保证驱动实际播放器，也不保证重启保留。
- 未验收： 面向服主的稳定安装组合与 Paper/Folia 实机运行范围。
未来计划 / Roadmap¶
仅列已确认方向，不承诺发布日期或版本号：
- 先打通正式版播放闭环： 授权来源、实际发声、队列与歌词表现；以受控音源接入和兼容客户端能力为前提。
- 完成可恢复的服务器状态： 接入正式持久化能力，处理并发修改、损坏数据和升级回滚，再开放可信的配置保存流程。
- 完成联机与聊天联动： 服务端协调一起听，并通过 OOChat 的正式接口分享音乐卡片；OOChat 缺失时只关闭分享。
- 完善原创界面与易用性： 通过正式窗口能力提供完整播放器和迷你播放器，考虑键盘操作、界面缩放及减少动画；不复制第三方素材。
- 后续体验优化： 在核心播放稳定后考虑已规划的淡入淡出和 Automix，以及受限、可校验的来源配置；不开放任意脚本执行。
本页不提供未验收构建下载。上述规划依赖正式前置能力与完整联调，不因开发测试通过自动成为已发布功能。
安装与前置¶
- 必须安装 OOCore 与 OOEngine；缺失任一前置，当前插件不能正常启用。
- OOConsole 为可选前置。缺失或接入失败时应只关闭相关配置入口，而不是提供另一套后台。
- 当前开发插件要求 Java 25。面向 Paper/Folia 的真实可用版本范围尚未完成正式发行验收，暂不承诺任意服务器版本兼容。
- 前置版本不是永久锁定的等号关系：需要支持 OOMusic 所用命令、权限、受控服务与窗口能力的兼容版本。尚无可向服主推荐的最低实机验收组合；正式发布时再公布基线与升级范围。
仅在获得维护者明确标注的测试包及匹配前置时，在隔离测试服操作：
- 停止服务器，备份现有插件和数据。
- 将 OOCore、OOEngine 和 OOMusic 的服务端插件 JAR放入服务器根目录下的
plugins/；需要时同时安装 OOConsole。 - 不要将开发 SDK、测试包或 Minecraft 客户端 Mod 放入
plugins/，也不要把服务端插件装进客户端mods/。 - 完整启动服务器并检查前置和 OOMusic 是否成功启用；玩家再执行
/oo music。 - 打不开窗口、搜索无结果或没有声音时，不要通过放宽音源限制绕过问题；当前开发构建并未承诺完整播放链路。
源安全¶
计划接入的音乐来源应为本地或管理员明确授权的来源，不内置“任意链接均可播放”的承诺。远程来源须遵守 HTTPS、允许的域名与音频类型、体积和超时限制，重定向也需重新校验。
不要在聊天、截图或问题报告中提供登录凭据、原始服务响应、长期音频地址或私人文件路径。凭据配置应使用受控秘密引用，不能直接填写并公开真实密钥。音乐与封面的使用授权仍由内容提供方及服主负责。
命令与权限¶
以下仅为 未发布开发版参考。当前没有正式 Release，不能将命令存在理解为完整播放器已经可安装使用。
命令¶
| 完整语法 | 参数与默认值 | 用途 | 精确权限 | 执行者限制 | 最小示例 |
|---|---|---|---|---|---|
/oo music |
无参数、无默认参数；不接受额外参数 | 请求打开音乐窗口；窗口服务不可用时返回提示 | oomusic.open |
仅具有有效玩家身份的玩家；控制台及其他非玩家不能打开 | 玩家输入 /oo music |
/oo 根入口由 OOCore 提供。OOMusic 注册 music 子节点，无别名；命令声明与处理逻辑均使用 oomusic.open，处理逻辑也会检查玩家身份和额外参数。窗口能否打开还取决于前置服务是否就绪，不保证当前开发构建可实际播放音频。
当前不提供 /oomusic 旧命令，也没有 /oo music share、reload 或 about 子命令。窗口中的播放按钮不是聊天命令，不要把按钮动作名称输入聊天栏。
权限¶
| 精确节点 | 普通玩家默认 | OP 默认 | 对应功能与实际状态 | 继承关系 |
|---|---|---|---|---|
oomusic.open |
允许 | 允许 | 窗口命令访问权限，命令处理逻辑实际检查 | 未声明子权限或父子继承 |
oomusic.listen-together.host |
允许 | 允许 | 仅预留声明；当前未发现使用此节点授权的房间入口，不代表一起听已可用 | 未声明子权限或父子继承 |
oomusic.admin.provider |
不授予 | 允许 | 仅预留声明；当前未发现使用此节点授权的完整音源管理入口 | 未声明子权限或父子继承 |
上表是插件声明的默认值，权限管理插件可以显式覆盖。OOMusic 未声明 oomusic.* 通配权限，也未声明权限树；不要假定授予其中一个节点会自动获得其他节点。oomusic.open 的检查范围是窗口命令入口，不能据此声称所有界面操作都有独立权限复验。
变量 / 占位符¶
当前版本暂无对外变量/占位符。 此处“当前版本”仅指尚未正式发布的开发版本。
| 类型 | 对外支持状态 | 可用位置与示例 | 前置说明 |
|---|---|---|---|
| PlaceholderAPI / PAPI | 没有注册 OOMusic expansion | 无支持的写法或返回值示例，请勿自行拼接 %oomusic_...% |
安装 PlaceholderAPI 也不会自动增加支持 |
| 聊天消息模板变量 | 未提供 OOMusic 变量解析接口 | 暂不可用于聊天、Tab 或记分板模板 | OOChat 音乐卡片仍在开发中 |
| UI 绑定 | 仅供内置开发界面使用，不是公开稳定占位符接口 | 不提供服主可复制的变量写法；内部标题、进度等字段不能当 PAPI 使用 | 依赖窗口服务，不代表跨插件模板支持 |
| 配置替换 | 当前没有对外配置文件或通用变量替换器 | 无可用配置替换示例 | env: / secret: 是计划配置中的秘密引用约定，不是显示占位符 |
可选可视化配置¶
已准备 OOConsole 配置接入，但当前配置状态保存在内存中，未完成服主可依赖的持久化与播放器配置生效闭环。不能把“出现表单”理解为配置已永久保存、音源已加载或播放器已经应用设置。
不安装 OOConsole 不会自动生成其他 Web 后台。普通服主暂不应依赖此入口管理生产音源。
窗口状态¶
当前保留开发中的窗口入口。完整播放器、迷你播放器及客户端兼容体验仍需联调与正式验收；本页不将窗口基础能力发布视为 OOMusic 已正式可用。
配置 / Configuration¶
当前没有供服主编辑的外部 config.yml、语言文件、TOML 或 JSON 配置文件，也不会自动生成可编辑的播放器 YAML。 不要手工创建这些文件并期待插件读取。
| 项目 | 当前行为与生效方式 |
|---|---|
| 播放器布局模板 | 随插件内置，不从服务器数据目录加载外部覆盖；不建议自行解包修改。 |
| 音乐来源 | 默认列表为空。没有受支持的用户配置示例可以直接接通本地目录或第三方音乐服务。 |
| OOConsole 设置 | 开发中的内存配置；重启会重新使用默认值，不能作为持久配置使用。 |
| 播放与收藏状态 | 不应依赖退出、切服或重启后保留；正式持久化恢复尚未对玩家交付。 |
因此本阶段不提供虚构的 YAML/JSON 示例。未来正式开放配置后，会在这里提供可直接使用的示例、字段说明、重启/重载要求及升级迁移方法。
升级与回滚¶
目前没有稳定版之间的受支持升级路径。授权测试构建更新前，应完整停服并备份插件和数据，记录配套前置组合；不要使用热重载。
若更新后无法启用或窗口异常，停服后恢复已备份的兼容插件组合。当前内存中的队列、收藏和配置不能视为已保存数据。不要混装未知来源的前置，也不要用旧开发包覆盖正式服测试。
已知问题¶
- 尚无正式稳定版本，也未给出可保证运行的 Paper/Folia 实机矩阵。
- 默认没有可播放音源；完整音频传输、客户端播放与界面体验尚未完成正式交付。
- 音乐卡片分享、完整一起听、迷你播放器与持久化恢复仍在开发中。
- OOConsole 表单状态与实际播放器生效、重启保存不是同一回事。
- 请勿将框架接入、开发测试通过或界面草稿当作已发布产品能力。
Java 兼容计划¶
Java 21 支持是新增目标，尚未实现或验收。 当前开发插件仍要求 Java 25；部分基础代码使用 Java 21 不代表整个插件及前置能在 Java 21 运行。
计划先验证 Java 21 下的 Paper 1.20.5、1.20.6 与 1.21 系列至 1.21.11 的兼容边界，再核对更早的 Paper 1.20.x。需要 OOCore、OOEngine 及相关可选组件提供兼容能力；未测试的版本不会列为已支持。
现有 Java 25 / Paper 26.x 方向保留。Paper 26.1 及以后不能因本计划改用 Java 21。 Folia 另行验证，本计划不代表所有服务端或所有历史 Minecraft 版本兼容。
参考：Paper Java 推荐版本、Minecraft 26.1 官方说明。
MC/Paper/Folia 跨版本适配统一由 OOCore 实现；OOMusic 负责自身 Java 字节码、依赖及业务验证。
联系 / Contact¶
反馈请提供插件版本、前置版本、服务器类型与版本、Java 版本、复现步骤及脱敏日志；不要上传令牌、私有音源地址或完整配置秘密。
- 作者 / Author: zkonikishi
- QQ: 276098266
- Discord: https://discord.gg/KPq2fZHFK
- ifdian
- QQ群 / QQ Group: 1063369777
视频相关功能¶
音乐视频画面不属于当前已交付功能，暂不提供 MV 播放或视频配置入口。