# 05 WE 属性扩展：音源 combo、fps 限制

Status: resolved

## 内容

1. **音源**：`project.json` 新增 combo `bgm`，列表是所有壁纸音源声明的**并集**
   （WE 的 combo 是静态列表，只能手工同步），另加一档「随预设」`auto`：
   `auto` / `zaiduheni`「「再度和你」」/ `xilian`「昔涟」/ `pv37`「版本 PV」。
   每档壁纸仍在自己 `preset.js` 的 `audioChoices` 里声明可选音源。
2. **fps 限制**：`properties.fps` 经 `applyGeneralProperties` 下发，WE 不会替壁纸限流，自行实现。
3. `setPaused` 不实现（WE 会整体冻结进程）。

## 实现要点

- **音源优先级**：用户自填 URL（`audio_file`）> `bgm` 选中的音源 > 本壁纸默认音源。
  所选音源**只在本壁纸声明过时才生效**；不属于当前壁纸则音频回落本壁纸默认，
  **选择本身保留**，切回那份壁纸时用户的选择还在。
- **门控绘制**：包裹实例上的 `drawFrame`。播放器循环写作
  `requestAnimationFrame(() => this.drawFrame())`——箭头闭包在调用时才读 `this.drawFrame`，
  所以在实例上换掉它就能接管排程。
  - 原实现只在**真正绘制**时才排下一帧，而被限流丢掉的帧同样要排，否则循环停摆；
    因此排程由包装层负责，再让原实现以 `requestNextFrame = false` 调用。
  - **踩到的坑**：朴素地"距上一帧不足 `interval` 就丢"会把 rAF 抖动放大成整拍丢失——
    目标 30fps 时落在 33.2ms 的那一帧被判为不足 33.33ms 而丢掉，实测只有 **22.5fps**。
    改为"留 4ms 容差 + 到期时间按固定步长推进"后精确到 30.0。
  - **另一个坑**：`if (properties.fps)` 的真值判断会把 `fps: 0`（取消限流）整个吞掉，
    改判 `!== undefined`。

## 验收

`node .scratch/test-props.mjs`：

| 项目 | 结果 |
| --- | --- |
| bgm 切音源即时生效 | ✓（10 项音源断言全过） |
| 跨壁纸回落 + 选择保留 | ✓ xilian 选「昔涟」→ 切 kv37 回落 pv37 → 切回 xilian 回落默认 |
| 自定义 URL 优先级最高且不被切壁纸清掉 | ✓ |
| 限 30 / 20 / 取消限流 | 实测 **30.0 / 20.0 / 60.0 fps** |
| 不影响动画相位推进速度 | 0.999 / 0.999 / 1.000 倍速（基准 1.000） |