diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 2b2f061..0bf610a 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -4,28 +4,38 @@ - [资源包](respack/index.md) -- [谱面特性](feature/index.md) +- [谱面标准](chart-standard/index.md) - - [特效](feature/effect/index.md) + - [谱面信息](chart-standard/chartinfo.md) - - [内置着色器](feature/effect/builtin/index.md) + - [谱面文件格式](chart-standard/chart-format/index.md) - - [`chromatic`](feature/effect/builtin/chromatic.md) - - [`circleBlur`](feature/effect/builtin/circleBlur.md) - - [`fisheye`](feature/effect/builtin/fisheye.md) - - [`glitch`](feature/effect/builtin/glitch.md) - - [`grayscale`](feature/effect/builtin/grayscale.md) - - [`noise`](feature/effect/builtin/noise.md) - - [`pixel`](feature/effect/builtin/pixel.md) - - [`radialBlur`](feature/effect/builtin/radialBlur.md) - - [`shockwave`](feature/effect/builtin/shockwave.md) - - [`vignette`](feature/effect/builtin/vignette.md) + - [RPE](chart-standard/chart-format/rpe/index.md) - - [自行编写着色器](feature/effect/custom-shader.md) + - [音乐文件格式](chart-standard/music.md) - - [视频背景](feature/video/index.md) + - [扩展特性](chart-standard/extra/index.md) - - [解锁动画](feature/unlock_video/index.md) + - [特效](chart-standard/extra/effect/index.md) + + - [内置着色器](chart-standard/extra/effect/builtin/index.md) + + - [`chromatic`](chart-standard/extra/effect/builtin/chromatic.md) + - [`circleBlur`](chart-standard/extra/effect/builtin/circleBlur.md) + - [`fisheye`](chart-standard/extra/effect/builtin/fisheye.md) + - [`glitch`](chart-standard/extra/effect/builtin/glitch.md) + - [`grayscale`](chart-standard/extra/effect/builtin/grayscale.md) + - [`noise`](chart-standard/extra/effect/builtin/noise.md) + - [`pixel`](chart-standard/extra/effect/builtin/pixel.md) + - [`radialBlur`](chart-standard/extra/effect/builtin/radialBlur.md) + - [`shockwave`](chart-standard/extra/effect/builtin/shockwave.md) + - [`vignette`](chart-standard/extra/effect/builtin/vignette.md) + + - [自行编写着色器](chart-standard/extra/effect/custom-shader.md) + + - [视频背景](chart-standard/extra/video/index.md) + + - [解锁动画](chart-standard/unlock_video/index.md) - [UML文档](./uml/README.md) diff --git a/src/chart-standard/chart-format/index.md b/src/chart-standard/chart-format/index.md new file mode 100644 index 0000000..6b2b8fc --- /dev/null +++ b/src/chart-standard/chart-format/index.md @@ -0,0 +1,11 @@ +# 谱面文件格式 + +目前支持的谱面文件格式包括: + +- RPE 格式, 见 [RPE 文档](./rpe/index.md) +- PEC 格式 (文档待完善) +- PBC 格式 (文档待完善) + +格式的推断通过 `info.yml` 中的 `format` 字段进行, 若为空则通过文件内容进行推断. + +> 注意: 忽略谱面文件的后缀名 diff --git a/src/chart-standard/chart-format/rpe/index.md b/src/chart-standard/chart-format/rpe/index.md new file mode 100644 index 0000000..581e8ee --- /dev/null +++ b/src/chart-standard/chart-format/rpe/index.md @@ -0,0 +1,3 @@ +# RPE 文档 + +哇, 有生之年工程 diff --git a/src/chart-standard/chartinfo.md b/src/chart-standard/chartinfo.md new file mode 100644 index 0000000..efab9aa --- /dev/null +++ b/src/chart-standard/chartinfo.md @@ -0,0 +1,182 @@ +# 谱面信息格式 + +谱面信息是一种 [元数据](https://zh.wikipedia.org/wiki/%E5%85%83%E6%95%B0%E6%8D%AE) , 用于描述谱面数据之外的的基本信息, 例如作者, 插图, 音乐信息等. + +谱面信息存在两种变体, [`ChartInfo`](https://github.com/TeamFlos/phira/blob/207c4724146c5a48c4e304d6e20447a39a72e0d3/prpr/src/info.rs#L17) 和 [`BriefChartInfo`](https://github.com/TeamFlos/phira/blob/207c4724146c5a48c4e304d6e20447a39a72e0d3/phira/src/data.rs#L21), 谱面信息 (`ChartInfo`) 的存储采用 YAML 格式, 谱面的 `info.yml` 文件即为 `ChartInfo` 的实例 + +本地导入时会自动填充 `ChartInfo` 的所有字段, 但 YAML 格式本身并不难懂, 若希望填写好后一并打包导入来节省时间, 则需要注意以下字段的填写 + +## `ChartInfo` + +> 请参考[源代码](https://github.com/TeamFlos/phira/blob/main/prpr/src/info.rs)中的定义, 可能存在更新 + +### 谱面 ID `id` + +不必需, `i32` 整数, 默认为空 + +用于标识谱面的唯一 ID, 与服务器中的 ID 保持一致, Phira 客户端会根据此 ID 来判断是否需要更新谱面 + +本地谱面该项为空 + +### 上传者 ID `uploader` + +不必需, `i32` 整数, 默认为空 + +用于标识上传者的唯一 ID, 与服务器中的 ID 保持一致, 用于显示在线谱面的上传者信息 + +本地谱面该项为空 + +### 谱面名称 `name` + +必需, `String` 字符串, 默认为 "UK" + +谱面的名称 + +### 难度 `difficulty` + +必需, `f32` 浮点数, 默认为 10.0 + +谱面的难度, 别乱来哈 + +### 难度等级 `level` + +必需, `String` 字符串, 默认为 "UK Lv.10" + +显示在游玩时屏幕右下角的难度等级 + +### 谱面作者 `charter` + +必需, `String` 字符串, 默认为 "UK" + +> 这谱谁写的.jpg + +### 音乐作者 `composer` + +必需, `String` 字符串, 默认为 "UK" + +音乐的作者 + +### 插图作者 `illustrator` + +必需, `String` 字符串, 默认为 "UK" + +谱面的插图作者 + +### 谱面文件名 `chart` + +必需, `String` 字符串, 默认为 "chart.json" + +谱面文件的文件名, RPE 生成的谱面通常为 `chart.json`, PE 生成的谱面通常为 `xxx.pec` + +### 谱面格式 `format` + +不必需, [`ChartFormat`](https://github.com/TeamFlos/phira/blob/dad7d6f3a8535cabfb70ec3f954d774948c440f9/prpr/src/info.rs#L7) 枚举, 默认为空 + +谱面的格式, 不应当手动填写, 由 Phira 客户端自动识别并写入, 出于完整性需求在这里列出 + +### 音乐文件名 `music` + +必需, `String` 字符串, 默认为 "song.mp3" + +音乐文件的文件名 + +### 插图文件名 `illustration` + +必需, `String` 字符串, 默认为 "background.png" + +插图文件的文件名 + +### 解锁视频 `unlockVideo` + +不必需, `String` 字符串, 默认为空 + +解锁该谱面的视频文件名 + +### 预览开始时间 `previewStart` + +必需, `f32` 浮点数, 默认为 0.0 + +音乐预览开始的时间(秒) + +### 预览结束时间 `previewEnd` + +不必需, `f32` 浮点数, 默认为空 + +音乐预览结束的时间(秒), 留空则视为预览开始时间后 15.0 秒, 若超出结尾则会被截断 + +> 源代码: [截断](https://github.com/TeamFlos/phira/blob/dad7d6f3a8535cabfb70ec3f954d774948c440f9/phira/src/scene/song.rs#L94) + +### 纵横比 `aspectRatio` + +必需, `f32` 浮点数, 默认为 16.0 / 9.0 + +> 注意: 谱面显示的纵横比, 设备的纵横比大于此值(例如部分加长手机, 或者一般手机上此值填写为 4:3)时会保证谱面处于该值的纵横比, 而小于此值时会拉伸谱面以保证谱面填满屏幕(来源: TBD) + +### 背景暗化程度 `backgroundDim` + +必需, `f32` 浮点数, 默认为 0.6 + +谱面背景的暗化程度, 单位待补充 + +### 判定线长度 `lineLength` + +必需, `f32` 浮点数, 默认为 6.0 + +谱面中线条的长度, 单位待补充(涉及到渲染细节, 文档待补充) + +### 谱面延迟 `offset` + +必需, `f32` 浮点数, 默认为 0.0 + +谱面相对于音乐之间的时间延迟(秒), 即该值为正时相比于该值为零时: + +- 若两种情况中音乐同时开始, 则 `offset` 为正时谱面开始更晚 +- 若两种情况中谱面同时开始, 则 `offset` 为正时音乐开始更早 + +### 提示 `tip` + +不必需, `String` 字符串, 默认为空 + +Tip: 不写的话会给你塞一条别的 + +### 标签 `tags` + +必需, `String` 字符串数组, 默认为空 + +谱面的标签, 用于分类和搜索, 标签相关文档待补充 + +### 简介 `intro` + +必需, `String` 字符串, 默认为空 + +谱面的简介 + +### 长条选项 `holdPartialCover` + +必需, `bool` 布尔值, 默认为 false + +Hold 音符的一个渲染选项, 具体行为待补充 + +### 创建时间 `created` + +不必需, `DateTime` 可选的 UTC 时间, 默认为空 + +谱面创建的时间, 不应当手动填写, 由 Phira 客户端自动写入 + +### 更新时间 `updated` + +不必需, `DateTime` 可选的 UTC 时间, 默认为空 + +本地谱面最近一次更新的时间, 不应当手动填写, 由 Phira 客户端自动写入 + +### 谱面更新时间 `chartUpdated` + +不必需, `DateTime` 可选的 UTC 时间, 默认为空 + +云端谱面最近一次更新的时间, 不应当手动填写, 由 Phira 客户端自动写入. 用于判断是否需要更新谱面 + +## `BriefChartInfo` + +`BriefChartInfo` 是 `ChartInfo` 的一个简化版本, 用于在不需要详细信息的场景下使用. 以下是 `BriefChartInfo` 的主要字段: + +TBD diff --git a/src/chart-standard/effect/builtin/chromatic.md b/src/chart-standard/effect/builtin/chromatic.md new file mode 100644 index 0000000..6371728 --- /dev/null +++ b/src/chart-standard/effect/builtin/chromatic.md @@ -0,0 +1 @@ +# chromatic diff --git a/src/chart-standard/effect/builtin/circleBlur.md b/src/chart-standard/effect/builtin/circleBlur.md new file mode 100644 index 0000000..c7c95c3 --- /dev/null +++ b/src/chart-standard/effect/builtin/circleBlur.md @@ -0,0 +1 @@ +# circleBlur diff --git a/src/chart-standard/effect/builtin/fisheye.md b/src/chart-standard/effect/builtin/fisheye.md new file mode 100644 index 0000000..062a316 --- /dev/null +++ b/src/chart-standard/effect/builtin/fisheye.md @@ -0,0 +1 @@ +# fisheye diff --git a/src/chart-standard/effect/builtin/glitch.md b/src/chart-standard/effect/builtin/glitch.md new file mode 100644 index 0000000..0790964 --- /dev/null +++ b/src/chart-standard/effect/builtin/glitch.md @@ -0,0 +1 @@ +# glitch diff --git a/src/chart-standard/effect/builtin/grayscale.md b/src/chart-standard/effect/builtin/grayscale.md new file mode 100644 index 0000000..2923cf8 --- /dev/null +++ b/src/chart-standard/effect/builtin/grayscale.md @@ -0,0 +1 @@ +# grayscale diff --git a/src/chart-standard/effect/builtin/index.md b/src/chart-standard/effect/builtin/index.md new file mode 100644 index 0000000..eedb9a7 --- /dev/null +++ b/src/chart-standard/effect/builtin/index.md @@ -0,0 +1 @@ +# 内置着色器 diff --git a/src/chart-standard/effect/builtin/noise.md b/src/chart-standard/effect/builtin/noise.md new file mode 100644 index 0000000..3bb821c --- /dev/null +++ b/src/chart-standard/effect/builtin/noise.md @@ -0,0 +1 @@ +# noise diff --git a/src/chart-standard/effect/builtin/pixel.md b/src/chart-standard/effect/builtin/pixel.md new file mode 100644 index 0000000..ca38d6c --- /dev/null +++ b/src/chart-standard/effect/builtin/pixel.md @@ -0,0 +1 @@ +# pixel diff --git a/src/chart-standard/effect/builtin/radialBlur.md b/src/chart-standard/effect/builtin/radialBlur.md new file mode 100644 index 0000000..f4b26f8 --- /dev/null +++ b/src/chart-standard/effect/builtin/radialBlur.md @@ -0,0 +1 @@ +# radialBlur diff --git a/src/chart-standard/effect/builtin/shockwave.md b/src/chart-standard/effect/builtin/shockwave.md new file mode 100644 index 0000000..dc7bfb6 --- /dev/null +++ b/src/chart-standard/effect/builtin/shockwave.md @@ -0,0 +1 @@ +# shockwave diff --git a/src/chart-standard/effect/builtin/vignette.md b/src/chart-standard/effect/builtin/vignette.md new file mode 100644 index 0000000..943f325 --- /dev/null +++ b/src/chart-standard/effect/builtin/vignette.md @@ -0,0 +1 @@ +# vignette diff --git a/src/chart-standard/effect/custom-shader.md b/src/chart-standard/effect/custom-shader.md new file mode 100644 index 0000000..c57e37a --- /dev/null +++ b/src/chart-standard/effect/custom-shader.md @@ -0,0 +1 @@ +# 自行编写着色器 diff --git a/src/chart-standard/effect/index.md b/src/chart-standard/effect/index.md new file mode 100644 index 0000000..65c7d71 --- /dev/null +++ b/src/chart-standard/effect/index.md @@ -0,0 +1 @@ +# 特效 diff --git a/src/feature/effect/builtin/chromatic.md b/src/chart-standard/extra/effect/builtin/chromatic.md similarity index 100% rename from src/feature/effect/builtin/chromatic.md rename to src/chart-standard/extra/effect/builtin/chromatic.md diff --git a/src/feature/effect/builtin/circleBlur.md b/src/chart-standard/extra/effect/builtin/circleBlur.md similarity index 100% rename from src/feature/effect/builtin/circleBlur.md rename to src/chart-standard/extra/effect/builtin/circleBlur.md diff --git a/src/feature/effect/builtin/fisheye.md b/src/chart-standard/extra/effect/builtin/fisheye.md similarity index 100% rename from src/feature/effect/builtin/fisheye.md rename to src/chart-standard/extra/effect/builtin/fisheye.md diff --git a/src/feature/effect/builtin/glitch.md b/src/chart-standard/extra/effect/builtin/glitch.md similarity index 100% rename from src/feature/effect/builtin/glitch.md rename to src/chart-standard/extra/effect/builtin/glitch.md diff --git a/src/feature/effect/builtin/grayscale.md b/src/chart-standard/extra/effect/builtin/grayscale.md similarity index 100% rename from src/feature/effect/builtin/grayscale.md rename to src/chart-standard/extra/effect/builtin/grayscale.md diff --git a/src/feature/effect/builtin/image/chromatic.png b/src/chart-standard/extra/effect/builtin/image/chromatic.png similarity index 100% rename from src/feature/effect/builtin/image/chromatic.png rename to src/chart-standard/extra/effect/builtin/image/chromatic.png diff --git a/src/feature/effect/builtin/image/circleBlur.png b/src/chart-standard/extra/effect/builtin/image/circleBlur.png similarity index 100% rename from src/feature/effect/builtin/image/circleBlur.png rename to src/chart-standard/extra/effect/builtin/image/circleBlur.png diff --git a/src/feature/effect/builtin/image/fisheye-neg.png b/src/chart-standard/extra/effect/builtin/image/fisheye-neg.png similarity index 100% rename from src/feature/effect/builtin/image/fisheye-neg.png rename to src/chart-standard/extra/effect/builtin/image/fisheye-neg.png diff --git a/src/feature/effect/builtin/image/fisheye-pos.png b/src/chart-standard/extra/effect/builtin/image/fisheye-pos.png similarity index 100% rename from src/feature/effect/builtin/image/fisheye-pos.png rename to src/chart-standard/extra/effect/builtin/image/fisheye-pos.png diff --git a/src/feature/effect/builtin/image/glitch.png b/src/chart-standard/extra/effect/builtin/image/glitch.png similarity index 100% rename from src/feature/effect/builtin/image/glitch.png rename to src/chart-standard/extra/effect/builtin/image/glitch.png diff --git a/src/feature/effect/builtin/image/grayscale.png b/src/chart-standard/extra/effect/builtin/image/grayscale.png similarity index 100% rename from src/feature/effect/builtin/image/grayscale.png rename to src/chart-standard/extra/effect/builtin/image/grayscale.png diff --git a/src/feature/effect/builtin/image/noise.png b/src/chart-standard/extra/effect/builtin/image/noise.png similarity index 100% rename from src/feature/effect/builtin/image/noise.png rename to src/chart-standard/extra/effect/builtin/image/noise.png diff --git a/src/feature/effect/builtin/image/pixel.png b/src/chart-standard/extra/effect/builtin/image/pixel.png similarity index 100% rename from src/feature/effect/builtin/image/pixel.png rename to src/chart-standard/extra/effect/builtin/image/pixel.png diff --git a/src/feature/effect/builtin/image/radialBlur.png b/src/chart-standard/extra/effect/builtin/image/radialBlur.png similarity index 100% rename from src/feature/effect/builtin/image/radialBlur.png rename to src/chart-standard/extra/effect/builtin/image/radialBlur.png diff --git a/src/feature/effect/builtin/image/shockwave.png b/src/chart-standard/extra/effect/builtin/image/shockwave.png similarity index 100% rename from src/feature/effect/builtin/image/shockwave.png rename to src/chart-standard/extra/effect/builtin/image/shockwave.png diff --git a/src/feature/effect/builtin/image/vignette.png b/src/chart-standard/extra/effect/builtin/image/vignette.png similarity index 100% rename from src/feature/effect/builtin/image/vignette.png rename to src/chart-standard/extra/effect/builtin/image/vignette.png diff --git a/src/feature/effect/builtin/index.md b/src/chart-standard/extra/effect/builtin/index.md similarity index 100% rename from src/feature/effect/builtin/index.md rename to src/chart-standard/extra/effect/builtin/index.md diff --git a/src/feature/effect/builtin/noise.md b/src/chart-standard/extra/effect/builtin/noise.md similarity index 100% rename from src/feature/effect/builtin/noise.md rename to src/chart-standard/extra/effect/builtin/noise.md diff --git a/src/feature/effect/builtin/pixel.md b/src/chart-standard/extra/effect/builtin/pixel.md similarity index 100% rename from src/feature/effect/builtin/pixel.md rename to src/chart-standard/extra/effect/builtin/pixel.md diff --git a/src/feature/effect/builtin/radialBlur.md b/src/chart-standard/extra/effect/builtin/radialBlur.md similarity index 100% rename from src/feature/effect/builtin/radialBlur.md rename to src/chart-standard/extra/effect/builtin/radialBlur.md diff --git a/src/feature/effect/builtin/shockwave.md b/src/chart-standard/extra/effect/builtin/shockwave.md similarity index 100% rename from src/feature/effect/builtin/shockwave.md rename to src/chart-standard/extra/effect/builtin/shockwave.md diff --git a/src/feature/effect/builtin/vignette.md b/src/chart-standard/extra/effect/builtin/vignette.md similarity index 100% rename from src/feature/effect/builtin/vignette.md rename to src/chart-standard/extra/effect/builtin/vignette.md diff --git a/src/feature/effect/custom-shader.md b/src/chart-standard/extra/effect/custom-shader.md similarity index 100% rename from src/feature/effect/custom-shader.md rename to src/chart-standard/extra/effect/custom-shader.md diff --git a/src/feature/effect/index.md b/src/chart-standard/extra/effect/index.md similarity index 100% rename from src/feature/effect/index.md rename to src/chart-standard/extra/effect/index.md diff --git a/src/feature/index.md b/src/chart-standard/extra/index.md similarity index 99% rename from src/feature/index.md rename to src/chart-standard/extra/index.md index 4eec360..54de149 100644 --- a/src/feature/index.md +++ b/src/chart-standard/extra/index.md @@ -1,4 +1,4 @@ -# 谱面特性 +# 扩展特性文档 prpr 在支持 Phigros 官方谱面格式、`pec` 格式和 `rpe` 格式之外，加入了一些谱面特性。这些谱面特性目前只在 prpr 及基于其构建的客户端上可用。它们包括： diff --git a/src/feature/video/index.md b/src/chart-standard/extra/video/index.md similarity index 100% rename from src/feature/video/index.md rename to src/chart-standard/extra/video/index.md diff --git a/src/chart-standard/index.md b/src/chart-standard/index.md new file mode 100644 index 0000000..383d8b6 --- /dev/null +++ b/src/chart-standard/index.md @@ -0,0 +1,24 @@ +# Phira 谱面标准 + +## 谱面基本结构 + +Phira 谱面包是一个压缩包, 解压后的压缩包内应当直接包含以下文件而非文件夹: + +- `info.yml`: 采用 YAML 格式的[谱面信息](./chartinfo.md)文件 +- ...`info.yml` 中所指定的其他文件 + +## 各文件支持情况 + +### 谱面文件 + +见 [谱面文件格式](./chart-format/index.md) + +### 音乐文件 + +见 [音乐文件格式](./music.md) + +TBD + +## 常见问题 + +RPE 的谱面 JSON 文件存储了元数据(创作者, 难度, 名称等), 这一行为是**不被推荐**的, 这会导致这部分信息可能被重复记录, 从而导致不一致性. Phira 的行为以 `info.yml` 为准 diff --git a/src/chart-standard/music.md b/src/chart-standard/music.md new file mode 100644 index 0000000..0fe6526 --- /dev/null +++ b/src/chart-standard/music.md @@ -0,0 +1,12 @@ +# 音乐文件格式 + +目前支持的音乐文件格式包括: + +- `.mp3` +- `.ogg` +- `.wav` + +> 注意: +> +> 1. `mp3` 格式可能会存在不可预测的延迟, 请尽量使用 `ogg` 文件来避免 +> 2. `wav` 为未经压缩的原始音频信号, 占用空间较多, 可能会导致谱面上传失败 diff --git a/src/feature/unlock_video/index.md b/src/chart-standard/unlock_video/index.md similarity index 100% rename from src/feature/unlock_video/index.md rename to src/chart-standard/unlock_video/index.md diff --git a/src/chart-standard/video/index.md b/src/chart-standard/video/index.md new file mode 100644 index 0000000..484cb74 --- /dev/null +++ b/src/chart-standard/video/index.md @@ -0,0 +1 @@ +# 视频背景