二次开发 工具 娱乐 【YccMusic——沉浸式奏乐】原版乐器演奏 / 沉浸式奏乐 / 自定义歌曲/自定义乐谱 / 怪物同步合奏 /1.0正式版 2026-08-21

【插件名称】YccMusic——沉浸式奏乐
【插件类型】乐器 / 音乐 / GUI / 资源包 / 自定义歌曲
【适用服务端】Paper 1.21
【Java 版本】Java 21
【前置插件】CraftEngine （必需）
【客户端要求】原版客户端，无需安装 Fabric、Forge、NeoForge 或任何客户端 Mod

新版接入 t.alcy.cc，每次打开乐谱都会会不一样，高斯模糊可调​

一、插件介绍​

YccMusic 是一款面向 Paper 1.21的中文乐器与音乐插件。玩家可以使用带独立模型的乐器演奏 YAML 或 MIDI 歌曲，也可以用指挥棒组织怪物合奏。
插件使用原版资源包、PDC 物品、Inventory GUI、命令、物品交互和 Paper Scheduler 工作，客户端无需安装 Fabric、Forge、NeoForge 或其他 Mod。

二、主要功能​

1. 提供 11 种乐器：
风笛、迪吉里杜管、长笛、琉特琴、钢琴、三角铁、小号、小鼓、维埃尔琴、末影贝斯、手碟。

2. 乐器物品：
中文名称、CustomModelData、PersistentDataContainer、独立权限、音域、音量、音高、距离和冷却。默认删除全部乐器 Lore，管理员仍可在 instruments.yml 自行添加。
3. 乐器视觉资源：
包含 11 个物品栏模型、11 个手持模型和对应纹理，已经适配 Minecraft 1.21.11 的新物品模型定义。
4. 合成配方：
注册 11 种乐器合成图样，支持配方书发现。风笛配方会正确要求 YccMusic 长笛物品。
5. 演奏操作：
玩家先在中文歌曲 GUI 中选择歌曲。手持乐器普通右键空气或方块直接演奏，潜行右键打开歌曲列表，左键停止。演奏绑定启动时的原乐器，丢弃、收起或切换乐器会进入暂停宽限期，及时拿回可续播，超时后下次从头开始。
僵尸可以拾取 YccMusic 乐器。指挥棒潜行右键打开歌曲列表，普通右键任意持乐器怪物，让其演奏玩家最近选择的歌曲。玩家演奏互不强制同步；同世界、同歌曲且在配置半径内的怪物共享服务器时间轴，并按低音、中音、高音和打击声部分配轨道、过滤重复音符、自动归一化音量。
6. 音乐系统：
支持 YAML 自定义歌曲和标准 MIDI 文件，支持 tempo、多轨、多通道、velocity、音长、逐音符乐器、循环、音量、pitch 和播放距离。
7. 播放范围：
可以只对指定玩家播放、对附近玩家播放，或对全服播放。每位玩家拥有独立播放状态，支持暂停、继续、停止和进度显示。
8. GUI：
普通玩家只看到中文歌曲列表、上一页和下一页，点击歌曲只保存选择。乐器或指挥棒潜行右键即可打开歌曲列表。管理员使用 /yccm instruments 打开独立乐器领取菜单，左键领取 1 件，Shift+左键领取 64 件。菜单物品无法被取走。
9. CraftEngine 资源包接入：
YccMusic 会把模型、纹理、语言、声音注册和授权 OGG 导出为 CraftEngine 外部输入包，通过 26.7.4 的资源包缓存事件参与合并。最终资源包由 CraftEngine 生成、托管、上传和发送；/yccm pack 也直接调用 CraftEngine，不会再叠加第二个独立资源包。
10. 生物乐器与粒子：
可选开启怪物随机携带乐器、拾取、掉落和循环演奏。默认在演奏者头顶生成粉色音符粒子，粒子类型、RGB 颜色、数量、位置、散布范围和可见距离均可在 config.yml 修改。玩家默认看不到自己的演奏粒子，不会遮挡第一人称视角。演奏还会发送原版 INSTRUMENT_PLAY 游戏事件，可触发幽匿感测。
11. 热重载：
/yccm reload 会重新加载 config.yml、messages.yml、instruments.yml 和 songs/，停止旧播放任务、关闭菜单、清理冷却并重注册配方。配置错误时保留旧配置，单个损坏歌曲不会拖垮整个插件。

三、资源与声音说明​

资源包包含乐器模型、纹理和演奏声音，其他未提供独立采样的乐器会使用 Minecraft 原版音色。许可证文件随发布包提供。
默认附带的 MIDI 用于服务器内测试与演示。公开传播前，服务器管理者需要自行确认音乐作品及 MIDI 编曲的使用授权。

四、主要命令​

/yccm help 查看中文帮助
/yccm reload 重载插件
/yccm give <玩家> <乐器> [数量] 给予乐器
/yccm instruments 管理员打开乐器领取菜单
/yccm songs 查看歌曲列表
/yccm play <歌曲> [玩家] 对指定玩家播放
/yccm playnearby <歌曲> [半径] 对附近玩家播放
/yccm playall <歌曲> 对全服播放
/yccm stop [玩家] 停止播放
/yccm pause 暂停歌曲
/yccm continue 继续歌曲
/yccm pack 获取资源包
/yccm gui 打开歌曲列表
/yccm select <歌曲> 选择右键播放的歌曲
/yccm volume [0-2] 设置个人音量
/yccm info 查看插件信息

五、主要权限​

yccmusic.player 普通玩家基础功能总权限，默认关闭
yccmusic.use 使用乐器，默认关闭
yccmusic.gui 使用歌曲 GUI，默认关闭
yccmusic.select 查看和选择歌曲，默认关闭
yccmusic.conduct 使用指挥棒指挥持乐器怪物，默认关闭
yccmusic.admin 管理插件，默认 OP
yccmusic.give 给予乐器，默认 OP
yccmusic.play 播放歌曲，默认关闭
yccmusic.play.nearby 附近播放，默认 OP
yccmusic.play.all 全服播放，默认 OP
yccmusic.stop 停止、暂停和继续，默认关闭
yccmusic.reload 重载插件，默认 OP
yccmusic.pack 获取资源包，默认关闭
yccmusic.use.<乐器ID> 使用指定乐器，默认关闭
LuckPerms 给默认玩家组开放完整基础功能：
/lp group default permission set yccmusic.player true

六、安装方法​

1. 确认服务端为 Paper 1.21.11，并使用 Java 21 启动。
2. 将 craft-engine-paper-plugin-26.7.4.jar 放入 plugins 目录。
3. 将 YccMusic.jar 放入 plugins 目录。
4. 启动服务器，确认 CraftEngine 与 YccMusic 均正常启用。
5. 在 plugins/CraftEngine/config.yml 配置 resource-pack.delivery.hosting；可使用 CraftEngine 自托管或它支持的其他托管方式。
6. 执行 /ce reload pack 或 /yccm reload，玩家使用 /yccm pack 获取 CraftEngine 合并资源包。
注意：YccMusic 只注册资源，最终下载地址、提示、拒绝踢出、自动上传和加入发送全部由 CraftEngine 管理。CraftEngine 与 YccMusic 的加入自动发送选项不要同时开启，以免重复弹包。

七、自定义歌曲​

把 .yml、.yaml、.mid 或 .midi 文件放入：
plugins/YccMusic/songs/
然后执行：
/yccm reload
YAML 可配置歌曲 ID、中文名称、作者、默认乐器、tempo、音量、pitch、循环、播放距离、轨道和音符。MIDI 会直接解析 tempo、轨道、通道、velocity 和音长。玩家播放时由当前手持乐器覆盖歌曲原音色。
八、已知限制
1. Paper 调度精度通常为 1 tick，无法达到客户端 Mod 的毫秒级音频精度。
2. 原版客户端不能把已经开始的声音持续绑定到移动实体，也不能精确控制每个声音实例的淡出包络。
3. 插件不能读取玩家电脑的 MIDI 键盘、延音踏板或任意键盘按下状态。
4. 插件不能复制客户端 Mixin 的第一人称和第三人称骨骼动画。
5. 玩家演奏不会强制同步；怪物合奏采用共享服务器时间轴、声部分配、去重与音量归一化，但网络延迟、TPS 和客户端资源加载仍可能造成轻微不同步。
6. 当前不支持客户端拖放歌曲；管理员需要把歌曲文件放入服务器 songs 目录。