mirror of
https://github.com/motajs/template.git
synced 2026-11-16 17:04:31 +08:00
feat: 录像数组
This commit is contained in:
1 parent
376b0fcac5
commit
f6383e41e8
12 files changed
+1610
-16
No files matched your search
@@ -0,0 +1,151 @@
|
||||
# 需求综述
|
||||
|
||||
录像由数万条录像步组成,每条录像步包含可变数量的参数,参数类型涵盖数字、字符串、布尔值和 bigint。直接操作 `ArrayBuffer` 的字节布局会导致系统耦合存储格式细节、修改录像困难。需要一个独立工具封装底层存储的读写,并提供插入、删除、修改等编辑能力。
|
||||
|
||||
# 需求理解
|
||||
|
||||
## 明确需求
|
||||
|
||||
1. 变长指令编码。指令码使用 `uint8` 或 `uint16`,宽度取决于已注册命令的最大 ID。
|
||||
2. 自描述参数格式。参数使用类型标识 + 变长内容的编码,每条录像步的参数数量可变。类型标识同时承担短字符串的长度信息,节省额外字节。
|
||||
3. 录像可编辑。支持在任意有效位置插入、删除、修改录像步——不是只追加的日志。
|
||||
4. 顺序流式读取。播放是按顺序逐帧进行的,需要流式读取器避免每次随机访问的 O(n) 偏移扫描。
|
||||
|
||||
## 隐含需求
|
||||
|
||||
1. 容量管理。`ArrayBuffer` 不可动态扩容,写入前需检查容量,不足时分配新缓冲并复制。
|
||||
2. 偏移累积。指令数组中的每条录像步长度不固定,随机访问某一条时需从头扫描累积偏移。流式读取器可以利用顺序访问特性只扫描一次。
|
||||
|
||||
# 设计前提
|
||||
|
||||
1. 双缓冲存储。指令数组和参数数组各自使用独立的 `ArrayBuffer`,通过 `DataView` 读写。
|
||||
2. 不可变元数据。`IReplayMetadata` 中的格式参数在初始化时确定,读取时不修改。
|
||||
3. 边解码边播放。不一次性解码全部数据——沙箱通过流式读取器按需解码。
|
||||
|
||||
# 核心概念定义
|
||||
|
||||
## 指令数组
|
||||
|
||||
录像中所有指令码与参数数量的序列化存储。每条录像步在指令数组中占用 1+W 字节(W 为指令码宽度):第一个 `uint8` 为参数数量,后续 `uint8` 或 `uint16` 为指令码。
|
||||
|
||||
## 参数数组
|
||||
|
||||
录像中所有参数内容的序列化存储。每个参数由一个 `uint8` 类型标识开头,后接对应类型的二进制内容。类型标识同时编码短字符串的长度(8-256 → 长度 n-7)。
|
||||
|
||||
## 流式读取器
|
||||
|
||||
持有一个内部偏移指针,每次调用 `read` 解码并返回当前指针指向的录像步,然后推进指针。由于指令数组中每条录像步的总字节数不固定,指针以步索引而非字节偏移为单位——读取器内部维护已扫描过的累积字节偏移,每次 `read` 仅解码一步。
|
||||
|
||||
## 指令宽度
|
||||
|
||||
指令码的存储字节数。初始为 `uint8`(1 字节)。命令 ID 上限在 `registerCommand` 注册时即可获知——若注册了 > 255 的 ID,直接初始化为 `uint16`,不涉及运行时重编码。若需要变更已存在录像的指令宽度(例如切换为更大的指令码空间以兼容新增命令,或压缩为更小的空间以节省体积),则通过 `setCommandWidth` 方法将全部指令条目按新宽度重编码。
|
||||
|
||||
# 接口设计分析
|
||||
|
||||
## `IReplayArray`
|
||||
|
||||
### 设计思路
|
||||
|
||||
由于录像需要支持任意有效位置的插入和删除——比如玩家在已录制的操作序列中间补充了额外操作,或者修复了某段错误的录像——只提供追加写入是不够的。因此需要 `insert` 和 `delete` 方法,以及在原位置修改的 `set` 方法。追加仍然是最频繁的操作——因此需要 `add` 方法。
|
||||
|
||||
由于沙箱播放是顺序推进的,每次调用 `get(index)` 都需要从头扫描积累偏移——因此设计 `createReadStream` 创建流式读取器。流式读取器内部维护步索引指针和已累积字节偏移,每次 `read` 仅解码一步,将偏移计算从 O(n²) 降为 O(n)。同时保留 `get` 用于跳转播放等非顺序场景。
|
||||
|
||||
由于命令 ID 上限在注册阶段已知,指令宽度在 `IReplayArray` 构造时即确定——若最大 ID > 255 则初始化为 `uint16`。但已存在的录像可能需要变更宽度——例如加载旧 `uint8` 录像后注册了 > 255 的新命令需要升级,或者想将 `uint16` 录像压缩回 `uint8` 以节省存储。因此需要 `setCommandWidth` 方法将全部指令条目按新宽度重编码。
|
||||
|
||||
### 接口分析
|
||||
|
||||
- 成员 `length: number`:预期频率**中频**。安全系统检测步数变化、沙箱判断播放是否结束。
|
||||
- 成员 `metadata: IReplayMetadata`:预期频率**低频**。存档时读取以持久化格式参数。
|
||||
- 方法 `add(id: number, params: ReplayParamValue[])`:预期频率**高频**。每次 `record` 调用一次。
|
||||
- 方法 `insert(index: number, id: number, params: ReplayParamValue[])`:预期频率**低频**。`index` 等于 `length` 时等同于 `add`;`index` 超出 `length` 时触发警告并忽略。
|
||||
- 方法 `delete(index: number)`:预期频率**低频**。
|
||||
- 方法 `set(index: number, id: number, params: ReplayParamValue[])`:预期频率**低频**。
|
||||
- 方法 `get(index: number): IReplayStepHandler`:预期频率**低频**。跳转播放时使用。
|
||||
- 方法 `createReadStream(startIndex?: number): IReplayReadStream`:预期频率**中频**。沙箱播放时调用。
|
||||
- 方法 `setCommandWidth(width: ReplayCommandWidth)`:预期频率**低频**。变更已存在录像的指令码宽度,将全部指令重编码。
|
||||
|
||||
### 预期体量
|
||||
|
||||
预期代码体量 300-360 行。
|
||||
|
||||
- 参数编码预期 100 行。七种参数类型各自需要独立的写入逻辑:布尔值为类型 0 接 1 字节;int8/int16/int32/int64/float64 各为一个单字节类型标识(1-5)接对应宽度的定长写入;bigint 需类型 6 接 `uint16` 长度再接 n 个 `int32`;短字符串将长度编码进类型字节(8-256,长度 = n-7),`TextEncoder` 编码后直接写入内容;长字符串用类型 7 接 `uint16` 长度再写内容。每种类型还需容量检查与扩容,七种类型的分支代码量相当可观。
|
||||
- 参数解码预期 80 行。与编码对称的七种读取分支,根据类型字节分发。数值类型按宽度读,bigint 读长度后拼接 int32,短字符串从类型字节反推长度后 `TextDecoder` 解码,长字符串先读长度。每条分支均含边界检查。
|
||||
- 指令读写预期 60 行。写入时根据当前 `commandWidth` 决定写入 1 还是 2 字节,读取时同理。每条录像步的指令部分 = `uint8` 参数数量 + W 字节指令码。`get` 和 `createReadStream` 均需维护字节偏移——每次读取或跳过一条录像步时,根据上一条的参数数量和参数总字节长度计算下一条的起始偏移。
|
||||
- 插入与删除预期 60 行。`insert` 需将指定位置及之后的所有指令和参数数据向后移动以腾出空间,再在空位写入新步。`delete` 则反向——将之后的数据向前移动覆盖被删除步。参数数组的移动量取决于被操作步的参数总字节数,需先解码获取。`set` 本质是先 `delete` 后 `insert`。
|
||||
- 容量管理与复制预期 30 行。两个 `ArrayBuffer` 各自独立管理容量,写入前检查,不足时分配更大新缓冲(如 2 倍增长),逐字节复制旧数据后再继续写入。
|
||||
- 流式读取器预期 25 行。内部维护步索引、指令数组字节偏移、参数数组字节偏移。`read` 解码当前步并推进三个变量,返回 `IReplayStepHandler`,超出 `length` 时返回 null。构造时可选 `startIndex`,需扫描至指定位置。
|
||||
- 指令宽度变更预期 25 行。`setCommandWidth` 遍历全部已写指令条目——解析每条录像步的参数数量和原宽度的指令码——按新宽度重新写入指令数组。`commandWidth` 可能变大也可能变小,编码前需根据新宽度判断每条指令码是否在范围内(例如 `uint8` 模式下指令 ID > 255 应报错)。
|
||||
|
||||
## `IReplayReadStream`
|
||||
|
||||
### 设计思路
|
||||
|
||||
由于沙箱播放是顺序推进的,流式读取器持有当前步索引指针及已累积的字节偏移,每次调用 `read` 仅解码一步且指针自动推进——避免了 `get(n)` 每次 O(n) 扫描的累积开销。读取完毕后返回 null,调用方可判断播放结束。
|
||||
|
||||
### 接口分析
|
||||
|
||||
- 成员 `index: number`:预期频率**低频**。显示当前播放进度。
|
||||
- 成员 `length: number`:预期频率**低频**。用于判断是否已读取完毕。
|
||||
- 方法 `read(): IReplayStepHandler | null`:预期频率**高频**。沙箱每步调用一次。
|
||||
|
||||
### 预期体量
|
||||
|
||||
预期代码体量 25 行。
|
||||
|
||||
## `IReplayMetadata`
|
||||
|
||||
### 设计思路
|
||||
|
||||
指令码宽度在读取时必须知晓才能正确解析每条录像步。`uint8` 和 `uint16` 是不同的编码模式,不是一个可变参数——因此用枚举 `ReplayCommandWidth` 标记,存档时持久化此枚举值。
|
||||
|
||||
### 接口分析
|
||||
|
||||
- 成员 `commandWidth: ReplayCommandWidth`:预期频率**低频**。初始化时根据最大命令 ID 设定,指令读写时使用。
|
||||
|
||||
### 预期体量
|
||||
|
||||
预期代码体量 5 行(含枚举定义)。
|
||||
|
||||
---
|
||||
|
||||
# 实现思路
|
||||
|
||||
## 参数编码格式
|
||||
|
||||
| 类型标识 | 参数类型 | 内容编码 |
|
||||
| -------- | --------------------- | ------------------------------------------------- |
|
||||
| 0 | 布尔值 | 1 字节:0 或 1 |
|
||||
| 1 | int8 | 1 字节 |
|
||||
| 2 | int16 | 2 字节 |
|
||||
| 3 | int32 | 4 字节 |
|
||||
| 4 | int64 | 8 字节 |
|
||||
| 5 | float64 | 8 字节 |
|
||||
| 6 | bigint | `uint16` 长度 N,后接 N 个 `int32` |
|
||||
| 7 | 长字符串(≥250 字节) | `uint16` 长度 N,后接 `TextEncoder` 编码的 N 字节 |
|
||||
| 8-256 | 短字符串(n-7 字节) | `TextEncoder` 编码的 n-7 字节,无额外长度字段 |
|
||||
|
||||
短字符串方案:类型标识本身编码了长度(8 表示 1 字节,256 表示 249 字节),`TextEncoder` 编码后直接写内容。大多数录像参数(道具 ID 名、操作描述等)落在此范围内,基本无需额外长度字段。
|
||||
|
||||
## 指令宽度确定
|
||||
|
||||
1. `IReplayArray` 构造时传入最大命令 ID(由 `IReplaySystem.registerCommand` 的累积结果提供)。若 maxId > 255,`commandWidth` 初始化为 `Uint16`;否则为 `Uint8`。
|
||||
2. 注册阶段即确定宽度,后续 `add`/`insert` 不涉及宽度切换。
|
||||
3. `setCommandWidth` 用于变更已存在录像的指令宽度:遍历全部指令条目,将原宽度的指令码按新宽度重写,更新 `metadata`。若缩小宽度时存在超过新宽度表示范围的指令 ID,应报错。
|
||||
|
||||
## 流式读取器内部状态
|
||||
|
||||
`read()` 每步仅解码当前指针指向的录像步:
|
||||
|
||||
1. 从指令数组当前字节偏移读 `uint8` 参数数量,再按 `commandWidth` 读指令码。
|
||||
2. 根据参数数量,从参数数组当前字节偏移逐参数解码。
|
||||
3. 将指令数组字节偏移增加 `1 + commandWidth`,参数数组字节偏移增加已解码参数的总字节数。
|
||||
4. 返回 `IReplayStepHandler`,`index` 为当前步索引。指针推进到下一步。
|
||||
|
||||
# 涉及文件
|
||||
|
||||
## `@user/data-common/src/replay/array.ts`
|
||||
|
||||
- [ ] 新增 `ReplayCommandWidth` 枚举
|
||||
- [ ] 编写 `IReplayArray`、`IReplayReadStream`、`IReplayMetadata` 接口
|
||||
- [ ] 编写 `ReplayArray` 类:实现 `IReplayArray`,封装双 `ArrayBuffer` 操作、指令宽度管理与变更、CRUD 编辑、流式读取
|
||||
- [ ] 编写 `ReplayReadStream` 类:实现 `IReplayReadStream`
|
||||
@@ -0,0 +1,80 @@
|
||||
# 需求综述
|
||||
|
||||
录像系统依赖作者在各逻辑系统中手动调用 `record`,这一依赖关系使得录像极易因疏忽而失效。需要一种机制来检测这类失效。
|
||||
|
||||
# 需求理解
|
||||
|
||||
## 明确需求
|
||||
|
||||
1. 录像存在失效风险。录像能否正确还原游戏流程完全取决于作者是否在每个状态修改处都调用了 `record`,遗漏是不可避免的风险。
|
||||
|
||||
## 隐含需求
|
||||
|
||||
1. 检测不能误报。系统内部的状态修改(如战斗结算中的属性计算)不应被检测为遗漏——只有从玩家操作入口派生的修改才需要检测。
|
||||
2. 播放时同样需检测。沙箱播放期间原始录像系统重新录制用于交叉验证——如果播放逻辑存在遗漏,同样应被检测到。
|
||||
|
||||
# 设计前提
|
||||
|
||||
1. 已知方案。`@shouldReplay` 标记影响状态的方法,`@ignoreReplay` 标记特定的延迟或被动代码路径,`begin`/`end` 界定检测区间。以下设计基于此方案推导。
|
||||
|
||||
# 核心概念定义
|
||||
|
||||
## 检测区间
|
||||
|
||||
由一对 `begin`/`end` 调用界定的代码执行范围。区间内收集标记,结束时比较区间前后的录像步数变化,结合标记信息决定是否告警。
|
||||
|
||||
## 状态影响标记
|
||||
|
||||
数据端方法上的 `@shouldReplay` 修饰器。表示此方法的调用应伴随录像步的写入——它是系统判断"此处有状态修改"的唯一依据。
|
||||
|
||||
## 检测抑制标记
|
||||
|
||||
特定方法上的 `@ignoreReplay` 修饰器。某些场景中,`@shouldReplay` 方法确实被调用,但录像步的写入发生在此区间之外(如异步回调中),不加抑制会误报。它不应用于所有渲染端交互函数——那样系统永不会告警。
|
||||
|
||||
# 接口设计分析
|
||||
|
||||
## 检测体系
|
||||
|
||||
### 设计思路
|
||||
|
||||
由于录像失效来源于作者忘记 `record`,而系统无法自动区分"状态修改来自玩家操作"还是"系统内部结算"——计算机不可能判断一次属性修改是玩家打怪触发的还是战斗计算过程——因此必须由作者显式标注哪些方法会影响状态。由此设计 `@shouldReplay` 修饰器。
|
||||
|
||||
标注了哪些方法会影响状态之后,还需要界定"在什么范围内检测"。一次玩家操作可能触发若干 `@shouldReplay` 方法——它们应当在同一区间内被收容,区间结束时统一评判。因此需要 `beginReplaySafetyCollection` 和 `endReplaySafetyCollection`。区间需要知道录像是否增长——`begin` 接收 `IReplaySystem` 参数以记录初始步数。
|
||||
|
||||
仅有标注和区间还不够——有些代码路径中 `@shouldReplay` 方法确实会被调用,但录像步的写入并不在当前区间内完成。例如玩家点击购买道具,购买逻辑触发属性修改(`@shouldReplay`),但对应的 `record` 在异步事件处理中延迟执行。若不加抑制,这些场景都会误报。因此需要 `@ignoreReplay` 修饰器,标记此类延迟或被动触发路径。
|
||||
|
||||
### 接口分析
|
||||
|
||||
- 修饰器 `@shouldReplay(description: string)`:预期频率**中频**。每个影响状态的方法标注一次。
|
||||
- 修饰器 `@ignoreReplay(description: string)`:预期频率**中频**。每个需抑制误报的方法标注一次。
|
||||
- 函数 `beginReplaySafetyCollection(replay: IReplaySystem): void`:预期频率**低频**。仅出现在渲染端交互入口和沙箱播放循环两处。
|
||||
- 函数 `endReplaySafetyCollection(): void`:预期频率**低频**。与 `begin` 配对。
|
||||
|
||||
### 预期体量
|
||||
|
||||
预期代码体量 50 行。
|
||||
|
||||
- 修饰器工厂各 10 行。
|
||||
- `begin`/`end` 及区间管理预期 30 行。
|
||||
|
||||
---
|
||||
|
||||
# 实现思路
|
||||
|
||||
## 检测流程
|
||||
|
||||
1. 渲染端交互入口调用 `beginReplaySafetyCollection(replay)`。
|
||||
2. 代码执行——`@shouldReplay` 和 `@ignoreReplay` 修饰的方法被调用时向区间注册标记。
|
||||
3. 调用 `endReplaySafetyCollection()`,检查:有 `@shouldReplay` 标记、无 `@ignoreReplay` 标记、步数未增 → 警告。
|
||||
4. 沙箱每步包裹 `begin`/`end`,用于交叉验证。
|
||||
|
||||
# 涉及文件
|
||||
|
||||
## `@user/data-common/src/replay/safety.ts`
|
||||
|
||||
- [ ] 编写 `shouldReplay` 和 `ignoreReplay` 修饰器工厂
|
||||
- [ ] 编写 `beginReplaySafetyCollection` 和 `endReplaySafetyCollection` 函数
|
||||
|
||||
# 待确认问题
|
||||
|
||||
无。
|
||||
@@ -0,0 +1,210 @@
|
||||
# 需求综述
|
||||
|
||||
需要一个能录制并回放游戏过程的系统,通过录像唯一还原一段游戏流程。
|
||||
|
||||
# 需求理解
|
||||
|
||||
## 明确需求
|
||||
|
||||
1. 游戏过程可回放。能通过录像唯一地还原出游戏从起点到终点的一段完整流程。
|
||||
2. 录像步可自定义。录像步的类型不限于系统内置——移动、使用道具等——也允许作者自定义。
|
||||
|
||||
## 隐含需求
|
||||
|
||||
1. 异步播放。由于播放每个录像步都伴随渲染动画,动画未结束前不能执行下一步——播放必须是异步的。
|
||||
2. 渲染端被动通知。架构约束下渲染端不能主动拉取数据——需要钩子将每步信息推送给渲染端。
|
||||
3. 录像需跨会话持久化。录像可能录制于这次游戏,在下次游戏中被播放——需要存档。
|
||||
|
||||
## 未确定需求
|
||||
|
||||
无。
|
||||
|
||||
# 设计前提
|
||||
|
||||
1. 确定性执行。计入录像的操作在相同输入下产生相同输出。
|
||||
2. 单向依赖。录像系统位于 `@user/data-common`,不依赖 Layer 1/2。渲染端被动接收信息。
|
||||
3. 外部主动录制。系统不自动录制——作者在逻辑系统中手动调用录像步写入接口。
|
||||
4. 底层存储独立。录像的二进制存储由 `IReplayArray` 统一管理(详见 `replay-array.md`),本系统不直接操作 `ArrayBuffer`。
|
||||
|
||||
# 核心概念定义
|
||||
|
||||
## 录像步
|
||||
|
||||
一段游戏流程中不可再分的最小操作单元。由一个指令标识和一组数量可变的参数构成:指令标识区分操作类型,参数描述操作的细节。
|
||||
|
||||
## 录像
|
||||
|
||||
一组按时间顺序排列的录像步的序列。完整记录从某初始状态到某最终状态的全部操作,是还原一段游戏流程的充要条件。
|
||||
|
||||
## 录像录制
|
||||
|
||||
将玩家操作转化为录像步并通过 `IReplayArray.add` 追加到末尾的过程。由作者在各逻辑系统(商店、移动等)中主动调用写入接口完成。
|
||||
|
||||
## 录像播放
|
||||
|
||||
从 `IReplayArray` 中通过流式读取器依次取出录像步并驱动数据端状态变化的过程。由于播放时需要从初始状态逐步重建到目标状态——这是整个系统中唯一需要批量修改全局状态的场景——使用沙箱隔离播放过程。
|
||||
|
||||
# 接口设计分析
|
||||
|
||||
## `IReplaySystem`
|
||||
|
||||
### 设计思路
|
||||
|
||||
由于要还原游戏流程,需要记录玩家操作。不同操作对应不同录像步类型——因此需要 `registerCommand` 注册命令,使每种命令 ID 映射到对应的执行对象。
|
||||
|
||||
注册了命令类型后,运行时需要向 `IReplayArray` 中追加新步——因此需要 `record` 方法,接收命令 ID 和可变长度的参数,内部委托给 `IReplayArray.add`。
|
||||
|
||||
由于需要回放录像,且回放时原始录像系统仍需录制新步(做交叉验证),播放需要有独立的执行环境。此外播放前需要重置全局状态,但重置逻辑属于数据端不应被 Layer 0 直接依赖——因此需要 `createReplaySandbox` 创建沙箱,通过 `IStateReseter` 接口间接访问重置能力。播放结束需要销毁沙箱——因此需要 `releaseSandbox`。
|
||||
|
||||
由于播放期间渲染端和数据端需要切换行为,需要一个成员标记当前是否有活跃沙箱——因此需要 `replaying`。外部可能需要获取当前沙箱实例——因此需要 `sandbox` 成员。
|
||||
|
||||
### 接口分析
|
||||
|
||||
- 成员 `replaying: boolean`:预期频率**高频**。
|
||||
- 成员 `sandbox: IReplaySandbox | null`:预期频率**中频**。
|
||||
- 方法 `registerCommand(id: number, command: IReplayCommand)`:预期频率**低频**。
|
||||
- 方法 `record(id: number, ...params: ReplayParamValue[])`:预期频率**高频**。
|
||||
- 方法 `createReplaySandbox(reseter: IStateReseter, save?: Map<string, unknown>): IReplaySandbox`:预期频率**低频**。
|
||||
- 方法 `releaseSandbox()`:预期频率**低频**。
|
||||
|
||||
### 预期体量
|
||||
|
||||
预期代码体量 60-80 行。
|
||||
|
||||
- 命令注册与管理预期 15 行:`Map<number, IReplayCommand>` 的增删查。
|
||||
- 沙箱创建与销毁预期 20 行:深拷贝 `IReplayArray`、注入命令注册表和 `IStateReseter`、创建 `ReplaySandbox` 实例。
|
||||
- 存档实现预期 25 行:`saveState` 从 `IReplayArray` 导出 `ArrayBuffer` 及 `IReplayMetadata`,`loadState` 从存档数据重建 `IReplayArray` 并恢复标记。
|
||||
|
||||
## `IReplayCommand`
|
||||
|
||||
### 设计思路
|
||||
|
||||
由于作者可以自定义录像步类型,播放不同步类型时需要执行不同的操作逻辑。录像系统本身无法知晓这些逻辑,需要作者提供。这些逻辑往往需要持有数据端引用,纯函数回调无法满足——因此需要接口对象 `IReplayCommand`,作者编写实现类通过构造器持有所需引用。沙箱执行时传递当前步信息——因此 `execute` 直接接收 `IReplayStepHandler`。
|
||||
|
||||
### 接口分析
|
||||
|
||||
- 方法 `execute(step: IReplayStepHandler)`:预期频率**低频**。每个命令编写一个实现类。
|
||||
|
||||
### 预期体量
|
||||
|
||||
预期代码体量 5 行。
|
||||
|
||||
## `IReplaySandbox`
|
||||
|
||||
### 设计思路
|
||||
|
||||
由于需要回放录像,播放过程中需要流程控制——连续推进、暂停、单步前进、终止。因此需要 `play`、`pause`、`resume`、`step`、`stop` 五个方法。
|
||||
|
||||
由于需求隐含要求异步播放和渲染端被动通知——项目已有 `IHookable` 通用钩子系统,沙箱扩展 `IHookable<IReplaySandboxHook>`,每步触发钩子并 `await` 其完成。
|
||||
|
||||
由于播放期间原始录像系统仍在录制,沙箱不能引用正在增长的 `IReplayArray`——创建时深拷贝,播放时通过 `IReplayReadStream` 顺序读取每一步,避免每次随机访问的 O(n) 偏移扫描。播放速度需要调节,渲染端据此调整动画时长——因此需要 `speed` 只读成员和 `setSpeed` 方法。
|
||||
|
||||
### 接口分析
|
||||
|
||||
- 成员 `replaying: boolean`:预期频率**高频**。
|
||||
- 成员 `pausing: boolean`:预期频率**中频**。
|
||||
- 成员 `speed: number`:预期频率**中频**。播放倍率,只读。
|
||||
- 方法 `setSpeed(speed: number)`:预期频率**低频**。
|
||||
- 方法 `play()`:预期频率**低频**。
|
||||
- 方法 `pause()`:预期频率**低频**。
|
||||
- 方法 `resume()`:预期频率**低频**。
|
||||
- 方法 `stop()`:预期频率**低频**。
|
||||
- 方法 `step()`:预期频率**中频**。返回 `Promise<void>`。
|
||||
|
||||
### 预期体量
|
||||
|
||||
预期代码体量 120-160 行。
|
||||
|
||||
- 播放循环预期 80 行。在循环中通过 `IReplayReadStream.read()` 逐帧解码,传给 `IReplayCommand.execute`,再触发 `onStep` 钩子并 `await`。连续模式下循环自动推进,单步模式执行一步后挂起等待下个 `step` 调用,暂停冻结循环但不丢失索引,终止跳出循环并清空流式读取器。四种模式的状态切换组合逻辑占主要行数。
|
||||
- 状态管理预期 30 行。`play`/`pause`/`resume`/`stop`/`step` 之间的互斥与合法性检查——未播放时 `pause` 无效果,已暂停时 `resume` 才恢复,`stop` 后一切操作无效。
|
||||
- 钩子集成预期 20 行。扩展 `Hookable` 后在循环中调用 `forEachHook`,收集 `onStep` 的 Promise 并全部 `await`。
|
||||
|
||||
## `IStateReseter`
|
||||
|
||||
### 设计思路
|
||||
|
||||
由于沙箱播放前需将全局状态恢复到基准状态——从头播放恢复为初始状态,从存档继续播放恢复为存档状态。重置能力属于数据端,不应被 `@user/data-common` 直接依赖——因此设计 `IStateReseter` 接口隔离此依赖,`reset` 接收可选存档数据覆盖两种场景。
|
||||
|
||||
### 接口分析
|
||||
|
||||
- 方法 `reset(save?: Map<string, unknown>)`:预期频率**低频**。
|
||||
|
||||
### 预期体量
|
||||
|
||||
预期代码体量 3 行。
|
||||
|
||||
## `IReplaySandboxHook`
|
||||
|
||||
### 设计思路
|
||||
|
||||
由于架构约束下渲染端被动接收信息,沙箱需要钩子将每步信息推送给渲染端。项目已有 `IHookable`/`IHookBase` 体系——因此沙箱钩子扩展 `IHookBase`,提供 `onStep` 方法接收 `IReplayStepHandler`。沙箱 `await` 其完成后再推进下一步。
|
||||
|
||||
### 接口分析
|
||||
|
||||
- 方法 `onStep?(step: IReplayStepHandler): Promise<void>`:预期频率**低频**。渲染端注册时定义一次。
|
||||
|
||||
### 预期体量
|
||||
|
||||
预期代码体量 4 行。
|
||||
|
||||
## `IReplayStepHandler`
|
||||
|
||||
### 设计思路
|
||||
|
||||
由于钩子和命令执行器都需要当前步的完整信息(操作类型、参数、索引),因此设计统一的 handler 风格数据接口 `IReplayStepHandler`,包含 `id`、`params`、`index`。
|
||||
|
||||
### 接口分析
|
||||
|
||||
- 成员 `id: number`:预期频率**高频**。
|
||||
- 成员 `params: readonly ReplayParamValue[]`:预期频率**高频**。
|
||||
- 成员 `index: number`:预期频率**低频**。
|
||||
|
||||
### 预期体量
|
||||
|
||||
预期代码体量 5 行。
|
||||
|
||||
## 类型别名
|
||||
|
||||
`ReplayParamValue = number | string | boolean | bigint`
|
||||
|
||||
---
|
||||
|
||||
# 实现思路
|
||||
|
||||
## 沙箱播放与交叉验证
|
||||
|
||||
1. 创建沙箱时深拷贝当前 `IReplayArray`。
|
||||
2. 调用 `reseter.reset(save)` 重置全局状态。
|
||||
3. 创建 `IReplayReadStream`,循环:`read()` 解码一步 → `IReplayCommand.execute` → 触发 `onStep` → `await`。
|
||||
4. 原始录像系统清空并重新录制——播放中沙箱执行的命令触发 `record`,若遗漏则安全系统警告。
|
||||
|
||||
# 涉及文件
|
||||
|
||||
## `@user/data-common/src/replay/types.ts`
|
||||
|
||||
- [ ] 新增 `IReplaySystem`、`IReplaySandbox`、`IReplayCommand`、`IStateReseter`、`IReplaySandboxHook`、`IReplayStepHandler` 接口与 `ReplayParamValue` 类型别名
|
||||
|
||||
## `@user/data-common/src/replay/replay.ts`
|
||||
|
||||
- [ ] 编写 `ReplaySystem` 类:命令注册、沙箱创建、存档实现
|
||||
|
||||
## `@user/data-common/src/replay/sandbox.ts`
|
||||
|
||||
- [ ] 编写 `ReplaySandbox` 类:扩展 `Hookable` 实现 `IReplaySandbox`
|
||||
|
||||
## `@user/data-common/src/replay/array.ts`
|
||||
|
||||
- [ ] 详见 `replay-array.md`
|
||||
|
||||
## `@user/data-common/src/types.ts`
|
||||
|
||||
- [ ] 新增 `IDataCommon` 成员 `replay`
|
||||
|
||||
## `@user/data-common/src/index.ts`
|
||||
|
||||
- [ ] 新增 `export * from './replay'`
|
||||
|
||||
## `@user/data-state/src/core.ts`
|
||||
|
||||
- [ ] 新增 `ReplaySystem` 实例化与 `IStateReseter` 实现
|
||||
- [ ] 新增存档注册
|
||||
@@ -50,7 +50,9 @@
|
||||
|
||||
### 设计思路
|
||||
|
||||
> 这部分应当分析需求,并写明接口是如何设计出来的,而不是简单地阐述接口内容。
|
||||
> 这部分应当分析需求,并写明接口是如何设计出来的,而不是简单地阐述接口内容。第一句必须写为什么需要设计这个接口本身,这里是 `IObjectMover` 接口,后面才能写接口的具体内容。
|
||||
|
||||
为了实现通用的物体移动功能,因此设计 `IObjectMover` 接口,包含所有物体移动最基本的接口支持。
|
||||
|
||||
对于玩家操控,判定往往发生在移动前,因此为统一接口,设计出 `onStepStart` 与 `onStepEnd` 两个接口,前者进行判定,后者根据判定结果进行相应的操作。为了让后者知道判定结果,将 `onStepStart` 的返回值设计为 `Promise<number>`,`onStepEnd` 接收之并执行操作。
|
||||
|
||||
|
||||
Reference in new issue
Block a user