入门篇：时间回溯系统的使用

本示例效果：

服务端代码

App.ts

typescript

import { EntityNode } from "@dao3fun/component";
import { TimeRewindSystem } from "./TimeRewindSystem";
import { TimeRewindComponent } from "./TimeRewindComponent";

/**
 * 系统默认配置
 * @property {number} maxRecordTime - 最大回溯时间（毫秒）
 * @property {number} recordInterval - 记录状态的时间间隔（毫秒）
 * @property {number} speedFactor - 回放速度因子，控制回放速度
 */
const DEFAULT_CONFIG: ISystemConfig = {
  maxRecordTime: 7500,
  recordInterval: 10,
  speedFactor: 1,
};

console.clear();
world.useOBB = true;

// 初始化系统
const sys = initTimeRewindSystem();

// 获取并配置实体
const entities = world.querySelectorAll(".time");
for (const entity of entities) {
  const node = createTimeRewindNode(entity);
  sys.addEntityNode(node);
}

// 启动初始回溯
setTimeout(() => sys.startRewind(), DEFAULT_CONFIG.maxRecordTime);

/**
 * 系统配置对象
 */
interface ISystemConfig {
  /** 最大回溯时间（毫秒） */
  maxRecordTime: number;
  /** 记录状态的时间间隔（毫秒） */
  recordInterval: number;
  /** 速度因子 */
  speedFactor: number;
}

/**
 * 初始化时间回溯系统
 * @param {Partial<ISystemConfig>} config - 可选的系统配置参数
 * @returns {TimeRewindSystem} 配置好的时间回溯系统实例
 */
function initTimeRewindSystem(
  config: Partial<ISystemConfig> = {}
): TimeRewindSystem {
  const sys = new TimeRewindSystem();
  const finalConfig = { ...DEFAULT_CONFIG, ...config };

  sys.config = {
    maxRecordTime: finalConfig.maxRecordTime,
    recordInterval: finalConfig.recordInterval,
    speedFactor: finalConfig.speedFactor,
  };

  sys.onProgress = (progress: number) => {
    remoteChannel.broadcastClientEvent({
      type: "timeRewindProgress",
      progress,
    });
  };
  sys.onEnd = () => {
    remoteChannel.broadcastClientEvent({ type: "timeRewindEnd" });
    setTimeout(() => sys.startRewind(), finalConfig.maxRecordTime);
  };

  return sys;
}

/**
 * 创建状态处理器配置
 * @param {EntityNode} node - 实体节点
 * @returns 状态处理器配置对象
 */
function createStateHandlers(node: EntityNode) {
  return {
    position: {
      get: () => node.entity.position,
      set: (value: GameVector3) =>
        node.entity.position.set(value.x, value.y, value.z),
    },
    meshOrientation: {
      get: () => node.entity.meshOrientation,
      set: (value: GameQuaternion) =>
        node.entity.meshOrientation.set(value.w, value.x, value.y, value.z),
    },
  };
}

/**
 * 创建回调函数配置
 * @param {EntityNode} node - 实体节点
 * @returns 回调函数配置对象
 */
function createCallbacks(node: EntityNode) {
  return {
    onStart: () => {
      node.entity.fixed = true;
      node.entity.gravity = false;
      node.entity.collides = false;
    },
    onEnd: () => {
      node.entity.fixed = false;
      node.entity.gravity = true;
      node.entity.collides = true;
    },
  };
}

/**
 * 创建并配置实体的时间回溯节点
 * @param {GameEntity} entity - 游戏实体
 * @returns {EntityNode} 配置好的实体节点
 */
function createTimeRewindNode(entity: GameEntity): EntityNode {
  const node = new EntityNode(entity);
  node.addComponent(TimeRewindComponent);

  const trc = node.getComponent(TimeRewindComponent);
  if (trc) {
    trc.config = {
      stateHandlers: createStateHandlers(node),
      callbacks: createCallbacks(node),
    };
  }

  return node;
}

TimeRewindComponent.ts

typescript

import { _decorator, Component } from "@dao3fun/component";
const { apclass } = _decorator;

/**
 * 状态获取器和设置器的类型定义
 */
export interface IStateHandler<T = any> {
  /** 获取状态值 */
  get: () => T;
  /** 设置状态值 */
  set: (value: T) => void;
}

/**
 * 时间回溯组件的配置接口
 * @interface IRewindConfig
 */
export interface IRewindConfig {
  /** 状态处理器映射，包含状态的获取和设置方法 */
  stateHandlers: Record<string, IStateHandler>;
  /** 回溯事件回调 */
  callbacks?: {
    /** 回溯开始时的回调函数 */
    onStart?: () => void;
    /** 回溯结束时的回调函数 */
    onEnd?: () => void;
    /** 回溯进度更新回调函数 */
    onProgress?: (progress: number) => void;
  };
}

/**
 * 时间回溯组件
 * 用于标识实体是否具有回溯功能，并存储回溯相关配置
 *
 * 该组件遵循ECS架构设计原则：
 * 1. 组件只存储数据，不包含业务逻辑
 * 2. 状态数据由TimeRewindSystem统一管理
 * 3. 组件通过事件通知系统状态变化
 *
 * @class TimeRewindComponent
 * @extends {Component<GameEntity>}
 */
@apclass()
export class TimeRewindComponent extends Component<GameEntity> {
  /**
   * 时间回溯组件的配置项
   */
  config: IRewindConfig = {
    stateHandlers: {},
    callbacks: {},
  };
}

TimeRewindSystem.ts

typescript

import { _decorator, NodeSystem } from "@dao3fun/component";
import { TimeRewindComponent } from "./TimeRewindComponent";

/**
 * 状态快照的接口定义
 * 用于存储实体在特定时间点的状态数据
 *
 * 快照设计原则：
 * 1. 时间标识：每个快照必须有唯一的时间戳
 * 2. 状态完整性：包含实体在该时间点的所有需要回溯的状态
 * 3. 实体关联：通过entityId与具体实体建立对应关系
 * 4. 数据独立性：快照数据与实体当前状态相互独立
 *
 * @interface IStateSnapshot
 * @property {number} timestamp - 快照的时间戳，记录状态保存的具体时间点
 * @property {Record<string, any>} states - 快照包含的状态数据，键为状态名，值为状态值
 * @property {string} entityId - 实体ID，用于标识状态属于哪个实体
 */
interface IStateSnapshot {
  /** 快照的时间戳 */
  timestamp: number;
  /** 快照包含的状态数据 */
  states: Record<string, any>;
  /** 实体ID */
  entityId: string;
}

/**
 * 时间回溯系统
 * 用于统一管理多个实体的回溯功能，实现游戏中的时间倒流效果
 *
 * 系统设计原则：
 * 1. 单一职责：专注于管理实体状态的记录和回放
 * 2. 数据驱动：通过快照存储和还原实体状态
 * 3. 组件解耦：与TimeRewindComponent配合，实现关注点分离
 * 4. 性能优化：使用Map存储快照，支持定期清理过期数据
 * 5. 状态一致性：确保回溯过程中实体状态的连续性和准确性
 *
 * 核心功能：
 * 1. 状态记录：定期保存实体状态快照
 * 2. 状态回放：支持按时间轴回溯实体状态
 * 3. 插值计算：实现状态之间的平滑过渡
 * 4. 内存管理：自动清理过期快照数据
 *
 * @extends {NodeSystem}
 */
export class TimeRewindSystem extends NodeSystem {
  /** 是否正在回溯中 */
  private isRewinding: boolean = false;
  /** 存储所有实体的状态快照，使用Map提高查询效率 */
  private snapshotMap: Map<string, IStateSnapshot[]> = new Map();
  /** 上次记录状态的时间戳，用于控制记录频率 */
  private lastRecordTime: number = 0;
  /** 回溯开始时间 */
  private rewindStartTime: number = 0;
  /** 回溯结束时间 */
  private rewindEndTime: number = 0;
  /**
   * 系统默认配置
   * @property {number} maxRecordTime - 最大回溯时间（毫秒）
   * @property {number} recordInterval - 记录状态的时间间隔（毫秒）
   * @property {number} speedFactor - 回放速度因子，用于控制回放速度
   */
  config = {
    maxRecordTime: 6000,
    recordInterval: 50,
    speedFactor: 1,
  };

  /**
   * 系统更新函数
   * 根据当前状态执行记录或回放操作
   *
   * 更新流程：
   * 1. 检查系统当前状态（记录/回放）
   * 2. 根据状态调用对应的处理函数
   * 3. 处理可能发生的异常情况
   *
   * @param {number} deltaTime - 帧间隔时间（毫秒）
   * @throws {Error} 当状态记录或回放过程中出现错误时抛出
   *
   * @example
   * // 在游戏主循环中调用
   * timeRewindSystem.update(16.67); // 假设60FPS
   */
  protected update(deltaTime: number): void {
    if (this.isRewinding) {
      this.rewindEntities();
    } else {
      this.recordEntities();
    }
  }

  /**
   * 记录所有实体的状态
   * 遍历所有具有TimeRewindComponent的实体，记录其当前状态
   *
   * 性能优化策略：
   * 1. 使用时间间隔控制记录频率，避免频繁记录
   * 2. 仅记录发生变化的状态
   * 3. 定期清理过期数据，避免内存占用过大
   * 4. 使用Map数据结构提高查询效率
   *
   * 记录流程：
   * 1. 检查时间间隔是否满足记录条件
   * 2. 遍历所有实体，获取TimeRewindComponent
   * 3. 调用状态获取器收集当前状态
   * 4. 创建快照并存储到对应实体的快照列表
   * 5. 清理过期快照数据
   *
   * @private
   * @throws {Error} 当状态获取器执行失败时抛出
   */
  private recordEntities(): void {
    const currentTime = Date.now();
    if (currentTime - this.lastRecordTime >= this.config.recordInterval) {
      const entities = Array.from(this.entities.values());

      for (const entity of entities) {
        if (!entity.enable) {
          continue;
        }
        const timeRewind = entity.getComponent(TimeRewindComponent);
        if (!timeRewind) continue;

        const states: Record<string, any> = {};
        for (const [key, handler] of Object.entries(
          timeRewind.config.stateHandlers
        )) {
          const value = handler.get();
          // 对获取的状态值进行深拷贝
          states[key] =
            typeof value === "object" && value !== null
              ? JSON.parse(JSON.stringify(value))
              : value;
        }

        const snapshot: IStateSnapshot = {
          timestamp: currentTime,
          states,
          entityId: entity.uuid,
        };
        if (!this.snapshotMap.has(entity.uuid)) {
          this.snapshotMap.set(entity.uuid, []);
        }
        const snapshots = this.snapshotMap.get(entity.uuid)!;
        snapshots.push(snapshot);

        // 移除过期的快照
        while (
          snapshots.length > 1 &&
          currentTime - snapshots[0].timestamp > this.config.maxRecordTime
        ) {
          snapshots.shift();
        }
      }

      this.lastRecordTime = currentTime;
    }
  }

  /**
   * 回放所有实体的状态
   * 对所有具有TimeRewindComponent的实体进行状态回放
   *
   * 回放策略：
   * 1. 根据时间戳查找目标快照
   * 2. 使用线性插值实现平滑过渡
   * 3. 支持自定义回放速度
   * 4. 处理边界时间点的状态还原
   *
   * 错误处理：
   * 1. 检查快照数据的完整性
   * 2. 处理插值计算中的边界情况
   * 3. 确保回放过程的稳定性
   * 4. 验证状态设置器的可用性
   *
   * 插值算法：
   * 1. 计算目标时间点的前后两个快照
   * 2. 根据时间差计算插值因子(0-1)
   * 3. 对每个状态属性进行线性插值
   * 4. 使用状态设置器更新实体状态
   *
   * @private
   * @throws {Error} 当快照数据不完整或状态设置器执行失败时抛出
   */
  private rewindEntities(): void {
    const entities = Array.from(this.entities.values());
    let allEntitiesFinished = true;

    for (const entity of entities) {
      if (!entity.enable) {
        continue;
      }
      const timeRewind = entity.getComponent(TimeRewindComponent);
      if (!timeRewind) continue;

      const snapshots = this.snapshotMap.get(entity.uuid);
      if (!snapshots || snapshots.length === 0) continue;

      // 根据speedFactor调整effectiveInterval，实现自定义回溯速度
      const effectiveInterval =
        this.config.recordInterval / Math.max(0.1, this.config.speedFactor);
      const lastSnapshot = snapshots[snapshots.length - 1];
      const rewindTime = lastSnapshot.timestamp - effectiveInterval;

      // 找到目标时间点的快照
      let targetIndex = snapshots.length - 1;
      while (targetIndex > 0 && snapshots[targetIndex].timestamp > rewindTime) {
        targetIndex--;
      }

      // 检查是否已经回溯到最早的快照
      if (targetIndex === 0 && snapshots[0].timestamp >= rewindTime) {
        // 如果已经到达最早的快照，标记该实体已完成回溯
        continue;
      }

      // 只要有一个实体还没完成回溯，就将标志设为false
      allEntitiesFinished = false;

      // 应用状态变化
      const targetSnapshot = snapshots[targetIndex];
      const nextSnapshot =
        snapshots[Math.min(snapshots.length - 1, targetIndex + 1)];

      // 计算插值因子
      const alpha = Math.min(
        1,
        Math.max(
          0,
          (rewindTime - targetSnapshot.timestamp) /
            (nextSnapshot.timestamp - targetSnapshot.timestamp)
        )
      );

      // 对每个状态进行插值并更新
      for (const [key, handler] of Object.entries(
        timeRewind.config.stateHandlers
      )) {
        if (key in targetSnapshot.states && key in nextSnapshot.states) {
          const targetValue = targetSnapshot.states[key];
          const nextValue = nextSnapshot.states[key];

          if (
            typeof targetValue === "number" &&
            typeof nextValue === "number"
          ) {
            handler.set(this.lerp(targetValue, nextValue, alpha));
          } else if (
            typeof targetValue === "object" &&
            targetValue !== null &&
            typeof nextValue === "object" &&
            nextValue !== null
          ) {
            // 创建插值对象的深拷贝
            const interpolatedValue: Record<string, number> = {};
            for (const prop in targetValue) {
              if (
                typeof targetValue[prop] === "number" &&
                typeof nextValue[prop] === "number"
              ) {
                interpolatedValue[prop] = this.lerp(
                  targetValue[prop],
                  nextValue[prop],
                  alpha
                );
              }
            }
            // 确保设置的是新的对象实例
            handler.set(JSON.parse(JSON.stringify(interpolatedValue)));
          } else {
            handler.set(targetValue);
          }
        }
      }

      // 移除已经回放的快照
      snapshots.splice(targetIndex + 1);

      // 计算回溯进度
      const totalDuration = this.rewindStartTime - this.rewindEndTime;
      const currentDuration = this.rewindStartTime - rewindTime;
      const rawProgress = Math.min(
        1,
        Math.max(0, currentDuration / totalDuration)
      );
      const adjustedProgress = this.easeInOutQuad(rawProgress);
      const progress = Number((1 - adjustedProgress).toFixed(3)); // 反转进度并保留3位小数

      // 通知进度更新
      if (timeRewind.config.callbacks?.onProgress) {
        timeRewind.config.callbacks.onProgress(progress);
      }
      this.onProgress?.(progress);
      // 检查回溯是否应该结束
      const isEndTimeReached = rewindTime <= this.rewindEndTime;
      const isOutOfSnapshots = snapshots.length <= 1;
      if (isEndTimeReached || isOutOfSnapshots) {
        this.stopRewind();
      }
    }
  }
  onProgress(progress: number) {}

  /**
   * 缓动函数 - 使用二次方曲线实现平滑过渡
   *
   * 该函数通过二次方曲线实现状态变化的加速和减速效果，使回溯过程更自然。
   *
   * 实现原理：
   * 1. 将插值过程分为加速和减速两个阶段
   * 2. 加速阶段（alpha < 0.5）使用二次函数实现渐进加速
   * 3. 减速阶段（alpha >= 0.5）使用二次函数实现渐进减速
   *
   * 性能优化：
   * 1. 使用Math.max和Math.min限制alpha范围，避免异常值
   * 2. 减少重复计算，提高执行效率
   *
   * @param {number} alpha - 插值因子，范围[0,1]
   * @returns {number} 缓动后的插值因子
   * @private
   */
  private easeInOutQuad(alpha: number): number {
    alpha = Math.max(0, Math.min(1, alpha));
    return alpha < 0.5
      ? 2 * alpha * alpha
      : 1 - Math.pow(-2 * alpha + 2, 2) / 2;
  }

  /**
   * 线性插值计算
   * 使用缓动函数实现平滑过渡，确保状态变化的自然和连续性
   *
   * 实现原理：
   * 1. 基于起始值和结束值计算插值
   * 2. 使用缓动函数调整插值因子，实现非线性过渡
   * 3. 确保插值结果在有效范围内
   *
   * 性能优化：
   * 1. 避免重复计算，直接使用缓动后的插值因子
   * 2. 使用加法和乘法代替更复杂的数学运算
   * 3. 减少函数调用开销，内联简单计算
   *
   * @param {number} start - 起始值
   * @param {number} end - 结束值
   * @param {number} alpha - 插值因子，范围[0,1]
   * @returns {number} 插值结果
   * @private
   */
  private lerp(start: number, end: number, alpha: number): number {
    return start + (end - start) * this.easeInOutQuad(alpha);
  }

  /**
   * 开始回溯所有实体或指定组的实体
   *
   * 回溯流程：
   * 1. 设置系统为回溯状态
   * 2. 遍历所有启用的实体
   * 3. 对具有TimeRewindComponent的实体启动回溯
   *
   * @param {number} [startTime] 回溯开始时间点，默认从最新记录开始
   * @param {number} [endTime] 回溯结束时间点，默认到最早记录
   *
   * @example
   * // 回溯最近5秒
   * const currentTime = Date.now();
   * timeRewindSystem.startRewind(currentTime, currentTime - 5000);
   */
  startRewind(startTime?: number, endTime?: number): void {
    this.isRewinding = true;
    const currentTime = Date.now();
    this.rewindStartTime = currentTime;
    this.rewindEndTime = currentTime - this.config.maxRecordTime;

    const entitiesToRewind = Array.from(this.entities.values());
    for (const entity of entitiesToRewind) {
      if (!entity.enable) {
        continue;
      }
      const timeRewind = entity.getComponent(TimeRewindComponent);
      if (timeRewind) {
        if (timeRewind.config.callbacks?.onStart) {
          timeRewind.config.callbacks.onStart();
        }
      }
    }
    this.onStart?.();
  }
  onStart() {}

  /**
   * 停止所有实体或指定组的实体的回溯
   *
   * 停止流程：
   * 1. 遍历所有启用的实体
   * 2. 对具有TimeRewindComponent的实体停止回溯
   * 3. 重置系统状态
   *
   * @example
   * // 在适当的时机停止回溯
   * timeRewindSystem.stopRewind();
   */
  stopRewind(): void {
    const entitiesToStop = Array.from(this.entities.values());
    for (const entity of entitiesToStop) {
      if (!entity.enable) {
        continue;
      }
      const timeRewind = entity.getComponent(TimeRewindComponent);
      if (timeRewind && timeRewind.config.callbacks?.onEnd) {
        timeRewind.config.callbacks.onEnd();
      }
      // 清理该实体的快照数据
      this.snapshotMap.delete(entity.uuid);
    }
    this.onEnd?.();
    // 重置系统状态
    this.isRewinding = false;
    this.lastRecordTime = 0;
    this.snapshotMap.clear();
  }
  onEnd() {}
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425

以上代码实现了一个游戏中的时间回溯（倒流）系统，允许游戏中的实体在一定时间内回退到之前的状态。以下是主要功能的解释：

核心功能

系统初始化：
- 定义了默认配置（最大回溯时间 7500ms，记录间隔 10ms）
- 创建了TimeRewindSystem实例并配置回调函数
实体管理：
- 通过选择器.time获取所有需要时间回溯功能的实体
- 为每个实体创建EntityNode并添加TimeRewindComponent
状态记录与回放：
- 系统会定期记录实体的状态（位置、旋转等）
- 可以触发回放，让实体按记录的状态逆向运动

关键组件

TimeRewindSystem：主系统，管理所有实体的时间回溯
TimeRewindComponent：附加到实体上的组件，处理单个实体的状态记录和回放
EntityNode：实体包装器，方便组件管理

工作流程

初始化系统并配置参数
查找所有需要时间回溯的实体并为其添加组件
系统开始记录实体状态（每 10ms 记录一次）
7500ms 后自动开始回放（时间倒流效果）
回放完成后重置系统，准备下一次记录

技术特点

模块化设计：系统、组件、实体分离
可配置：可以通过参数调整回溯时间、记录频率等
事件驱动：通过回调函数通知状态变化
性能优化：控制记录频率，避免过度消耗资源

这个系统适合用于实现游戏中的"时间倒流"特效，比如让被破坏的物体恢复原状，或者让角色回到之前的位置等场景。

入门篇：时间回溯系统 的使用 ​

服务端代码 ​

核心功能 ​

关键组件 ​

工作流程 ​

技术特点 ​

入门篇：时间回溯系统的使用

服务端代码

核心功能

关键组件

工作流程

技术特点