Musicreater/docs/生成文件的使用说明.md

音·创 Musicreater

库版 Package Version

生成文件结构

由于先前的 读我文件(README.md) 过于冗杂，现另辟蹊径来给大家全方位的教程。

这是本库生成后文件结构的相关说明，不是使用本库的教程，若要查看本库的演示程序使用教程，可点击此处

名词解释

名词	解释	备注
指令区	一个用于放置指令系统的区域，通常是常加载区。	常见于服务器指令系统、好友联机房间中
指令链（链）	与链式指令方块不同，一个指令链通常指代的是一串由某种非链式指令方块作为开头，后面连着一串链式指令方块的结构。	通常的链都应用于需要“单次激活而多指令”的简单功能
起始块	链最初的那个非链式指令方块。	此方块为脉冲方块或重复方块皆可
指令系统（系统）	指令系统通常指的是，由一个或多个指令链以及相关红石机构相互配合、一同组成的，为达到某种特定的功能而构建的整体结构。	通常的系统都应用于需要“综合调配指令”的复杂功能。可由多个实现不同功能的模块构成，不同系统之间可以相互调用各自的模块。
游戏刻（刻）	游戏的一刻是指《我的世界》的游戏循环运行一次所占用的时间。（详见《我的世界》中文维基）。指令方块的延迟功能（即指令方块的“延迟刻数”设置项，此项的名称被误译为“已选中项的延迟”）的单位即为1游戏刻。	正常情况下，游戏固定以每秒钟20刻的速率运行。但是，由于游戏内的绝大多数操作都是基于刻数而非现实中的时间来计时并进行的，一次游戏循环内也许会发生大量的操作，很多情况下，一秒对应的游戏刻会更少。

文件格式

1. 附加包格式（.mcpack）

   使用附加包格式导出音乐，则音乐会以指令函数文件（.mcfunction）存储于附加包内。在附加包中，函数文件的存储结构应为：

   • functions\
     • index.mcfunction
     • mscply\
       • progressShow.mcfunction
       • track1.mcfunction
       • track2.mcfunction
       • ...
       • trackN.mcfunction

   如图，其中，index.mcfunction文件和mscply文件夹存在于函数目录的根下；在mscply目录中，包含音乐导出的众多音轨播放文件（trackX.mcfunction），同时，若生成此包时选择了带有进度条的选项，则会包含progressShow.mcfunction文件。

   index.mcfunction用于开始播放，其中包含打开各个音轨对应函数的指令，以及加分指令，这里的加分，是将播放计分板的值大于等于1的所有玩家的播放计分板分数增加1。同时，若生成此包时选择了自动重置计分板的选项，则会包含一条重置计分板的指令。

   你知道吗？音·创的最早期版本“《我的世界》函数音乐生成器”正是用函数来播放，不过这个版本采取的读入数据的形式大有不同。

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。如此往复，直至指令链堆叠完成。

播放器

以结构生成的文件可以采用多种方式播放，一类播放方式，我们称其为播放器，例如延迟播放器和计分板播放器等等，以后推出的新的播放器，届时也会在此处更新。

为什么要设计这么多播放器？是为了适应不同的播放环境需要。通常情况下，一个音乐中含有多个音符，音符与音符之间存在间隔，这里就产生了不一样的，实现音符间时间间隔的方式。而不同的应用环境下，又会产生不一样的要求。接下来将对不同的播放器进行详细介绍。

1. 计分板播放器

   计分板播放器是一种传统的《我的世界》音乐播放方式。通过对于计分板加分来实现播放不同的音符。一个很简单的原理，就是用不同的计分板分值对应不同的音符，再通过加分，来达到那个分值，即播放出来。

   在音·创中，用来达到这种效果的指令是这样的：

   execute @a[scores={ScBd=x}] ~ ~ ~ playsound InstID @s ~ ~Ht ~ Vlct Ptc
   

   参数	说明	备注
   ScBd	指定的计分板名称
   x	音发出时对应的分数值
   InstID	声音效果ID	不同的声音ID可以对应不同的乐器，详见转换乐器对照表
   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}

   后四个参数决定了这个音的性质，而前两个参数仅仅是为了决定音播放的时间。

2. 延迟播放器

   延迟播放器是通过《我的世界》游戏中，指令方块的设置项“延迟刻数”来达到定位音符的效果。将所有的音符依照其播放时距离乐曲开始时的时间（毫秒），放在一个序列内，再计算音符两两之间对应的时间差值，转换为《我的世界》内对应的游戏刻数之后填入指令方块的设置中。

   在音·创中，由于此方式播放的音乐不需要用计分板，所以播放指令是这样的：

   execute Tg ~ ~ ~ playsound InstID @s ~ ~Ht ~ Vlct Ptc
   

   参数	说明	备注
   Tg	播放对象	选择器或玩家名
   InstID	声音效果ID	不同的声音ID可以对应不同的乐器，详见转换乐器对照表
   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}

   其中后四个参数决定了这个音的性质。

   由于这样的延迟数据是依赖于指令方块的设置项，所以使用这种播放器所转换出的结果仅可以存储在包含方块NBT信息及方块实体NBT信息的结构文件中，或者直接输出至世界。