From df3519ebc5916d41c97f2d8564d1cab9887d48ae Mon Sep 17 00:00:00 2001 From: Eilles Date: Tue, 21 Jul 2026 00:11:02 +0800 Subject: [PATCH] =?UTF-8?q?=E6=8F=90=E4=BA=A4=E4=B8=80=E9=83=A8=E5=88=86?= =?UTF-8?q?=E6=96=B0=E7=9A=84=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../commands_to_structure/__init__.py | 2 +- README.md | 55 ++++-- README_EN.md | 58 +++--- docs/内置插件相关/MC指令结构/生成功能文档.md | 183 ++++++++++++++++++ .../MC指令结构/生成文件的使用说明.md | 60 ++++++ pyproject.toml | 4 - 6 files changed, 321 insertions(+), 41 deletions(-) create mode 100644 docs/内置插件相关/MC指令结构/生成功能文档.md create mode 100644 docs/内置插件相关/MC指令结构/生成文件的使用说明.md diff --git a/Musicreater/builtin_plugins/commands_to_structure/__init__.py b/Musicreater/builtin_plugins/commands_to_structure/__init__.py index fcf2eb7..fa3eabd 100644 --- a/Musicreater/builtin_plugins/commands_to_structure/__init__.py +++ b/Musicreater/builtin_plugins/commands_to_structure/__init__.py @@ -1,7 +1,7 @@ # -*- coding: utf-8 -*- """ -音·创 v3 内置的 Minecraft 结构生成插件 +音·创 v3 内置的 Minecraft 指令结构生成插件 """ """ diff --git a/README.md b/README.md index c1a1b53..a001128 100644 --- a/README.md +++ b/README.md @@ -54,21 +54,42 @@ ## 安装 🔳 -- 使用 pypi +使用 pypi 直接安装 - ```bash +- ```bash pip install --upgrade Musicreater ``` -- 如果无法更新至最新，可以尝试使用 pypi 的默认源： +如果因第三方源同步较慢，无法更新至最新，可以尝试使用 pypi 的默认源： - ```bash +- ```bash pip install --upgrade -i https://pypi.python.org/simple Musicreater ``` -- 采用最新的开发分支下的滚动更新： +如果需要使用一些内置插件，则可以在库名称后面加上对应的可选依赖标签，现有的插件和可选依赖标签对应如下： - ```bash +- | 内置插件 | 插件功能 | 可选依赖标签 | 说明 | + | -------- | -------- | ------------ | ---- | + | Midi 读取 | 读取 MIDI 文件，导入音轨或全曲 | `midi` | 未来可能支持 MIDI 写入 | + | Minecraft 指令结构生成 | 导出乐曲，创建 Minecraft 指令方块存储的音乐结构 | `structure` | 当前支持 `.mcstructure`、`.bdx` 格式直接导出和 `.mcpack` 附加包格式的导出，具体导出格式请查阅[插件文档](./docs/内置插件相关/MC指令结构/) | + | 音乐预览 | 以 Minecraft 音效直接输出音乐的波形声音文件
导入自制的 Minecraft 音乐资源包并解析，并输出预览结果波形（实验性） | `preview`
`preview-advanced` | 输出为 `.wav` 格式的音乐文件，用于预览音乐的播放效果
需与 preview 标签一并安装 | + +除了内置插件有对应的可选依赖标签外，还有另外两组可选依赖： + +- | 标签 | 说明 | + | ------------ | ---- | + | `full` | 添加所有可选依赖，即包含所有插件的依赖项 | + | `dev` | 添加开发依赖，包括一些开发或测试功能时所用插件、以及 `full` 标签中的所有插件的依赖项。 | + +也就是说，如果需要使用 midi 读取和 Minecraft 指令结构生成，则需要安装 `midi` 和 `structure` 标签所对应的依赖项。例如： + +- ```bash + pip install "Musicreater[midi,structure]" + ``` + +参与开发，可以采用最新的开发分支下的滚动更新： + +- ```bash pip install "git+https://gitee.com/TriM-Organization/Musicreater.git@develop[dev]" ``` @@ -80,20 +101,30 @@ ## 作者 ✒ -**金羿 Eilles**：我的世界基岩版指令作者，个人开发者，B 站不知名 UP 主。 +以下人名依照对于各项的参与之序排布。 + +### 项目策划 + +**金羿 Eilles**、**玉衡Alioth Alioth** + +### 软件开发 + +**金羿 Eilles**、**玉衡Alioth Alioth**、**鱼旧梦 ElapsingDreams** + +### 资源素材 + +**Charlie_Ping “查理平”**、**偷吃不是Touch Touch**、**金羿 Eilles** -**玉衡Alioth Alioth**：我的世界基岩版玩家，喜欢编程和音乐，学生。 -**偷吃不是Touch Touch**：我的世界基岩版指令制作者，提供测试支持 ## 致谢 🙏 -本致谢列表排名无顺序。 +本致谢列表按照其提交的内容生效之时间依次排序。 - 感谢 **昀梦**\ 找出指令生成错误 bug 并指正 - 感谢由 **Charlie_Ping “查理平”** 带来的 BDX 文件转换参考，以及 MIDI-我的世界对应乐器 参考表格 - 感谢由 **[CMA_2401PT](https://github.com/CMA2401PT)** 为我们的软件开发的一些方面进行指导，同时我们参考了他的 BDXworkshop 作为 BDX 结构编辑的参考 -- 感谢由 **[Dislink Sforza](https://github.com/Dislink) “断联·斯福尔扎”**\ 带来的 midi 音色解析以及转换指令的算法，我们将其改编并应用；同时，感谢他的[网页版转换器](https://dislink.github.io/midi2bdx/)给我们的开发与更新带来巨大的压力和动力，让我们在原本一骑绝尘的摸鱼道路上转向开发。 +- 感谢由 **[Dislink Sforza](https://github.com/Dislink) “断联·斯福尔扎”**\ 的[网页版转换器](https://dislink.github.io/midi2bdx/)给我们的开发与更新带来巨大的压力和动力，让我们在原本一骑绝尘的摸鱼道路上转向开发。 - 感谢 **Mono**\ 反馈安装时的问题，辅助我们找到了视窗操作系统下的兼容性问题；感谢其反馈延迟播放器出现的重大问题，让我们得以修改全部延迟播放错误；尤其感谢他对于我们的软件的大力宣传 - 感谢 **Ammelia “艾米利亚”**\ 敦促我们进行新的功能开发，并为新功能提出了非常优秀的大量建议，以及提供的 BDX 导入测试支持，为我们的新结构生成算法提供了大量的实际理论支持 - 感谢 **[神羽 “SnowyKami”](https://www.sfkm.me/)** 对我们项目的支持与宣传，非常感谢他为我们提供的服务器！ @@ -131,7 +162,7 @@ “Minecraft”是 Mojang Synergies AB 的商标，此项目中所有对于“我的世界”、“Minecraft”等相关称呼均为必要的介绍性使用 -- 上文提及的 网易 公司，指代的是在中国大陆运营《我的世界：中国版》的上海网之易璀璨网络科技有限公司 +- 上文提及的 网易 公司，指代的是在中国大陆运营《我的世界：中国版》的上海网之易吾世界网络科技有限公司 NOT AN OFFICIAL MINECRAFT PRODUCT. diff --git a/README_EN.md b/README_EN.md index 4751650..33db2ef 100644 --- a/README_EN.md +++ b/README_EN.md @@ -35,7 +35,7 @@ [简体中文 🇨🇳](README.md) | English🇬🇧 -**Notice that the localizations of documents may probably NOT be up-to-date. The original document is in Chinese.** +> **NOTICE** The localizations of documents may probably NOT be up-to-date. The original document is in Chinese. ## Introduction🚀 @@ -43,11 +43,11 @@ Musicreater is a cost free, open-source, highly optimized library designed for e Welcome to join our QQ group: [861684859](https://jq.qq.com/?_wv=1027&k=hpeRxrYr) -> **NOTICE** The project inside this repository is only the support library, which is mainly for the developers of music related software for _Minecraft: Bedrock Edition_. +> **NOTICE** The project inside this repository is only a supportive library, which is mainly for the developers of music related software for _Minecraft: Bedrock Edition_. > > The _Bedrock Edition music convertor_ which is for common users is in [Linglun Converter](../../../Linglun-Converter). [Archived] > -> We are also developing a _BE music editor_ (sth like a digital audio workstation): [Linglun](../../../LinglunStudio) +> We are also developing a _BE music editor_, a new _Minecraft_ digital audio workstation(DAW): [Linglun](../../../LinglunStudio) ## Installation 🔳 @@ -73,32 +73,42 @@ Commands such as `python`、`pip` could be changed to some like `python3` or `pi [仓库 API 文档](./docs/%E5%BA%93%E7%9A%84%E7%94%9F%E6%88%90%E4%B8%8E%E5%8A%9F%E8%83%BD%E6%96%87%E6%A1%A3.md) -### Authors ✒ +## Authors ✒ -**Eilles (金羿)**：A student, individual developer, unfamous Bilibili UPer, which knows a little about commands in _Minecraft: Bedrock Edition_ +The names are in the order of each person's first contributing time of each part of the project. -**Alioth (玉衡Alioth)**: A student, player of _Minecraft: Bedrock Edition_, which is a fan of music and programming. +### Project Managers + +**Eilles (菀 金羿)**, **Alioth (玉衡Alioth)** + +### Developers + +**Eilles (菀 金羿)**, **Alioth (玉衡Alioth)**, **ElapsingDreams (鱼旧梦)** + +### Resource Providers + +**Charlie_Ping**, **Touch (偷吃不是Touch)**, **Eilles (菀 金羿)** -**Touch (偷吃不是 Touch)**: A man who is good at using command(s) in _Minecraft: Bedrock Edition_, who supported us of debugging and testing program and algorithm ## Acknowledgements 🙏 -This list is not in any order. +We thank: -- Thank _昀梦_\ for finding and correcting the bugs in the commands that _Musicreater_ generated. -- Thank _Charlie_Ping “查理平”_ for the bdx convert function for reference, and the reference chart that's used to convert the mid's instruments into Minecraft's instruments. -- Thank _[CMA_2401PT](https://github.com/CMA2401PT)_ for BDXWorkShop for reference of the .bdx structure's operation, and his guidance in some aspects of our development. -- Thank _[Dislink Sforza](https://github.com/Dislink) “断联·斯福尔扎”_ \ for his midi analysis algorithm brought to us, we had adapted it and made it applied in one of our working method; Also, thank him for the [WebConvertor](https://dislink.github.io/midi2bdx/) which brought us so much pressure and power to develop as well as update our projects better, instead of loaf on our project. -- Thank _Mono_\ for reporting problems while installing -- Thank _Ammelia “艾米利亚”_\ for urging us to develop new functions, and put forward a lot of excellent suggestions for new functions, as well as the BDX file's importing test support provided, which has given a lot of practical theoretical support for our new Structure Generating Algorithm -- Thank _[神羽](https://gitee.com/snowykami) “[SnowyKami](https://github.com/snowyfirefly)”_ for supporting and promoting our project, and also thanks him for his server which given us to use for free. -- Thank _指令师\_苦力怕 “playjuice123”_\ for finding bugs within our code, and noticed us to repair a big problem. -- Thank _雷霆_\ for his annoying and provoking operations which may awake some problems within the program by chance and reminding us to repair. -- Thank _小埋_\ for reporting the empty add-on packs title and description problem. --
Thank 油炸 <QQ2836146704> for inspiring us to constantly develop something new.The groupmate on the picture was saying that our convert-QQ-bot had once brought him great convinience but now it closed down by some reason so he was feeling regretful."It was once, a convert-QQ-bot is just in front my eyes"
"Until lose, I finally know cannot chase back what I needs"
-- Thank _雨_\ for give us report that under the new `execute` command format that the scoreboard player's add-on packs cannot play correctly. -- Thank _梦幻duang_\ for providing us with his knowlodeg of the command format in Minecraft: Java Edition Version 1.12.2. -- Thank [_Open Note Block Studio_](https://github.com/OpenNBS/NoteBlockStudio)'s Project for giving us the power and energy of continual developing. +- _昀梦_\ for finding and correcting the bugs in the commands that _Musicreater_ generated. +- _Charlie_Ping “查理平”_ for the bdx convert function for reference, and the reference chart that's used to convert the mid's instruments into Minecraft's instruments. +- _[CMA_2401PT](https://github.com/CMA2401PT)_ for BDXWorkShop for reference of the .bdx structure's operation, and his guidance in some aspects of our development. +- _[Dislink Sforza](https://github.com/Dislink) “断联·斯福尔扎”_ \ for the [WebConvertor](https://dislink.github.io/midi2bdx/) which brought us so much pressure and power to develop as well as update our projects better, instead of loaf on our project. +- _Mono_\ for reporting problems while installing +- _Ammelia “艾米利亚”_\ for urging us to develop new functions, and put forward a lot of excellent suggestions for new functions, as well as the BDX file's importing test support provided, which has given a lot of practical theoretical support for our new Structure Generating Algorithm +- _[神羽](https://gitee.com/snowykami) “[SnowyKami](https://github.com/snowyfirefly)”_ for supporting and promoting our project, and also thanks him for his server which given us to use for free. +- _指令师\_苦力怕 “playjuice123”_\ for finding bugs within our code, and noticed us to repair a big problem. +- _雷霆_\ for his annoying and provoking operations which may awake some problems within the program by chance and reminding us to repair. +- _小埋_\ for reporting the empty add-on packs title and description problem. +-
油炸 <QQ2836146704> for inspiring us to constantly develop something new.The groupmate on the picture was saying that our convert-QQ-bot had once brought him great convinience but now it closed down by some reason so he was feeling regretful."It was once, a convert-QQ-bot is just in front my eyes"
"Until lose, I finally know cannot chase back what I needs"
+- _雨_\ for give us report that under the new `execute` command format that the scoreboard player's add-on packs cannot play correctly. +- _梦幻duang_\ for providing us with his knowlodeg of the command format in Minecraft: Java Edition Version 1.12.2. +- the project of [_Open Note Block Studio_](https://github.com/OpenNBS/NoteBlockStudio) for giving us the power and energy of continual developing. +- _启航与凡凡_\ for pointing out the decoding error of _Musicreater v2_'s music sequence file, and the way to fix. > Thanks for the support and help of a lot of groupmates > If you have given contributions but have not been in the list, please contact us! @@ -123,8 +133,8 @@ NOT APPROVED BY OR ASSOCIATED WITH NETEASE. 此项目不隶属或关联于 Mojang Studios 或 微软 -此项目亦不隶属或关联于 网易 相关 +此项目亦不隶属或关联于 网易 “Minecraft”是 Mojang Synergies AB 的商标，此项目中所有对于“我的世界”、“Minecraft”等相关称呼均为必要的介绍性使用 -- 上文提及的 网易 公司，指代的是在中国大陆运营《我的世界：中国版》的上海网之易璀璨网络科技有限公司 +- 上文提及的 网易 公司，指代的是在中国大陆运营《我的世界：中国版》的上海网之易吾世界网络科技有限公司 diff --git a/docs/内置插件相关/MC指令结构/生成功能文档.md b/docs/内置插件相关/MC指令结构/生成功能文档.md new file mode 100644 index 0000000..940d620 --- /dev/null +++ b/docs/内置插件相关/MC指令结构/生成功能文档.md @@ -0,0 +1,183 @@ +

Minecraft 指令结构生成插件

+ + +

+ +

+ +

生成文件的结构

+ +**此开发文档已经过时** + +> **请明确**：该文档自 音·创 v2 版本停止开发后不再更新，本插件之相关功能从移植到 v3 之后已有变化。因此，此处文档仅作引用和参考，后续更新后会移除这句话。 + +# 生成文件结构 + +## 名词解释 + +|名词|解释|备注| +|--------|-----------|----------| +|指令区|一个用于放置指令系统的区域，通常是常加载区。|常见于服务器指令系统、好友联机房间中| +|指令链（链）|与链式指令方块不同，一个指令链通常指代的是一串由某种非链式指令方块作为开头，后面连着一串链式指令方块的结构。|通常的链都应用于需要“单次激活而多指令”的简单功能| +|起始块|链最初的那个非链式指令方块。|此方块为脉冲方块或重复方块皆可| +|指令系统（系统）|指令系统通常指的是，由一个或多个指令链以及相关红石机构相互配合、一同组成的，为达到某种特定的功能而构建的整体结构。|通常的系统都应用于需要“综合调配指令”的复杂功能。可由多个实现不同功能的模块构成，不同系统之间可以相互调用各自的模块。| +|游戏刻（刻）|游戏的一刻是指《我的世界》的游戏进程循环运行一次所占用的时间。（[详见《我的世界》中文维基](https://zh.minecraft.wiki/wiki/%E5%88%BB#%E6%B8%B8%E6%88%8F%E5%88%BB)）。指令方块的延迟功能（即指令方块的“延迟刻数”设置项，此项的名称被误译为“已选中项的延迟”）的单位即为 `1` 游戏刻。|正常情况下，游戏固定以每秒钟 `20` 刻的速率运行。但是，由于游戏内的绝大多数操作都是基于游戏进程循环而非现实中的时间来计时并进行的，一次游戏循环内也许会发生大量的操作，更多情况下，一秒对应的游戏刻会更少。| +|红石刻|一个红石刻代表了两个游戏刻。（[详见《我的世界》中文维基](https://zh.minecraft.wiki/wiki/%E5%88%BB#%E7%BA%A2%E7%9F%B3%E5%88%BB)）。红石中继器会带来 `1~4` 个红石刻的延迟，其默认的延迟时间为 `1` 红石刻。|正常情况下，红石信号在一个红石电路中传输回存在 $\frac{1}{10}$ 秒左右的延迟。但是，同理于游戏刻，一秒对应的红石刻是不定的。| + +## 播放器 + +本插件生成的文件可以采用多种方式播放，一类播放方式，我们称其为**播放器**，例如**延迟播放器**和**计分板播放器**等等，以后推出的新的播放器，届时也会在此处更新。 + +为什么要设计这么多播放器？是为了适应不同的播放环境需要。通常情况下，一个音乐中含有多个音符，音符与音符之间存在间隔，这里就产生了不一样的，实现音符间时间间隔的方式。而不同的应用环境下，又会产生不一样的要求。接下来将对不同的播放器进行详细介绍。 + +### 参数释义 + +|参数|说明|备注| +|--------|-----------|----------| +|`ScBd`|指定的计分板名称|| +|`Tg`|播放对象|选择器或玩家名| +|`x`|音发出时对应的分数值|| +|`InstID`|声音效果ID|不同的声音ID可以对应不同的乐器，详见转换[乐器对照表](../../../../Musicreater/blob/master/docs/%E8%BD%AC%E6%8D%A2%E4%B9%90%E5%99%A8%E5%AF%B9%E7%85%A7%E8%A1%A8.md)| +|`Ht`|播放点对玩家的距离|通过距离来表达声音的响度。以 $S$ 表示此参数`Ht`，以Vol表示音量百分比，则计算公式为： $S = \frac{1}{Vol}-1$ | +|`Vlct`|原生我的世界中规定的播放力度|这个参数是一个谜一样的存在，似乎它的值毫不重要……因为无论这个值是多少，我们听起来都差不多。当此音符所在MIDI通道为第一通道，则这个值为 $0.7$ 倍MIDI指定力度，其他则为 $0.9$ 倍。| +|`Ptc`|音符的音高|这是决定音调的参数。以 $P$ 表示此参数， $n$ 表示其在MIDI中的编号， $x$ 表示一定的音调偏移，则计算公式为： $P = 2^\frac{n-60-x}{12}$。之所以存在音调偏移是因为在《我的世界》中，不同的[乐器存在不同的音域](https://zh.minecraft.wiki/wiki/%E9%9F%B3%E7%AC%A6%E7%9B%92#%E4%B9%90%E5%99%A8)，我们通过音调偏移来进行调整。| + +### 播放器内容 + +1. 计分板播放器 + + 计分板播放器是一种传统的《我的世界》音乐播放方式。通过对于计分板加分来实现播放不同的音符。一个很简单的原理，就是**用不同的计分板分值对应不同的音符**，再通过加分，来达到那个分值，即播放出来。 + + 在**音·创 v2**中，用来达到这种效果的指令是这样的： + + ```mcfunction + execute @a[scores={ScBd=x}] ~ ~ ~ playsound InstID @s ^ ^ ^Ht Vlct Ptc + ``` + + + + 后四个参数决定了这个音的性质，而前两个参数仅仅是为了决定音播放的时间。 + +2. 延迟播放器 + + 延迟播放器是通过《我的世界》游戏中，指令方块的设置项“延迟刻数”来达到定位音符的效果。**将所有的音符依照其播放时距离乐曲开始时的时间（毫秒），放在一个序列内，再计算音符两两之间对应的时间差值，转换为《我的世界》内对应的游戏刻数之后填入指令方块的设置中。** + + 在**音·创 v2**中，由于此方式播放的音乐不需要用计分板，所以播放指令是这样的： + + ```mcfunction + execute Tg ~ ~ ~ playsound InstID @s ^ ^ ^Ht Vlct Ptc + ``` + + + 其中后四个参数决定了这个音的性质。 + + 由于这样的延迟数据是依赖于指令方块的设置项，所以使用这种播放器所转换出的结果仅可以存储在包含方块NBT信息及方块实体NBT信息的结构文件中，或者直接输出至世界。 + +3. 中继器播放器 + + 中继器播放器是一种传统的《我的世界》红石音乐播放方式，利用游戏内“红石组件”之“红石中继器”以达到定位音符之用。**但是，中继器的延迟为1红石刻** + + +## 文件格式 + +1. 附加包格式（`.mcpack`） + + 使用附加包格式导出音乐，若采用计分板 播放器，则音乐会以指令函数文件（`.mcfunction`）存储于附加包内。而若为延迟或中继器播放器，则音乐回以结构文件（`.mcstructure`）存储。在所生成的附加包中，函数文件的存储结构应为： + + - `functions\` + - `index.mcfunction` + - `stop.mcfunction` + - `mscply\` + - `progressShow.mcfunction` + - `track1.mcfunction` + - `track2.mcfunction` + - ... + - `trackN.mcfunction` + - `structures\` + - `XXX_main.mcstructure` + - `XXX_start.mcstructure` + - `XXX_reset.mcstructure` + - `XXX_pgb.mcstructure` + + 如图，其中，`index.mcfunction`文件、`stop.mcfunction`文件和`mscply`文件夹存在于函数目录的根下；在`mscply`目录中，包含音乐导出的众多音轨播放文件（`trackX.mcfunction`）。同时，若使用计分板播放器生成此包时启用生成进度条，则会包含`progressShow.mcfunction`文件。若选择延迟或中继器播放器，则会生成`structures`目录以及相关`.mcstructure`文件，其中`mian`表示音乐播放用的主要结构；`start`是用于初始化播放的部分，仅包含一个指令方块即起始块；`reset`和`pgb`仅在启用生成进度条时出现，前者用于重置临时计分板，后者用于显示进度条。 + + `index.mcfunction`用于开始播放： + + 1. 若为计分板播放器，则其中包含打开各个音轨对应函数的指令，以及加分指令，这里的加分，是将**播放计分板的值大于等于 $1$ 的所有玩家**的播放计分板分数增加 $1$。同时，若生成此包时选择了自动重置计分板的选项，则会包含一条重置计分板的指令。 + + 2. 若为延迟或中继器播放器，则其中的指令仅包含用以正确加载结构的`structure`指令。 + + `stop.mcfunction`用于终止播放： + + 1. 若为计分板播放器，则其中包含将**全体玩家的播放计分板**重置的指令。 + + 2. 若为延迟或中继器播放器，则其中包含**停用命令方块**和**启用命令方块**的指令。~~然鹅实际上对于播放而言是一点用也没有~~ + + > 你知道吗？音·创的最早期版本“《我的世界》函数音乐生成器”正是用函数来播放，不过这个版本采取的读入数据的形式大有不同。 + +2. 生成结构的方式 + + 无论是音·创生成的是何种结构，`MCSTRUCTURE`还是`BDX`，都会依照此处的格式来生成。此处我们想说明的结构的格式不是结构文件存储的格式，而是结构导出之后方块摆放的方式。结构文件存储的格式这一点，在各个《我的世界》开发的相关网站上都可能会有说明。 + + 考虑到进行《我的世界》游戏开发时，为了节约常加载区域，很多游戏会将指令区设立为一种层叠式的结构。这种结构会限制每一层的指令系统的高度，但是虽然长宽也是有限的，却仍然比其纵轴延伸得更加自由。 + + 所以，结构的生成形状依照给定的高度和内含指令的数量决定。其 $Z$ 轴延伸长度为指令方块数量对于给定高度之商的向下取整结果的平方根的向下取整。用数学公式的方式表达，则是： + + $$ MaxZ = \left\lfloor\sqrt{\left\lfloor{\frac{NoC}{MaxH}}\right\rfloor}\right\rfloor $$ + + 其中，$MaxZ$ 即生成结构的$Z$轴最大延伸长度，$NoC$ 表示链结构中所含指令方块的个数，$MaxH$ 表示给定的生成结构的最大高度。 + + 我们的结构生成器在生成指令链时，将首先以相对坐标系 $(0, 0, 0)$ （即相对原点）开始，自下向上堆叠高度轴（即 $Y$ 轴）的长，当高度轴达到了限制的高度时，便将 $Z$ 轴向正方向堆叠 $1$ 个方块，并开始自上向下重新堆叠，直至高度轴坐标达到相对为 $0$。若当所生成结构的 $Z$ 轴长达到了其最大延伸长度，则此结构生成器将反转 $Z$ 轴的堆叠方向，直至 $Z$ 轴坐标相对为 $0$。如此往复，直至指令链堆叠完成。 + + +# 进度条自定义（已完全过时，请参阅相关代码） + +因为我们提供了可以自动转换进度条的功能，因此在这里给出进度条自定义参数的详细解释。 + +一个进度条，明显地，有**固定部分**和**可变部分**来构成。而可变部分又包括了文字和图形两种（当然，《我的世界》里头的进度条，可变的图形也就是那个“条”了）。这一点你需要了解，因为后文中包含了很多这方面的概念需要你了解。 + +进度条的自定义功能使用一个字符串来定义自己的样式，其中包含众多**标识符**来表示可变部分。 + +标识符如下（注意大小写）： + +| 标识符 | 指定的可变量 | +|---------|----------------| +| `%%N` | 乐曲名(即传入的文件名)| +| `%%s` | 当前计分板值 | +| `%^s` | 计分板最大值 | +| `%%t` | 当前播放时间 | +| `%^t` | 曲目总时长 | +| `%%%` | 当前进度比率 | +| `_` | 用以表示进度条占位| + +表示进度条占位的 `_` 是用来标识你的进度条的。也就是可变部分的唯一的图形部分。 + +**样式定义字符串（基础样式）**的样例如下，这也是默认进度条的基础样式： + +```▶ %%N [ %%s/%^s %%% __________ %%t|%^t]``` + +这是单独一行的进度条，当然你也可以制作多行的，如果是一行的，输出时所使用的指令便是 `title`，而如果是多行的话，输出就会用 `titleraw` 作为进度条字幕。 + +哦对了，上面的只不过是样式定义，同时还需要定义的是可变图形的部分，也就是进度条上那个真正的“条”。 + +对于这个我们就采用了固定参数的方法，对于一个进度条，无非就是“已经播放过的”和“没播放过的”两种形态，例如，我们默认的进度“条”（**可变样式**）的定义是这样的： + +**可变样式甲（已播放样式）**：`'§e=§r'` + +**可变样式乙（未播放样式）**：`'§7=§r'` + +综合起来，把这些参数传给函数需要一个参数整合，使用位于 `Musicreater/subclass.py` 下的 `ProgressBarStyle` 类进行定义： + +我们的默认定义参数如下： + +```python +DEFAULT_PROGRESSBAR_STYLE = ProgressBarStyle( + r"▶ %%N [ %%s/%^s %%% __________ %%t|%^t ]", + r"§e=§r", + r"§7=§r", +) +``` + +*为了避免生成错误，请尽量避免使用标识符作为定义样式字符串的其他部分* + + diff --git a/docs/内置插件相关/MC指令结构/生成文件的使用说明.md b/docs/内置插件相关/MC指令结构/生成文件的使用说明.md new file mode 100644 index 0000000..02cac4b --- /dev/null +++ b/docs/内置插件相关/MC指令结构/生成文件的使用说明.md @@ -0,0 +1,60 @@ +

Minecraft 指令结构生成插件

+ + +

+ +

+ +

生成文件的使用方式

+ +**此引导文档已经过时** + +> **请明确**：该文档自 音·创 v2 版本停止开发后不再更新，本插件之相关功能从移植到 v3 之后已有变化。因此，此处文档仅作引用和参考，后续更新后会移除这句话。 + + +## 附加包格式 + +支持的文件后缀：`.MCPACK` + +- 计分板播放器 + + 1. 导入附加包 + 2. 在一个循环方块中输入指令 `function index` + 3. 将需要聆听音乐的实体的播放所用计分板设置为 `1` + 4. 激活循环方块 + 5. 若想要暂停播放，可以停止循环指令方块的激活状态 + 6. 若想要重置某实体的播放，可以将其播放用的计分板重置 + 7. 若要终止全部玩家的播放，在聊天框输入指令 `function stop` + + > 其中 步骤三 和 步骤四 的顺序可以调换。 + +- 延迟播放器 + + 1. 导入附加包 + 2. 在聊天框输入指令 `function index` + 3. 同时激活所生成的循环和脉冲指令方块 + 4. 若要终止播放，在聊天框输入指令 `function stop` 试试看，不确保有用 + + > 需要注意的是，循环指令方块需要一直激活直到音乐结束 + +## 结构格式 + +支持的文件后缀：`.MCSTRUCTURE`、`.BDX` + +1. 将结构导入世界 + +- 延迟播放器 + + 2. 将结构生成的第一个指令方块之模式更改为**脉冲** + 3. 激活脉冲方块 + 4. 若欲重置播放，可以停止对此链的激活，例如停止区块加载 + 5. 此播放器不支持暂停 + +- 计分板播放器 + + 2. 在所生成的第一个指令方块前，放置一个循环指令方块，其朝向应当对着所生成的第一个方块 + 3. 在循环指令方块中输入使播放对象的播放用计分板加分的指令，延迟为 `0`，每次循环增加 `1` 分 + 4. 激活循环方块 + 5. 若想要暂停播放，可以停止循环指令方块的激活状态 + 6. 若想要重置某实体的播放，可以将其播放用的计分板重置 + diff --git a/pyproject.toml b/pyproject.toml index 31f2d17..0b092e2 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -60,10 +60,6 @@ "librosa", ] preview-advanced = [ - "numpy < 3.0", - "soundfile", - "sounddevice", - "librosa", "pyloudnorm", ] full = [