MineFantasia

MineFantasia

欢迎来到MineFantasia!这是一个关于音乐的Minecraft模组。尽情创造,沉浸在你自己想象中的美妙音乐世界吧!

游戏机制

MineFantasia

MineFantasia

简介

欢迎来到 MineFantasia!这是一个为 Minecraft 打造的音乐模组。

本模组目前仍在开发中,但你可以下载它来体验目前已实现的功能。

模组提供了钢琴、合成器、弦乐器、管乐器等多种乐器。只需右键点击对应乐器,即可打开新界面,使用键盘或鼠标开始演奏。

除乐器外,模组还提供了多人合奏系统。这意味着你可以与好友一起进行气势恢宏的器乐合奏。

乐器演奏系统

模组为 Minecraft 添加了乐器演奏系统,并在此基础上加入了种类繁多的乐器。这是模组的核心功能。

乐器演奏界面

当玩家主手持有乐器,或右键点击已放置的乐器时,乐器演奏界面将会打开:

Performance-Screen

演奏区域:包含 21 个方块,从上到下、从左到右排列。每个方块对应键盘按键 Q-U、A-J、Z-M,方块中央显示对应音符的名称。

设置区域:包含 5 个功能按钮,左下角三个,右下角两个。

界面左下角:

共有 3 个按钮,从上到下依次为:升高按钮、当前中心八度编号/升高半音数、降低按钮。

当中间按钮不显示 + 或 - 符号时,显示的是当前中心八度编号。当显示 + 或 - 时,显示的是升高半音数。两者的记录相互独立但又彼此影响。在单次演奏会话中,它们仅分别记录各自的数据,切换时不会重置。

当处于中心八度编号模式时,点击升高/降低按钮,演奏区域内的全部 21 个音符将升高/降低一个八度(12 个半音)。当处于升高半音数模式时,点击升高/降低按钮,全部 21 个音符将升高/降低一个半音。所有变化都会在演奏区域方块中显示。

注意:在中心八度编号模式下,音高升高/降低的范围不会超过/低于乐器记录的最高/最低八度编号。在升高半音数模式下,为确保覆盖所有音符,上下限会扩展一个八度组。

这三个按钮绑定到键盘方向键。上为升高按钮,下为降低按钮,右从当前中心八度编号切换到升高半音数,左从升高半音数切换到当前中心八度编号。

界面右下角:

共有 2 个按钮,从上到下依次为:隐藏演奏方块按钮(带有眼睛图标)和设置按钮(带有齿轮图标)。

点击隐藏演奏方块按钮将隐藏演奏区域内的 21 个方块以及设置按钮,使演奏界面背景完全透明。再次点击即可恢复。

点击设置按钮进入音符编辑模式。你可以通过键盘或鼠标选择需要修改音符名称的方块,在下方的输入框中输入新的音符名称,然后按 Enter 完成修改。

音符配置

由于 Minecraft 原版注册系统的限制,音符名称的命名规则为:八度组编号(八度位置) + 音符名称。

八度组编号指的是 FL Studio 钢琴卷帘中使用的编号。音符名称均为小写字母,音符名称前加 s 表示 #(升号)。例如:5c、6sc。模组不引入降号。

模组将音符分为断奏音符和延音音符。目前,断奏乐器包括:钢琴、卡林巴琴、竖琴。延音乐器包括:所有合成器、小提琴、长笛。

断奏乐器的演奏原理为:点击一个音符时,对应声音播放一次。如果你在演奏界面长按某个音符,对应音符将快速重复。此外,如果你使用资源包替换钢琴音源,请确保单个钢琴声音的长度不超过原音源的长度。否则,可能会造成灾难性的后果!

对于延音乐器:单个音符可演奏的最长时长由音源文件长度决定。模组默认的延音声音最长可持续 8 秒(FL Studio 中 120 BPM 下 4 小节的长度)。

文件系统

在你首次运行模组并进入世界后,模组将在你的 mods 文件夹内生成其专用文件夹。

其文件结构为:

点击展开
📁`minefantasia`
├── 📁`midi`
├── 📁`ins`
│   └── 📁`custom_synth`
│       └── 📄`example.json`
├── 📁`model`
│   └── 📄`player.geo.json`
├── 📁`animation`
│   └── 📄`player.animation.json`
├── 📁`texture`
│   └── 🖼️`player.png`
└── 📄`uuid.json`

其中,midi 文件夹存储你所有的 MIDI 文件(与模型替换无关),ins 文件夹存储所有通用乐器子乐器的 JSON 信息文件,model 文件夹存储你所有的 GeckoLib 模型文件 key.geo.json,animation 文件夹存储你所有的 GeckoLib 模型动画文件 key.animation.json,texture 文件夹存储你所有的 GeckoLib 模型纹理 key.png。

除 midi 和 ins 文件夹外,每个目录中都会生成一个以 player 为 key 的默认 JSON 文件。请不要移除或替换它们。

自定义通用乐器

从版本 0.0.9-beta 开始,模组将逐步为各种乐器添加通用乐器版本。

通用乐器允许玩家自行添加同一乐器类型的不同音色。其演奏界面与内置乐器基本一致,仅在演奏区域上方增加了一个子乐器切换模块。

通用乐器的运作模式为:模组读取基本信息并完成注册 + 玩家导入音源资源包。与注册相关的信息放置在模组文件夹中:mods/minefantasia/ins,在此文件夹内按每个通用乐器细分。

其文件结构为:

点击展开
📁`minefantasia`
└── 📁`ins`
    ├── 📁`General Instrument 1`
    │   ├── 📄`Sub Instrument 1.json`
    │   ├── 📄`Sub Instrument 2.json`
    │   └── ...
    ├── 📁`General Instrument 2`
    │   ├── 📄`Sub Instrument 1.json`
    │   ├── 📄`Sub Instrument 2.json`
    │   └── ...
    └── ...

子乐器 JSON 文件的命名不得与现有模组乐器冲突。例如,对于通用合成器,如果有一个名为 sunshine 的子乐器,其 JSON 文件应命名为 sunshine.json 并放置在 ins/custom_synth 文件夹中。

包含的信息如下:

点击展开
📄`subIns.json`<br>
├── 🗝️`name` 字段:子乐器的名称,用于游戏内部识别。
├── 🗝️`minOctave` 字段:子乐器的最低八度,应大于 0。
├── 🗝️`maxOctave` 字段:子乐器的最高八度,应小于 10。
└── 🗝️`fadeDuration` 字段:仅对延音乐器有效,定义从松开按键到声音完全淡出的时间。

目前新增的通用乐器如下:

点击展开

🎵-通用合成器

未来将适配更多通用乐器。

为方便玩家为通用乐器添加资源,模组工具 MFPackager 已在 GitHub 上发布。该工具可将指定路径下的资源自动打包为模组可识别的资源包,并自动生成子乐器的注册 JSON 文件。

自定义玩家模型

为使模组的乐器演奏系统更加生动,并适配乐器演奏动画,模组添加了基于 GeckoLib 5 的动画系统,并基于最新的 GeckoLib 5,为所有视角替换了 Minecraft 原版玩家模型。当你在演奏乐器时,模型也会做出相应的演奏动作。

模组还重新设计了第一人称视角的摄像机跟随系统。尽管该系统在快速左右移动视角时以及极少数特定状态下仍有待改进,但在大多数情况下,该系统实现了真正的玩家第一人称视角,并保持了良好的操作体验。

支持模型替换,但本模组_不支持_ YSM 模型或其他模组的模型。你应使用 GeckoLib 模型。

模组文件夹下的 model、animation、texture 文件夹以及 uuid.json 与自定义玩家模型相关。

uuid.json 文件是以玩家 UUID 命名的文件,仅在玩家进入世界时生成。其内容包含四个关键记录字段:

点击展开

📄uuid.json
├── 🗝️key 字段:玩家所用模型的关键字,用于注册、标记以及在模组代码内绑定对应玩家模型 ID。不同玩家可以使用相同的 key。
├── 🗝️model 字段:自定义 GeckoLib 玩家模型文件的绝对路径。不需要 .geo.json 后缀。
├── 🗝️texture 字段:自定义玩家 GeckoLib 模型纹理的绝对路径,需要完整文件名。
└── 🗝️animation 字段:自定义 GeckoLib 玩家模型动画文件的绝对路径。不需要 .animation.json 后缀。

为便于模组内部注册和区分模型,所有模型文件名和骨骼都需要以你模型的 key 作为前缀,例如 key.geo.json、key.head 等。

模组对模型骨骼数量或其结构没有严格的具体规定或限制,但请确保你的自定义 GeckoLib 模型按要求包含以下重要骨骼:

点击展开

📄key.geo.json
├── 🦴key.head 骨骼:该骨骼由模组内部用于计算第一人称视角下摄像机的坐标和偏移;它还用于定位模型头部,使其随摄像机旋转。
├── 🦴key.cameraAnchor 骨骼:该骨骼必须仅包含一个 locator,且 locator 的名称必须为 cameraAnchor。其父骨骼建议为模型的根骨骼(key.root)或头部骨骼(key.head)。该骨骼由模组用于计算第一人称视角下摄像机的坐标和偏移。
├── 🦴key.rightHandItem 骨骼:该骨骼必须仅包含一个 locator,且 locator 的名称必须为 rightHandItem。其父骨骼必须是相应的手部骨骼,以使物品能随动画移动。该骨骼由模组内部用于计算所有视角下玩家右手(主手)物品的渲染位置和偏移。
└── 🦴key.leftHandItem 骨骼:该骨骼必须仅包含一个 locator,且 locator 的名称必须为 leftHandItem。其父骨骼必须是相应的手部骨骼,以使物品能随动画移动。该骨骼由模组内部用于计算所有视角下玩家左手(副手)物品的渲染位置和偏移。

模组使用上述 4 个骨骼的 pivot 进行坐标计算,请确保它们的 pivot 值正确。
对于这 4 个骨骼之外的其他骨骼、它们的子骨骼以及骨骼内的元素名称,模组没有严格限制。

请注意,模组当前的玩家模型替换系统不会自动同步多人游戏中各个玩家正在使用的模型,仍需要手动调整 uuid.json 中的内容来更换模型。这意味着如果你想向他人展示你的模型,你需要将你模型的所有 JSON 文件发送给他们,并请他们在自己的设备上手动修改你对应的 uuid.json。

自定义模型动画

模组支持自定义玩家模型动画。由于所有动画名称都在模组代码中硬编码,你的自定义模型动画名称必须与模组中硬编码的动画名称一致。
目前支持的动画及其命名要求如下:

点击展开

📄key.animation.json
├── 🎬key.walk:玩家模型行走时播放的动画。
├── 🎬key.idle:玩家模型闲置时播放的动画。
├── 🎬key.crouch:玩家模型蹲下时播放的动画。
├── 🎬key.swim:玩家模型游泳时播放的动画。播放此动画时不显示手持物品。由于 Minecraft 原版在此情况下会将玩家碰撞箱尺寸改为 0.6x0.6x0.6,为使玩家模型头部能正常旋转并正确应用摄像机坐标,在制作此动画时,完成整体模型动画后,在 BlockBench 的 Animation 标签页中移动整个模型(key.root),将头部骨骼 key.head 的 pivot 对齐到坐标 [0, 6.4, 0],并确保 key.root 骨骼没有 Rotation 偏移。
├── 🎬key.fly:玩家模型使用鞘翅飞行时播放的动画。播放此动画时不显示手持物品。由于 Minecraft 原版在此情况下会将玩家碰撞箱尺寸改为 0.6x0.6x0.6,为使玩家模型头部能正常旋转并正确应用摄像机坐标,在制作此动画时,完成整体模型动画后,在 BlockBench 的 Animation 标签页中移动整个模型(key.root),将头部骨骼 key.head 的 pivot 对齐到坐标 [0, 6.4, 0],并确保 key.root 骨骼没有 Rotation 偏移。
├── 🎬key.piano:玩家模型在钢琴上演奏时播放的整体动画,如姿势变化。
├── 🎬key.kalimba:玩家模型在卡林巴琴上演奏时播放的整体动画,如姿势变化。
├── 🎬key.harp:玩家模型在竖琴上演奏时播放的整体动画,如姿势变化。
├── 🎬key.violin:玩家模型在小提琴上演奏时播放的整体动画,如姿势变化。
├── 🎬key.synth:玩家模型在所有类型的合成器上演奏时播放的整体动画,如姿势变化。
├── 🎬key.banjo:玩家模型在班卓琴上演奏时播放的整体动画,如姿势变化。
├── 🎬key.drumKit:玩家模型在架子鼓上演奏时播放的整体动画,如姿势变化。
├── 🎬key.bass:玩家模型在贝斯上演奏时播放的整体动画,如姿势变化。
├── 🎬key.guitar:玩家模型在吉他上演奏时播放的整体动画,如姿势变化。
├── 🎬key.pianoPlay:在演奏界面打开状态下于钢琴上演奏时按下音符触发的瞬发动画,如手部动作。
├── 🎬key.kalimbaPlay:在演奏界面打开状态下于卡林巴琴上演奏时按下音符触发的瞬发动画,如手部动作。
├── 🎬key.harpPlay:在演奏界面打开状态下于竖琴上演奏时按下音符触发的瞬发动画,如手部动作。
├── 🎬key.violinPlay:在演奏界面打开状态下于小提琴上演奏时按下音符触发的瞬发动画,如手部动作。
├── 🎬key.synthPlay:在演奏界面打开状态下于合成器上演奏时按下音符触发的瞬发动画,如手部动作。
├── 🎬key.banjoPlay:在演奏界面打开状态下于班卓琴上演奏时按下音符触发的瞬发动画,如手部动作。
├── 🎬key.drumKitPlay:在演奏界面打开状态下于架子鼓上演奏时按下音符触发的瞬发动画,如手部动作。
├── 🎬key.bassPlay:在演奏界面打开状态下于贝斯上演奏时按下音符触发的瞬发动画,如手部动作。
└── 🎬key.guitarPlay:在演奏界面打开状态下于吉他上演奏时按下音符触发的瞬发动画,如手部动作。

关于 key.swim 和 key.fly 动画为何不能修改 key.root 骨骼的 Rotation 偏移的补充说明:实际上,如果添加基于模型根骨骼的旋转偏移,GeckoLib 对玩家头部骨骼跟随摄像机视角的旋转计算可能会发生偏差甚至失效。具体原因目前尚不清楚,因此目前只能在动画制作过程中避免直接修改根骨骼的旋转偏移。

由于个人美术能力有限,默认模型没有某些乐器的演奏动画,因此也未经充分测试和验证。但模组仍保留了对这些动画的调用。你可以在自定义模型中使用上述动画名称,为演奏相应乐器添加替换动画。如遇任何问题,可以在本模组的 GitHub 仓库 issues 页面 提交 issue。

MIDI 系统

模组实现了读取本地 MIDI 文件,并可使用模组内置乐器音源播放它们。

所有 MIDI 文件均存储在 mods/minefantasia/midi 文件夹中:

点击展开

📁minefantasia
└──📁midi

MIDI 文件后缀必须为 .mid。模组支持 format0 和 format1 MIDI 文件的单轨与多轨同时播放,以及 format2 MIDI 文件的单轨播放。

MIDI 播放盒及其界面

在模组中,MIDI 文件播放通过模组的方块实体:MIDI 播放盒实现。其界面如下所示:

MIDI Playbox

MIDI 播放盒界面有三个选择区域,从左到右依次为:

乐器

此区域默认显示模组中的所有乐器。在此区域中,你可以选择用于播放音轨的模组乐器。此区域一次只能选择一种乐器。

MIDI 文件

此区域会自动读取你 mods/minefantasia/midi 文件夹中存储的所有 MIDI 文件的名称并显示。在此区域中,你可以选择要播放的 MIDI 文件。选择后,模组会自动解析该 MIDI 文件,并在音轨区域中依序显示该 MIDI 文件的所有音轨。此区域一次只能选择一个 MIDI 文件。

音轨

在你选择 MIDI 文件后,此区域会读取所选 MIDI 文件并依序显示其中的所有音轨。在此区域中,你可以一次选择多个音轨。

每个区域下方都有由左右箭头指示的翻页按钮。每个区域默认显示的信息条目数为 5。

此外,MIDI 播放盒界面有三个按钮,从左到右依次为:

确认

此按钮专门用于在红石信号触发前设置信息,例如设置演奏乐器和演奏音轨。如果未在播放时点击,它不会播放所选音轨。要播放,你可以使用红石信号触发。如果在播放时点击,系统将检查乐器选择等选项是否已更改。如果已更改,它将停止播放并立即以新配置开始播放。

播放

此按钮用于在选择演奏乐器和音轨后立即播放所选音轨。

请注意:如果你未选择任何乐器或音轨就点击播放,MIDI 播放盒会将相关信息设置为空。

停止

此按钮用于立即停止当前 MIDI 播放盒的播放,并清除之前的播放信息,如演奏乐器和音轨。如果你不点击此按钮,信息在 MIDI 序列正常播放完毕后不会丢失。点击此按钮后,你需要重新配置 MIDI 播放盒。

界面左上角还有两个按钮,从上到下依次为:

网络同步播放按钮

当此按钮激活时,它会变为绿色,并将当前正在播放的 MIDI 文件播放给服务器上的所有玩家。此同步功能在每个客户端上独立。这意味着即使其他玩家没有你正在播放的 MIDI 文件,他们仍然能听到音乐。此按钮可在播放期间随时调整。

释放控制按钮

此按钮默认显示为红色,表示当前播放盒实体被你占用。点击此按钮将释放你对播放盒实体的所有权,播放界面将关闭,其他玩家随后可以右键点击打开界面并使用播放盒。

MIDI 播放盒控制

MIDI 播放盒支持红石控制。与普通方块一样,它可以传输红石信号,但它本身不是红石组件。

MIDI 播放盒接收红石脉冲信号。每接收一个脉冲信号,它将切换一次播放状态。

单个 MIDI 播放盒在多人模式下为整个服务器共享一个实体。为避免不同客户端之间的使用冲突,MIDI 播放盒实现了玩家绑定。首次放置后,它会自动绑定第一个打开播放界面的玩家。在此玩家主动释放它或方块被破坏并替换之前,服务器上的其他玩家无法右键点击打开播放界面,但仍可通过红石控制播放盒的播放状态。

自定义音源资源包

如果你不喜欢模组中某个乐器的默认音源,并且你有途径和能力获取音源(例如自行采样乐器),你可以自行替换相关资源包中的音源文件。

模组的音源使用 Ogg 格式。对 Ogg 文件的要求(如音符时长、音符命名格式等)已在上文音符配置部分详细说明,此处不再赘述。

安装

模组提供两个安装版本:完整版和精简版。

完整版:包含模组的所有资源文件。资源文件无法替换。文件体积较大,适合不想折腾的玩家。

精简版:不包含模组的乐器声音文件。你需要手动加载指定的资源包才能演奏乐器。模组文件体积非常小,适合服务器或希望自定义客户端乐器声音的玩家。注意:如果你未按照模组的资源格式添加对应乐器的资源包,演奏乐器或同步其他玩家 MIDI 播放盒的音符时将不会发出对应的乐器声音。

完整版和精简版均不会影响多人游戏功能。

从版本 0.0.9-beta 开始,模组中的所有乐器声音已替换为来自 CC0 许可的真实乐器音源或使用 MIT 许可的 FluidR3_GM 乐器采样,且模组完整版已正式开放下载。

  1. 从 GeckoLib 的 GitHub 仓库、Modrinth 等下载对应版本的 GeckoLib-NeoForge,并将下载的 jar 文件放入你的 mods 文件夹。
  2. 从右侧 Releases 部分或 Modrinth 等下载本模组的最新版本,并将下载的 jar 文件放入你的 mods 文件夹。
  3. 如果你下载的是精简版,可以前往 Modrinth 下载相关资源包。

版权声明

Copyright © 2026 Seikai-Takenawa. 本模组(MineFantasia)保留所有权利。

允许的行为:

  • 模组的功能性行为,例如:模型替换、动画替换、通过编辑资源包修改模组中的乐器音源等。
  • 你可以录制模组游玩内容并在社交媒体上分享。
  • 你可以与好友分享本模组的副本,仅限个人非商业用途。
  • 你可以在你的 Minecraft 客户端或非商业服务器上使用本模组。

禁止的行为:

  • 禁止进行上述允许范围之外的任何修改、逆向工程、反编译或创建本模组的衍生作品。
  • 禁止在任何其他网站或平台公开发布或重新上传本模组。
  • 禁止将本模组用于任何商业目的(包括但不限于出售、作为付费整合包/服务器的一部分等)。
  • 任何未明确声明为允许的行为。

常见问题

Q1. 我如何获得乐器?
A1. 目前,乐器无法通过合成或合成配方获得。在非创造模式下,模组的钢琴会自然生成在模组结构 音乐厅 的中心,且不可破坏。其他乐器只能从 音乐厅 后台区域的箱子中随机获得。

Q2. 在多人游戏中,我听不到其他玩家演奏乐器。
A2. 在多人游戏中,乐器演奏系统仅将演奏信息同步给与演奏乐器的玩家处于同一区块的玩家。

Q3. 我在第一人称视角下能透视方块。
A3. 模组重构了第一人称视角的摄像机跟随系统。摄像机现在始终位于玩家模型头部的 cameraAnchor 处。因此,当玩家站在非常靠近前方方块的位置低头时,摄像机位置可能最终位于玩家碰撞箱之外,导致透视问题。此外,建模者错误配置 cameraAnchor 骨骼的 pivot 也可能导致摄像机坐标超出玩家碰撞箱。目前此问题尚无完美解决方案。建议将替换玩家模型的头部设计得更小,并将头部和 cameraAnchor 骨骼的 pivot 调整到合适位置,以避免移动时头部超出玩家碰撞箱。

Q4. 某些物品在玩家手上显示的大小、角度等在各种视角下看起来很奇怪。
A4. 替换整个原版玩家模型系统意味着原版物品渲染逻辑不再适用于替换后的 GeckoLib 模型。此问题正在适配和改进中。

Q5. 为什么小提琴没有琴弓?
A5. 为小提琴添加琴弓会影响小提琴的使用和演奏逻辑,也会使演奏小提琴时的模型动画更加复杂。个人美术能力有限,实在不知道如何处理这部分。(其实另一个原因是懒。总之,大家暂时把它当作普通乐器就好﹙ˊ_>ˋ﹚)

Q6. MIDI 播放盒速度不正确/卡顿/加速。
A6. 由于模组使用 Minecraft 内置的 tick 系统进行计时,其精度受服务器/客户端 tick 速率波动的影响。

Q7. 会支持旧版本吗?未来会有 Forge/Fabric 版本吗?
A7. 由于个人开发精力有限,目前没有 Forge/Fabric 版本的计划。模组使用 GeckoLib 5,因此最低支持版本为 1.21.5。

Q8. 我能获取源代码来为模组添加自定义乐器和功能吗?
A8. 模组目前不开源,感谢你的理解!不过,你可以通过下载模组的精简版并替换资源包中特定乐器的音源来实现类似功能。模组未来也将为各种乐器添加通用乐器版本。