.osu (文件格式)

.osu 是一种简单易懂的，用于存储 osu! 谱面难度信息的文件格式。

结构

文件第一行描述了谱面文件存储格式的版本。目前，osu file format v14 是最新版。

之后的内容分为多个章节，并由方括号包裹的章节标题所分隔。

常规

编辑器

这些设置只在谱面编辑器内有效，不影响谱面的实际游玩。

元数据

难度

事件

事件语法： 类型,开始时间,参数

• 类型（字符串或者整型）： 事件类型，可以用名称或数字来表示。
• 开始时间（整型）： 事件开始时间，以谱面音频开始为原点，单位是毫秒。如果事件的开启时间未确定，则默认为 0。
• 参数（逗号分隔的数组）： 特定的， 在不同事件类型中发挥作用的参数。

背景

背景语法：0,0,文件名,x 轴位置,y 轴位置

• 文件名（字符串）： 背景图片在谱面文件夹内的文件名或者相对路径。若文件路径周围包含英文双引号，则也可被识别。
• x 轴位置（整型） 和 y 轴位置（整型）： 以屏幕中心为原点的背景图片位置偏移值，单位是 osu! 像素。例如，50,100 表示这张背景图片在游玩时，需要移动至屏幕中心向右移动 50 osu! 像素，向下移动 100 osu! 像素显示。如果偏移值为 0,0，也可以忽略不写。

视频

视频语法：Video,开始时间,文件名,x 轴位置,y 轴位置

Video 可用 1 代替。

• 文件名（字符串）、x 轴位置（整型）、 y 轴位置（整型） 的效果与背景图片一致。

休息段

休息段语法：Break,开始时间,结束时间

Break 可用 2 代替。

• 结束时间（整型）： 休息段的结束时间。以谱面音频开始为原点，单位是毫秒。

故事板

获取更多故事板语法，参见：编写故事板代码。

故事板代码可编写并存储至独立的 .osb 扩展名文件内，且这个文件包含的故事板代码，将能在谱面内所有难度运行并显示。

你可以为谱面内的不同难度制作它们专属的故事板，也可以与以上提到的公用故事板结合使用。

时间点

每个时间点都会控制谱面的一部分，又常称为“时间轴区间”。.osu 格式要求这些时间点在记录时，需要按时间顺序排序。

时间语法：时间,拍长,节拍,音效组,音效参数,音量,是否为非继承时间点（红线）,效果

• 时间（整型）： 时间轴区间的开始时间，以谱面音频开始为原点，单位是毫秒。这个时间轴区间的结束时间即为下一个时间点的开始时间（如果这是最后一个时间点，则无结束时间）。
• 拍长（精准小数）： 这个参数有两种含义：

  • 对于非继承时间点（红线），这个参数即一拍的长度，单位是毫秒。
  • 对于继承时间点（绿线），这个参数为负值，去掉符号后被 100 整除，即为这根绿线控制的滑条速度。例如，-50 代表这一时间段的滑条速度均为基础滑条速度的 2 倍。
• 节拍（整型）： 一小节中的拍子数量。继承时间点（绿线）的这个值无效果。
• 音效组（整型）： 物件使用的默认音效组（0 = 谱面默认设置（SampleSet），1 = normal，2 = soft，3 = drum）。
• 音效参数（整型）： 物件使用的自定义音效参数。 0 表示使用 osu! 默认的音效。
• 音量（整型）： 击打物件的音量（0 - 100）。
• 是否为非继承时间点（红线）（布尔值）： 字面意思。
• 效果（整型）： 一位影响时间点特殊效果的参数。参见：效果部分。

效果

时间点可以通过在效果（整型）参数中，通过修改参数值为 1 或者 8（二进制下，是第 0 位和第 3 位），来开启两种特殊效果。

• 1（二进制的第 0 位）：是否开启 Kiai 时间
• 8（二进制的第 3 位）：是否在 osu!taiko 和 osu!mania 模式下，忽略红线的第一条小节线显示

若想同时开启两种效果，则可填 9（1 + 8 = 9）。其余的二进制位暂不使用。

例子

10000,333.33,4,0,0,100,1,1
12000,-25,4,3,0,100,0,1

10 秒处的第一个时间点为非继承时间点（红线），并包含以下的设置：

• BPM 为 180（1 / 333.33 * 1000 * 60）
• 拍子记号为 4/4
• 沿用谱面的默认音效组
• 使用 osu! 的默认音效
• 音量 100%
• 开启 Kiai 时间

12 秒处的第二个时间点为继承时间点（绿线），改变滑条速度为 4 倍，并将这一段的音效组切换成 drum 音效组。

颜色

本节的所有设置均为颜色设置。这里的颜色为用逗号分隔的 RGB 数组（0 - 255），分别代表此颜色中的红、绿、蓝分量。

物件

打击物件语法：x,y,时间,物件类型,打击音效,物件参数,打击音效组

• x（整型） 和 y（整型）： 物件的位置，原点在左上角，单位是 osu! 像素。
• 时间（整型）： 物件精确击打的时间。以谱面音频开始为原点，单位是毫秒。
• 物件类型（整型）： 一位标记物件类型的数据。参见：类型部分。
• 打击音效（整型）： 一位标记物件打击音效的数据。参见：音效部分。
• 物件参数（逗号分隔的数组）： 根据物件类型不同附加的一些参数。
• 打击音效组（冒号分隔的数组）： 击打物件时，决定具体该播放哪些音效的一些参数。与打击音效参数关系密切。参见：音效部分。如果没有设置特殊参数，则默认为 0:0:0:0:。

类型

物件类型参数是一个 8 位整数，每一位都有特殊的含义。

音效

音效数据用于标记物件的打击音效：

如果没有设置打击音效，则默认为 Normal。

除了 osu!mania 模式之外，在其他模式中游玩，无论皮肤设置的 LayeredHitSounds（总是播放 Normal 音效） 设为何种状态，它都将默认强制启用。

自定义音效组

使用打击音效组数据能更细化地自定义物件的音效。如果没有设置特殊参数，则默认为 0:0:0:0:。

打击音效组语法：普通音效组:附加音效组:参数:音量:文件名

• 普通音效组（整型）： Normal 音效的音效组
• 附加音效组（整型）： Whistle、Finish、Clap 音效的音效组
• 音效组编号（整型）： 用于区分不同音效组的编号。如果是 0，则表示这个打击物件的音效组，沿用控制该物件时间点的音效组设定。
• 音量（整型）： 音效组的音量。如果是 0，则表示这个打击物件的音量，沿用控制该物件时间点的音量设定。
• 文件名（字符串）： 自定义附加音效的文件名或相对路径。

普通音效组和附加音效组可以设为以下的这些值：

• 0：未设置自定义音效组

  • 对于普通打击音效，音效组由控制该物件的时间点决定。
  • 对于附加打击音效， 音效组由普通打击音效组决定。
• 1：Normal 组
• 2：Soft 组
• 3：Drum 组

以上所有设置（不包括音量设置）共同决定了击打物件时应当播放何种音效。这个音效文件名格式为：<音效组名称>-hit<音效名称><音效组编号>.wav，其中：

• 音效组名称可设为 normal、soft、drum，这确定了普通打击音效或附加打击音效的音效组
• 音效名称可设为 normal、whistle、finish、clap
• 音效组编号与上述段落的音效组编号相同。如果值为 0 或 1，则可忽略不写

当加载谱面时，游戏会自动按从上到下的优先级加载对应名称的音效。

• 当音效组编号不设为 0 时，加载谱面内的音效
• 当无法在谱面内找到该音效组编号对应的文件时，加载玩家皮肤内的音效
• 当无法在玩家皮肤内找到该音效组编号对应的文件时，加载 osu! 默认的音效

当填写了文件名，此时游戏会将这个文件替换掉物件默认的附加打击音效。

圆圈

圆圈物件没有物件参数。

滑条

滑条语法： x,y,开始时间,物件类型,打击音效,曲线类型|曲线点,滑动次数,长度,头尾音效,头尾音效组,打击音效组

• 曲线类型（字符）： 构建滑条的曲线类型（B = 贝塞尔，C =向心 catmull-rom，L =直线，P = 完美圆）
• 曲线点（竖线分隔的字符串数组）： 构建滑条的锚点。每个点的格式为x:y。
• 滑动次数（整型）： 玩家在滑条完成前需要在滑条上滑动的次数。也可以看成折返次数 +1。
• 长度（精准小数）： 滑条的视觉长度。单位是 osu! 像素。
• 头尾音效（竖线分隔的整型数组）： 当按下滑条和滑条完成（包括折返）时播放的音效。第一个音效是滑条头的音效，最后的音效则是滑条尾的音效。
• 头尾音效组（竖线分隔的字符串数组）： 头尾音效的音效组。音效组的格式为普通音效组:附加音效组，与之前音效部分的格式相同。

滑条曲线

构建滑条时，开头的 x 和 y 确定了滑条头的位置，而曲线点保存了剩下的控制锚点位置。

osu! 里有四种滑条曲线类型：

• 贝塞尔曲线（B）： 可以创建任何曲度的贝塞尔曲线。使用红色的锚点（转折点），可以将多条贝塞尔曲线置入同一根滑条中。
• 向心 catmull-rom 曲线（C）： Catmull 曲线是贝塞尔曲线的一种插值替代方案，现因不好看而很少使用。
• 直线（L）： 在所有相隔的点之间都由直线相连接。
• 完美圆（P）： 完美圆曲线只能由三个点构成（包括滑条头的点），此时形成的滑条曲线是圆的一部分弧线。三点以上的滑条则自动转换成贝塞尔类型。

如果滑条的长度比已确定的曲线路径要长，则滑条会从曲线末尾继续延伸，直到达到目标长度。

注意：滑条的长度描述了完成滑条所需的时间。长度 / (基础滑条速度 * 100 * SV) * 拍长即完成滑条所需的时间（毫秒）（这里的 SV 是滑条速度倍率，受继承时间点（绿线）控制。如果没有绿线控制，则默认为 1）。

滑条音效

与头尾音效不同，当玩家在拖动滑条球时，滑条也会播放音效。这个音效会循环播放，直至滑条结束。

这个音效的命名方式与打击音效和打击音效组类似，但只支持使用 Normal 和 Whistle 音效。文件名格式为：<滑条音效组>-slider<滑条音效><音效组编号>.wav。当滑条音效填写为 slide 时，对应了 Normal 音效，而填写为 whistle，则对应了 Whistle 音效。

转盘

转盘语法： x,y,开始时间,物件类型,转盘音效,结束时间,转盘音效组

• 结束时间（整型）： 转盘的结束时间，以谱面音频开始为原点，单位是毫秒。
• x 和 y 不影响转盘的位置。它们的默认值为 256,192，即游戏区域的正中心。

长键（仅 osu!mania）

长键语法： x,y,开始时间,物件类型,长键音效,结束时间,长键音效组

• 结束时间（整型）： 长键的结束时间，以谱面音频开始为原点，单位是毫秒。
• x 与长键所在的键位有关。算法为：floor(x * 键位总数 / 512)，并限制在 0 和 键位总数 - 1 之间。
• y 不影响长键。默认值为 192，即游戏区域的水平中轴。

例子

256,192,11000,21,2
256,192,11200,8,12,12000,3:0:0:80:
100,100,12600,6,1,B|200:200|250:200|250:200|300:150,2,310.123,2|1|2,0:0|0:0|0:2,0:0:0:0:

第一个物件为圆圈：

• 处于游戏区域正中央
• 位于 11 秒处
• 是一组新 Combo 的开头，并跳过了一个 Combo 颜色显示
• 添加了 Whistle（哨声） 音效

第二个物件为转盘：

• 始于 11.2 秒处
• 终于 12 秒处
• 添加了 Finish（镲）和 Clap（鼓掌）音效（在转盘中，位于结尾），音量为 80%
• 修改普通击打音效（在转盘中，为旋转的音效）为 drum 音效组，音量为 80%

第三个物件为滑条：

• 滑条头位于 (100,100)
• 始于 12.6 秒处
• 是一组新 Combo 的开头
• 滑条主体由多条贝塞尔曲线构成，第一条曲线的控制点为 (100,100)、(200,200)、(250,200)，第二条曲线的控制点为 (250,200) 和 (300,150)。这两条贝塞尔曲线的结合处为红锚点。
• 一次折返
• 长 310.123 osu! 像素
• 在滑条头添加了 Whistle（哨声）音效，并在滑条尾添加了 soft 音效组的 Whistle（哨声）

osu!taiko

osu!taiko 的物件只使用时间决定物件在游戏区域出现的位置，忽略了物件所处的 x 和 y 值。同样地，滑条的决定参数只有滑条长度；曲线类型和曲线点只会影响谱面在编辑器内的显示模样。Combo 颜色、新 Combo 设置也会被忽略。同时，osu!taiko 有一套模式专属的音效规则。

• 添加 Whistle（哨声）和 Clap（鼓掌）音效的圆圈会变为咔（蓝色）音符，未添加这两种音效的圆圈则默认为咚（红色）音符。 添加 Finish（镲）音效的物件会变为大音符。
• 滑条变为黄色连打。
• 转盘变为拨浪鼓音符。

osu!catch

osu!catch 的游玩区域仅和 x 轴有关，而物件的 y 值则不重要。但是可以通过改变滑条的斜率来影响玩家游玩时盘子的水平加速度。

• 圆圈变为大果。
• 滑条变为水果串（由中果和小果组成，中果即滑条点的位置），滑条头尾或折返位置会带有大果。
• 转盘变为香蕉雨。

osu!mania

与 osu!catch 类似，osu!mania 不使用物件的 y 值。而 x 则用于区分物件所处的键位。参见：长键部分。

• 圆圈变为普通音符。
• osu!mania 内不使用滑条和转盘。