feat: add unlock video

src/SUMMARY.md

@@ -2,8 +2,35 @@
 
 - [简介](./README.md)
 
+- [资源包](respack/index.md)
+
+- [谱面特性](feature/index.md)
+
+  - [特效](feature/effect/index.md)
+
+    - [内置着色器](feature/effect/builtin/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)
+
+    - [自行编写着色器](feature/effect/custom-shader.md)
+
+  - [视频背景](feature/video/index.md)
+
+  - [解锁动画](feature/unlock_video/index.md)
+
 - [UML文档](./uml/README.md)
+
   - [语法](./uml/syntax/README.md)
+
     - [坐标](./uml/syntax/coordinate.md)
     - [数据类型](./uml/syntax/type.md)
     - [表达式](./uml/syntax/expression.md)
@@ -13,8 +40,9 @@
     - [注释表达式](./uml/syntax/comment_expression.md)
 
   - [如何调试](./uml/debugging.md)
-  
+
   - [样例 UML](./uml/examples/README.md)
+
     - [模板活动](./uml/examples/template_event.md)
     - [2024 圣诞夜惊魂](./uml/examples/xmas-2024.md)
 

src/feature/effect/builtin/chromatic.md

@@ -0,0 +1,10 @@
+# `chromatic`
+
+色差效果。
+
+![示例](image/chromatic.png)
+
+## 参数
+
+- `sampleCount`（整数，默认 `3`，范围 `1-64`）：采样次数，越高显示会更连贯，开销也更大；
+- `power`（小数，默认 `0.01`）：强度，或者说偏移距离。

src/feature/effect/builtin/circleBlur.md

@@ -0,0 +1,9 @@
+# `circleBlur`
+
+圆点模糊。会将像素点模糊放大为亮点，建议搭配参数动画使用。
+
+![示例](image/circleBlur.png)
+
+## 参数
+
+- `size`（小数，默认 `10.0`）：原点的大小，以像素为单位。

src/feature/effect/builtin/fisheye.md

@@ -0,0 +1,15 @@
+# `fisheye`
+
+鱼眼效果。当 `power` 为负数时可以做出类似隧洞穿梭的效果。
+
+`power` 为负数：
+
+![示例](image/fisheye-neg.png)
+
+`power` 为正数：
+
+![示例](image/fisheye-pos.png)
+
+## 参数
+
+- `power`（小数，默认 `-0.1`）：鱼眼缩放比例。

src/feature/effect/builtin/glitch.md

@@ -0,0 +1,13 @@
+# `glitch`
+
+混乱 / 错误效果。该效果会随时间产生不确定的闪烁。
+
+![示例](image/glitch.png)
+
+## 参数
+
+- `power`（小数，默认 `0.3`）：闪烁强度；
+- `rate`（小数，默认 `0.6`，范围 `0-1`）：闪烁频率。`0` 为总不闪烁，`1` 为总是闪烁；
+- `speed`（小数，默认 `5.0`）：整个闪烁动画的速度；
+- `blockCount`（小数，默认 `30.5`）：见上图，错位条带的条数（大概）；
+- `colorRate`（小数，默认 `0.01`，范围 `0-1`）：色差的距离。

src/feature/effect/builtin/grayscale.md

@@ -0,0 +1,9 @@
+# `grayscale`
+
+灰度化效果。
+
+![示例](image/grayscale.png)
+
+## 参数
+
+- `factor`（小数，默认 `1.0`）：灰度化程度。`0` 为不进行灰度化处理，`1` 为完全进行灰度化处理。

src/feature/effect/builtin/index.md

@@ -0,0 +1,3 @@
+# 内置着色器
+
+该部分列举了 prpr 的内置着色器。

src/feature/effect/builtin/noise.md

@@ -0,0 +1,10 @@
+# `noise`
+
+噪音效果。向画面附加一层随机的模糊效果。
+
+![示例](image/noise.png)
+
+## 参数
+
+- `seed`（小数，默认 `81.0`）：用来生成随机图案的种子。通过连续地变化种子可以使图案发生连续的变化。
+- `power`（小数，默认 `0.03`，范围 `0-1`）：见上图，模糊的程度（像素偏移范围）。

src/feature/effect/builtin/pixel.md

@@ -0,0 +1,9 @@
+# `pixel`
+
+像素化效果。
+
+![示例](image/pixel.png)
+
+## 参数
+
+- `size`（小数，默认 `10.0`）：像素化后的单个像素大小。

src/feature/effect/builtin/radialBlur.md

@@ -0,0 +1,13 @@
+# `radialBlur`
+
+放射模糊。
+
+![示例](image/radialBlur.png)
+
+## 参数
+
+- `centerX`（小数，默认 `0.5`，范围 `0-1`）：放射中心的 X 坐标；
+- `centerY`（小数，默认 `0.5`，范围 `0-1`）：放射中心的 Y 坐标；
+- `power`（小数，默认 `0.01`，范围 `0-1`）：放射强度；
+- `sampleCount`（整数，默认 `3`，范围 `1-64`）：采样次数，越高显示会更连贯，开销也更大。
+

src/feature/effect/builtin/shockwave.md

@@ -0,0 +1,14 @@
+# `shockwave`
+
+冲击波效果。建议配合 `progress` 的参数动画使用。
+
+![示例](image/shockwave.png)
+
+## 参数
+
+- `progress`（小数，默认 `0.2`，范围 `0-1`）：冲击波的进度。冲击波是一个动画，`0` 进度为开始，直到 `1` 进度结束；
+- `centerX`（小数，默认 `0.5`，范围 `0-1`）：冲击波中心的 X 坐标；
+- `centerY`（小数，默认 `0.5`，范围 `0-1`）：冲击波中心的 Y 坐标；
+- `width`（小数，默认 `0.1`）：冲击波的宽度；
+- `distortion`（小数，默认 `0.8`）：冲击波扭曲程度；
+- `expand`（小数，默认 `10.0`）：冲击波延伸广度。

src/feature/effect/builtin/vignette.md

@@ -0,0 +1,11 @@
+# vignette
+
+虚光照效果。将屏幕的边缘调暗或调成其他颜色，可以用来模拟 Arcaea 的部分异象效果。
+
+![示例](image/vignette.png)
+
+## 参数
+
+- `color`（颜色，默认黑色）：边缘的颜色；
+- `extend`（小数，默认 `0.25`，范围 `0-1`）：边缘的延伸程度，值越大黑色部分越多；
+- `radius`（小数，默认 `15.0`）：中央光照大小，值越小受到影响的范围越大。

src/feature/effect/custom-shader.md

@@ -0,0 +1,52 @@
+# 自行编写着色器
+
+用于特效的着色器是片元着色器。你可以自行编写着色器并将其附加于谱面压缩包中。在 `shader` 字段，你需要填写 `/shader路径`。注意这里的 `/` 是必不可少的，它将内置着色器和自定义着色器区分开来。
+
+为保证兼容性，着色器版本要求为 GLSL 1.00。
+
+## 内置变量
+
+prpr 为着色器内置了如下变量：
+
+```glsl
+varying vec2 uv; // 材质 UV
+uniform vec2 screenSize; // 屏幕大小（注意是整个屏幕，并不只是谱面部分）
+uniform sampler2D screenTexture; // 屏幕材质（同样也是整个屏幕的材质）
+uniform float time; // 谱面时间，以秒为单位
+```
+
+还有一些变量是虽然存在，但在片元着色器中使用无意义的。在定义自己的变量时，你应该避免与它们重名：
+
+```glsl
+uniform mat4 Model;
+uniform mat4 Projection;
+uniform vec2 UVScale;
+```
+
+## 着色器变量
+
+为了在谱面中可以指定参数，你需要这样定义你的着色器 `uniform` 变量：
+
+```glsl
+uniform type name; // %def%
+```
+
+其中 `type` 为类型，目前支持 `float`、`vec2` 和 `vec4`；`name` 为变量名；`def` 为默认值。三个都是不可缺少的。
+
+## 示例
+
+下面的示例着色器将会根据 `factor` 的值给屏幕叠加上强弱不等的红色：
+
+```glsl
+#version 100
+precision mediump float;
+
+varying lowp vec2 uv;
+uniform sampler2D screenTexture;
+
+uniform float factor; // %0.5% 0..1
+
+void main() {
+  gl_FragColor = mix(texture2D(screenTexture, uv), vec4(1.0, 0.0, 0.0, 1.0), factor);
+}
+```

src/feature/effect/index.md

@@ -0,0 +1,74 @@
+# 特效
+
+特效是在一段时间内对谱面整体施加着色器效果的特性，可以用以达成一些普通谱面无法实现或难以实现的视觉效果。prpr 预置了一批着色器，你也可以自己编写着色器，详见 [自行编写着色器](./custom-shader.md)。
+
+## 格式
+
+你需要在 `extra.json` 中加入 `effects` 字段，其内容为 `Effect` 的数组。
+
+### Effect
+
+单个 `Effect` 的格式如下所示：
+
+```json
+{
+	"start": [0, 0, 1],
+	"end": [0, 0, 1],
+	"shader": "着色器名字",
+	"global": false,
+	"vars": {
+		...
+	}
+}
+```
+
+`start` 和 `end` 指定了特效的开始和结束时间，格式与 RPE 默认的时间表示格式相同（`[小节数, 分子, 分母]`）。
+
+`shader`，即着色器名字，既可以是内置着色器，也可以是自定义的着色器。
+
+`global` 决定了该特效会不会影响到 UI 元素（连击数、暂停按钮等）。可以不填，默认为 `false`。
+
+`vars` 是可选项，它是一个变量名字到 [`动画变量`](../index.html#动画变量) 的映射，用于指定着色器的参数（或者说，着色器的 `uniform` 变量）。即，假设我需要指定两个变量 `power` 和 `radius` 的值，我可以这样写：
+
+```json
+{
+	...,
+	"vars": {
+		"power": ...,
+		"radius": ...
+	}
+}
+```
+
+## 示例
+
+下面的例子将在 `[2, 0, 1]` 到 `[4, 0, 1]` 中使用 `chromatic` 内置着色器，并将 `power` 这一参数在这一时段内从 `0` 到 `0.1` 线性变化，且 `sampleCount` 被固定为 `5`：
+
+```json
+{
+	...,
+	"effects": [
+		{
+			"start": [2, 0, 1],
+			"end": [4, 0, 1],
+			"shader": "chromatic",
+			"vars": {
+				"power": [
+					{
+						"startTime": [2, 0, 1],
+						"endTime": [4, 0, 1],
+						"easingType": 2,
+						"start": 0.0,
+						"end": 0.1
+					}
+				],
+				"sampleCount": 5
+			}
+		}
+	]
+}
+```
+
+## 内置着色器
+
+你可以在 [这里](./builtin/index.md) 查看所有的内置着色器，以及它们的参数和相关说明。

src/feature/index.md

@@ -0,0 +1,64 @@
+# 谱面特性
+
+prpr 在支持 Phigros 官方谱面格式、`pec` 格式和 `rpe` 格式之外，加入了一些谱面特性。这些谱面特性目前只在 prpr 及基于其构建的客户端上可用。它们包括：
+
+- [特效](./effect/index.md)
+- [视频背景](./video/index.md)
+
+关于特性的配置需要全部存储在压缩包根目录的 `extra.json` 中。为了使用谱面特性，你需要手动编辑 JSON 文件。如果你不知道 JSON 是什么，请参阅 [JSON 教程](http://c.biancheng.net/json/)。
+
+## BPM 配置
+
+**在进行相关配置前，你需要在 `extra.json` 中预先设定好曲目的 BPM**。例如：
+
+```json
+{
+   "bpm": [
+      { "time": [0, 0, 1], "bpm" : 200.0 },
+      { "time": [10, 1, 2], "bpm" : 250.0 }
+   ],
+   ...
+}
+```
+
+这里表示歌曲最初 BPM 为 `200`，而后在十又二分之一拍是转换为 `250`。
+
+## 动画变量
+
+在配置文件中会常常用到动画变量。例如，在 RPE 中，的 X 坐标变化事件实际上就是 X 坐标作为一个动画变量。
+
+prpr 的动画变量有两种格式。第一种即单个值，表示该变量不会更改，一直维持同一个值。这种格式是为了方便填写而适用的。第二种格式与 RPE 中的格式相同，是由多个 `Event` 组成的。单个 `Event` 格式如下所示：
+
+```json
+{
+	"startTime": [0, 0, 1],
+	"endTime": [0, 0, 1],
+	"easingType": 2,
+	"easingLeft": 0.0,
+	"easingRight": 1.0,
+	"start": ...,
+	"end": ...
+}
+```
+
+其中 `startTime`、`endTime` 是事件的开始和结束时间；`easingType` 是缓动类型；`easingLeft`、`easingRight` 是可选的，代表裁剪缓动的开始与结束位置。
+
+`start` 和 `end` 代表该时间开始和结束处该变量的值。这里值的类型是取决于变量本身的类型的，它可以是下面类型中的任意一种：
+
+- `float`：单个小数；
+- `vec2`：两个小数表示的二维向量，用数组表示；
+- `color`：四个整数（0-255）表示的颜色，格式为 `[R, G, B, A]`。
+
+例如，下面的动画变量将在特定时段内从 `0` 到 `1` 线性变化：
+
+```json
+[
+	{
+		"startTime": [2, 0, 1],
+		"endTime": [4, 0, 1],
+		"easingType": 2,
+		"start": 0.0,
+		"end": 0.1
+	}
+]
+```

src/feature/unlock_video/index.md

@@ -0,0 +1,18 @@
+
+# 解锁动画
+
+**请注意解锁动画和视频背景的区别**
+
+解锁动画允许在玩家初次游玩谱面前播放一段视频。
+
+## 使用方法
+
+目前 UI 还没做好，稍微有些麻烦。下面的步骤建议在 Windows 上进行。
+
+如果你的谱面已经有了 `info.yml`，请跳转到第三步。
+
+1. 在 Phira 中导入你的谱面；
+2. 在 `data/charts/custom` 中搜索你的谱面 ID（如 `9067228`），找到对应的文件夹，在里面找到 `info.yml`；
+3. 向你的谱面文件夹（注意不是导入到 Phira 后的文件夹，是 pez 解压出来的文件夹）内加入解锁动画，假设文件名为 `unlock.mp4`；
+4. 在 `info.yml` 中找到 `unlockVideo: null` 一行，替换为 `unlockVideo: unlock.mp4`（如果没有这一行，则加上这一行）；
+5. 重新导入你的谱面。