Animation v2

dev-docs/Animation v2.md

@@ -0,0 +1,71 @@
+目前的动画实现不支持两项关键功能：相对动画和继承关键帧。
+
+因此，将开发 Animation v2 接口，这一接口将拓展现有的动画体系。
+
+v2 动画的 JSON 是一个对象：
+
+```json
+{
+  "version": 2,
+  "relative": true,
+  "inherit": true,
+  "keyframes": [
+    { "time": 250, "position": { "x": -100 }, "ease": "easeOut" },
+    { "time": 750, "position": { "x": 100 }, "ease": "easeInOut" },
+    { "time": 1000, "position": { "x": 0 }, "ease": "easeIn" }
+  ]
+}
+```
+
+该动画使舞台对象围绕当前位置左右摇动一次，最终回到原位。
+
+关键帧的 `time`（单位为毫秒）是该关键帧在动画中所处的时间，从动画开始计算，与 AE 中关键帧所在的时间相同。关键帧按 `time` 先后排列，与其在数组中的位置无关；动画的总时长为最大的 `time`。`time` 缺省或非法（不是数字或小于 0）时按 0 处理。`ease` 为同一属性从上一关键帧到达本帧这一区间所使用的缓动，缺省为 `easeInOut`。`time` 相同的多个关键帧处于同一时刻，构成跳变：数组中靠前的关键帧为插值终点，靠后的关键帧为跳变后的状态。
+
+除了关键帧以外，还将加入用于描述动画属性的字段，目前包括：
+
+1. 动画版本 `version`，对于 Animation v2，这个值是 2。
+2. 是否为相对动画 `relative`，默认为 true。为 true 则启用相对动画，帧中的值基于舞台对象的**当前基准状态**变换；为 false 则帧中的值为绝对值。**当前基准状态**遵循 `transformFrom` 及相关参数的设置，一般为 current（当前的变换），如果为 default 则为 `baseTransform`。各属性默认的计算方式如下（取值含义见第 4 项）：
+   - `add`：`position`、`rotation`、`blur`、`bevel`、`bevelThickness`、`bevelRotation`、`bevelSoftness`、`bloom`、`bloomBlur`。
+   - `multiplyWithZeroFallback`：`scale`。
+   - `absolute`：其余属性，如 `alpha`、`brightness`、颜色、滤镜开关等。
+3. 是否启用帧继承 `inherit`，默认为 true。启用时，各属性分别处理，采用类似于 AE 的方式：
+   1. 在属性最后一个关键帧后：继承最近关键帧的值。
+   2. 在两个关键帧之间：插值。
+   3. 在属性第一个关键帧前：从**当前基准状态**过渡到第一个关键帧。
+   4. 动画中未涉及的属性：保持不变。
+
+   禁用时，关键帧中未指定的属性取当前基准状态；在第一个关键帧前，同样从当前基准状态过渡到第一个关键帧。
+4. 覆盖相对动画计算方式 `relativeCalc`，是一个对象，键名为属性名，值为计算方式：
+   - `add`：基准值加帧中的值。
+   - `multiply`：基准值乘帧中的值。
+   - `multiplyWithZeroFallback`：同 `multiply`，但基准值为 0 时按 1 处理。
+   - `absolute`：直接使用帧中的值。
+
+   例如 `"relativeCalc": { "alpha": "multiplyWithZeroFallback" }` 使 `alpha` 按当前透明度的倍数变化。`position`、`scale` 等嵌套属性的设置同时作用于两轴。未指定或值非法的属性按默认计算方式处理。`relative` 为 false 时，此字段不生效。
+
+以上字段缺省或为非法值时，一律按默认值处理。
+
+相对动画重复执行会累积，例如右移 100 执行两次即右移 200。多个并行动画作用于同一属性时，效果叠加。
+
+对于旧的动画，即 JSON 文件直接是关键帧数组的，将其称为旧接口，仍然遵循 v1 的行为实现。在编辑器中，选择动画时默认隐藏 v1 动画，引擎可读取，但仅用于兼容旧脚本。
+
+实现方案：不分别实现 v1 和 v2。动画在 `AnimationManager.addAnimation` 中统一转换为 v2 格式后写入内核。加载动画文件、`setTempAnimation`、`setTransform`、`changeFigure`、`changeBg` 注册的动画均以此方式处理。
+
+- 顶层是对象：按 `version` 处理，缺省为 2。`version` 为 1 时，关键帧与 v1 一样使用 `duration`。
+- 顶层是数组：v1 动画，以该数组作为 `keyframes`，并设置 `version: 1`。
+
+v1 关键帧的 `duration`（单位为毫秒）是从上一关键帧到本关键帧的时长，第一个关键帧从动画开始计算。转换时依次累加，得到每个关键帧的 `time`。
+
+需要与 v1 保持一致的行为，均由 `version: 1` 决定，转换后的行为应与 v1 等价：
+
+- `relative`、`inherit` 固定为 false，`relativeCalc` 不生效。
+- 禁用帧继承时，在第一个关键帧前保持第一个关键帧的值。
+- 保留 v1 的 writeFullEffect 行为：`transformFrom=default` 且非并行时，动画中未涉及的属性重置为 `baseTransform`。
+
+对于 `setTempAnimation`，在此处一般不便按照完整的 Animation v2 接口编写动画。为了在使用类似于 v1 的写法时也能使用相对动画、帧继承等特性，允许传入 `relative`、`inherit` 参数：
+
+- 传入关键帧数组且未传入这两个参数：按 v1 处理，用于兼容旧脚本。
+- 传入关键帧数组且传入了其中任一参数：以该数组作为 `keyframes` 按 v2 处理，传入的参数覆盖默认值。数组中的关键帧沿用 v1 的写法，使用 `duration`。
+- 传入 v2 对象：传入的参数覆盖对象中对应字段的值。
+
+所有内置动画将重写为 v2，以当前状态为基准，例如 `shake` 围绕当前位置摇动，`exit` 从当前透明度淡出。

packages/webgal/public/game/animation/animationTable.json

@@ -15,5 +15,22 @@
   "godrayFilm",
   "removeFilm",
   "shockwaveIn",
-  "shockwaveOut"
+  "shockwaveOut",
+  "enter-from-left-v2",
+  "enter-from-bottom-v2",
+  "enter-from-right-v2",
+  "shake-v2",
+  "move-front-and-back-v2",
+  "enter-v2",
+  "exit-v2",
+  "blur-v2",
+  "oldFilm-v2",
+  "dotFilm-v2",
+  "reflectionFilm-v2",
+  "glitchFilm-v2",
+  "rgbFilm-v2",
+  "godrayFilm-v2",
+  "removeFilm-v2",
+  "shockwaveIn-v2",
+  "shockwaveOut-v2"
 ]

packages/webgal/public/game/animation/blur-v2.json

@@ -0,0 +1,9 @@
+{
+  "version": 2,
+  "keyframes": [
+    {
+      "time": 300,
+      "blur": 5
+    }
+  ]
+}

packages/webgal/public/game/animation/dotFilm-v2.json

@@ -0,0 +1,9 @@
+{
+  "version": 2,
+  "keyframes": [
+    {
+      "time": 0,
+      "dotFilm": 1
+    }
+  ]
+}

packages/webgal/public/game/animation/enter-from-bottom-v2.json

@@ -0,0 +1,24 @@
+{
+  "version": 2,
+  "relativeCalc": {
+    "alpha": "multiplyWithZeroFallback"
+  },
+  "keyframes": [
+    {
+      "time": 0,
+      "alpha": 0,
+      "position": {
+        "y": 50
+      },
+      "blur": 5
+    },
+    {
+      "time": 500,
+      "alpha": 1,
+      "position": {
+        "y": 0
+      },
+      "blur": 0
+    }
+  ]
+}

packages/webgal/public/game/animation/enter-from-left-v2.json

@@ -0,0 +1,24 @@
+{
+  "version": 2,
+  "relativeCalc": {
+    "alpha": "multiplyWithZeroFallback"
+  },
+  "keyframes": [
+    {
+      "time": 0,
+      "alpha": 0,
+      "position": {
+        "x": -50
+      },
+      "blur": 5
+    },
+    {
+      "time": 500,
+      "alpha": 1,
+      "position": {
+        "x": 0
+      },
+      "blur": 0
+    }
+  ]
+}

packages/webgal/public/game/animation/enter-from-right-v2.json

@@ -0,0 +1,24 @@
+{
+  "version": 2,
+  "relativeCalc": {
+    "alpha": "multiplyWithZeroFallback"
+  },
+  "keyframes": [
+    {
+      "time": 0,
+      "alpha": 0,
+      "position": {
+        "x": 50
+      },
+      "blur": 5
+    },
+    {
+      "time": 500,
+      "alpha": 1,
+      "position": {
+        "x": 0
+      },
+      "blur": 0
+    }
+  ]
+}

packages/webgal/public/game/animation/enter-v2.json

@@ -0,0 +1,16 @@
+{
+  "version": 2,
+  "relativeCalc": {
+    "alpha": "multiplyWithZeroFallback"
+  },
+  "keyframes": [
+    {
+      "time": 0,
+      "alpha": 0
+    },
+    {
+      "time": 300,
+      "alpha": 1
+    }
+  ]
+}

packages/webgal/public/game/animation/exit-v2.json

@@ -0,0 +1,9 @@
+{
+  "version": 2,
+  "keyframes": [
+    {
+      "time": 300,
+      "alpha": 0
+    }
+  ]
+}

packages/webgal/public/game/animation/glitchFilm-v2.json

@@ -0,0 +1,9 @@
+{
+  "version": 2,
+  "keyframes": [
+    {
+      "time": 0,
+      "glitchFilm": 1
+    }
+  ]
+}

packages/webgal/public/game/animation/godrayFilm-v2.json

@@ -0,0 +1,9 @@
+{
+  "version": 2,
+  "keyframes": [
+    {
+      "time": 0,
+      "godrayFilm": 1
+    }
+  ]
+}

packages/webgal/public/game/animation/move-front-and-back-v2.json

@@ -0,0 +1,19 @@
+{
+  "version": 2,
+  "keyframes": [
+    {
+      "time": 500,
+      "scale": {
+        "x": 1.15,
+        "y": 1.15
+      }
+    },
+    {
+      "time": 1000,
+      "scale": {
+        "x": 1,
+        "y": 1
+      }
+    }
+  ]
+}

packages/webgal/public/game/animation/oldFilm-v2.json

@@ -0,0 +1,9 @@
+{
+  "version": 2,
+  "keyframes": [
+    {
+      "time": 0,
+      "oldFilm": 1
+    }
+  ]
+}

packages/webgal/public/game/animation/reflectionFilm-v2.json

@@ -0,0 +1,9 @@
+{
+  "version": 2,
+  "keyframes": [
+    {
+      "time": 0,
+      "reflectionFilm": 1
+    }
+  ]
+}

packages/webgal/public/game/animation/removeFilm-v2.json

@@ -0,0 +1,14 @@
+{
+  "version": 2,
+  "keyframes": [
+    {
+      "time": 0,
+      "oldFilm": 0,
+      "dotFilm": 0,
+      "reflectionFilm": 0,
+      "glitchFilm": 0,
+      "rgbFilm": 0,
+      "godrayFilm": 0
+    }
+  ]
+}

packages/webgal/public/game/animation/rgbFilm-v2.json

@@ -0,0 +1,9 @@
+{
+  "version": 2,
+  "keyframes": [
+    {
+      "time": 0,
+      "rgbFilm": 1
+    }
+  ]
+}

packages/webgal/public/game/animation/shake-v2.json

@@ -0,0 +1,26 @@
+{
+  "version": 2,
+  "keyframes": [
+    {
+      "time": 250,
+      "position": {
+        "x": -100
+      },
+      "ease": "easeOut"
+    },
+    {
+      "time": 750,
+      "position": {
+        "x": 100
+      },
+      "ease": "easeInOut"
+    },
+    {
+      "time": 1000,
+      "position": {
+        "x": 0
+      },
+      "ease": "easeIn"
+    }
+  ]
+}

packages/webgal/public/game/animation/shockwaveIn-v2.json

@@ -0,0 +1,15 @@
+{
+  "version": 2,
+  "keyframes": [
+    {
+      "time": 0,
+      "shockwaveFilter": 0,
+      "radiusAlphaFilter": 0
+    },
+    {
+      "time": 2000,
+      "shockwaveFilter": 3.05,
+      "radiusAlphaFilter": 1.05
+    }
+  ]
+}

packages/webgal/public/game/animation/shockwaveOut-v2.json

@@ -0,0 +1,13 @@
+{
+  "version": 2,
+  "keyframes": [
+    {
+      "time": 0,
+      "shockwaveFilter": 0
+    },
+    {
+      "time": 2000,
+      "shockwaveFilter": 3
+    }
+  ]
+}