refactor(story-player): 抽出共享 DOTween ease 曲线库与 TweenRunner ease/loop 选项 - #407

对着 2.7.71 (build 2771) 的 GameAssembly.dll 复核了整份曲线库,发现三处与 native 不符,已直接推到本分支(c630bf3)。核心结论是:SetEase(Ease) 单参重载从不重置 easeOvershootOrAmplitude / easePeriod,所以曲线拿到的是库默认值 1.70158 / 0,而不是各条曲线"教科书形式"里隐含的默认值。

链路证据:

• TweenSettingsExtensions.SetEase<T>(t, Ease) @ 0x1848859d0 —— 只写 easeType,外加对 flash 族做一次 (int) 截断,别的什么都不碰:

  HIDWORD(t[11].klass) = ease;
  if ( IsFlashEase(ease) ) *(float*)&t[12].klass = (float)(int)*(float*)&t[12].klass;
  t[11].monitor = nullptr; // customEase = null

• DOTween..cctor @ 0x1841bb710 → defaultEaseOvershootOrAmplitude = 1.70158、defaultEasePeriod = 0
• Tweener.Setup<Vector3,...> @ 0x184896a60 → 把这两个值拷进每个 tween

1. Elastic 三条曲线的 amplitude 用错(数值偏差可观)

Evaluate @ 0x1841f1170 的 elastic 分支是这样的:

comiss xmm9(1.0), xmm12(overshootOrAmplitude)
ja loc_1841F1955 ; 仅当 1.0 > overshoot 时:amp = 1, s = period * 0.25
; 否则 → Asin 分支:amp 保持原值,s = period / 2pi * asin(1 / amp)

overshoot = 1.70158 ≥ 1,所以 ja 不成立、走 else:振幅乘子保持 1.70158,相移是 period/2π·asin(1/amp) 而非 period/4。常量已逐个核对:0x186a782a4 = 0.3(In/Out 的 period 默认)、0x186a9416c = 0.45(InOut)、0x186a782c8 = 2π、0x186a77d9c = 0.25。

原实现用的是 easings.net 那套 amplitude=1 形式(2π/3、2π/4.5 折叠常量),实测差异:

端点有 early-out 所以现有的"端点锚定"用例测不出来,已补上中间点断言。全语料没有 Elastic ease,属潜伏问题,不影响线上。

顺带确认 Back 族是对的(1.70158、InOutBack ×ばつ1.525 与 native 一致),Bounce 族对照 0x1841f0180 / 0x1841f03a0 也一致。

2. 序数 0(Ease.Unset)应落 OutQuad,不是 Linear

Evaluate 的入口守卫:

if ( (unsigned int)(easeType - 1) > 0x24 ) // 只有 1..37 有 case
 goto LABEL_127; // -(t/d)*(t/d-2),即 OutQuad 抛物线

easeType = 0 → 0xFFFFFFFF > 0x24 → default 分支。而 SetEase 是无条件赋值(见上),没有 Unset→默认值 的重映射。原注释 0: Ease.Unset — GetEnum's parse fallback value 把两件事混了:GetEnum 的解析回落是序数 1(Linear),_ExecuteImageTween @ 0x183f05a3f 传的就是立即数 1。原 tests/tweenEase.spec.ts 里 expect(dotweenEaseCurve("0")(0.5)).toBe(0.5) 把错值锁进了断言,已改为 0.75。

语料里没有 ease="0"(只有 "1"×ばつ18 / "6"×ばつ8 / "7"×ばつ2),无可见回归。

3. 曲线表按名取值会命中 Object.prototype

dotweenEaseCurves 是对象字面量,dotweenEaseCurves[ease] 会拿到继承成员,而它们非 null,?? linearEase 兜不住:

ease="toString" → 返回字符串 → progress 变 NaN → transform 全 NaN
ease="valueOf" → 抛 TypeError(在 tween step 回调里,吃掉整个动画帧)
ease="hasOwnProperty" → 抛 TypeError
ease="__proto__" → 拿到 prototype 对象,在 setImageTween 里当场抛

剧本文本是 wiki 可编辑内容,一个手滑的 ease 值就能打崩整条命令;native 对应行为只是 DLog.LogError("Can not parse enum ...") 然后回落 Linear。已改为 Object.hasOwn 自有属性查找。

顺带按 native 补齐了 int32 溢出的序数回落——Enum.Parse 走 Int32.Parse,溢出即抛,GetEnum 在 0x1846a7cd0 的 catch 里 LogError 后 mov eax, defaultEnum。这里也确认了 PR 描述中"解析失败回落 Linear"是对的,catch 块确实存在。

另外一并处理的

• Flash 族的 (-1 / 0) 前提是错的,实际是 SetEase 截断后的 amplitude = (int)1.70158 = 1、period = 0。不过 amp=1 时 Flash.Ease 只剩单波(stepIndex=1、dir=1、波进度 = time),WeightedEase @ 0x1841f3ed0 又在 period == 0 时短路成 min(1, res)——与 -1 的假设数值上完全等价,我逐点比对过 Flash/InFlash/OutFlash,语料里唯一那条 ease="OutFlash"(story_mizuki_1_1.txt:515)渲染不变。所以不是 bug,但那 ~60 行多波机械按构造不可达,已塌缩成 min(1, wave(time)) 并订正出处注释。
• CgItemPanel.easeProgress 并进来了。main 上一直还有第三份 ease 实现,只有 3 条曲线,而且用 ease.toLowerCase()——大小写不敏感,和它自己紧挨着的注释(ignoreCase: false)以及本 PR 的大小写敏感解析直接冲突。既然本 PR 的立意就是消灭重复曲线表,顺手合流,顺便让 cgitem/hidecgitem 拿到另外 34 条曲线。现有单测的 ease 全是 "Linear",行为不变。
• TweenRunner 按 SetLoops @ 0x184885f00 钳位(0 → 1、< -1 → -1),并删掉 loops === 1 时与取模分支恒等的死代码。
• 曲线表改用 satisfies,序数表里写错键名(dotweenEaseCurves.OutQaud)现在会编译失败——之前配上仓库的 noUncheckedIndexedAccess: false 会静默变成 undefined → OutQuad。
• tests/tweenEase.spec.ts 里「ease="34" 是 OutFlash(story_mizuki_1_1)」的注释不准:语料那条是按名字写的 ease="OutFlash",全语料没有序数 34。已改成两者都断言。
• 出处地址统一到 2.7.71 (build 2771)。

没做的一项

native 在 ease 无法解析时会 DLog.LogError("Can not parse enum ..."),port 是静默的。要镜像成 runtime warning 需要 DotweenEase 往外暴露"是否可解析",并且会同时影响 cgitem/hidecgitem 和另外三个还没合的命令 PR 的告警输出(以及 log corpus 快照),超出本 PR 范围,留着后续统一处理。

验证:pnpm test 全绿、pnpm exec vue-tsc -b 通过、改动文件 eslint 通过。