计时器玩法

关卡内的倒计时 / 正计时 HUD（内部代号 BombTimer，行为树计时器）。 策划在行为树里起一个计时器，客户端在屏幕上显示 MM:SS:CC， 剩余时间进入紧急值时切红色 + 抖动动画。
核心设计：服务器只在状态变化时下发一次， 中间的每一帧都由客户端按服务器时间戳墙钟自己推算——不吃带宽，也不会累计漂移。

1. 模块定位

1.1 三个文件的职责

1.2 两个枚举

/**
 * 行为树计时器类型枚举
 * 服务器协议映射：0=正计时, 1=倒计时
 */
export const enum EBombTimerType {
    CountUp = 0,      // 正计时（从0开始增加）
    CountDown = 1,    // 倒计时（从目标值开始减少）
}

/**
 * 行为树计时器状态枚举
 * 服务器协议映射：0=启动, 1=暂停, 2=停止
 */
export const enum EBombTimerState {
    Idle = -1,        // 空闲状态（初始状态）—— 客户端独有，服务器没有这个值
    Running = 0,     // 启动
    Paused = 1,      // 暂停
    Stopped = 2,     // 停止
}

2. 核心机制：墙钟推进

2.1 为什么不用客户端 Timer 自减

2.2 GetDisplayTime 全文

/**
 * 获取计时器显示时间（考虑服务器和客户端的延时）
 */
public GetDisplayTime(timerName: string): number {
    const timer = this.Timers.get(timerName);
    if (!timer) { return BombTimerDefineConstants.BombTimerDefaultValue; }

    const currentValue = timer.CurrentValue;
    const targetValue = timer.TargetValue;
    const timerType = timer.timerType as EBombTimerType;
    const sendTimeStamp = timer.SendTimeStamp;
    const currentState = this.MapStatusToState(timer.status);

    // 仅运行态才按墙钟推进显示值；暂停/停止/未启动时冻结在 currentValue
    // 否则未勾"默认开启"的计时器也会被误显示为正在计时
    const timeDiff = currentState === EBombTimerState.Running
        ? Time.ServerTimeStamp - sendTimeStamp
        : 0;

    let showTimeMs = 0;
    if (timerType === EBombTimerType.CountUp) {
        showTimeMs = currentValue + timeDiff;      // 正计时：往上加
    } else {
        showTimeMs = currentValue - timeDiff;      // 倒计时：往下减
    }

    if (showTimeMs > targetValue) { showTimeMs = targetValue; }    // 上钳
    if (showTimeMs < 0) { showTimeMs = 0; }                        // 下钳

    // 检查计时器是否已完成，如果完成则设置为Stopped状态
    if (currentState !== EBombTimerState.Stopped) {
        if ((timerType === EBombTimerType.CountUp && showTimeMs >= targetValue) ||
            (timerType === EBombTimerType.CountDown && showTimeMs <= 0)) {
            this.UpdateTimerState(timerName, EBombTimerState.Stopped);   // 客户端自封顶
        }
    }

    return showTimeMs;
}

2.3 客户端自封顶：为什么 Model 要主动改状态

GetDisplayTime 里有一段「算完之后如果到点了就 UpdateTimerState(Stopped)」。 这看起来违反直觉——getter 里有副作用。但这是必要的：

所以设计上是「客户端乐观地自己判完成，服务器的 Stopped 通知只是确认」。 代价就是 getter 有副作用——这在代码规范上是要打问号的， 但在这个场景里，替代方案（单开一个 tick 去扫所有计时器）成本更高。

3. 显示对象选择

/**
 * 获取应该显示的计时器名称
 * 如果有多个计时器 showUi=true，返回和当前时间最近的
 * 过滤掉 Stopped 状态的计时器
 */
public GetDisplayTimerName(): string | undefined {
    let displayTimerName: string | undefined = undefined;
    let minTimeDiff = Infinity;

    for (const [timerName, timer] of this.Timers) {
        if (timer.showUi) {
            const timerState = this.MapStatusToState(timer.status);
            if (timerState === EBombTimerState.Stopped) { continue; }

            const sendTimeStamp = timer.SendTimeStamp;
            const timeDiff = Math.abs(Time.ServerTimeStamp - sendTimeStamp);
            if (timeDiff < minTimeDiff) {         // 取最近下发的那个
                minTimeDiff = timeDiff;
                displayTimerName = timerName;
            }
        }
    }
    return displayTimerName;
}

4. 协议与数据结构

4.1 协议结构

interface IBtTimerMsg {
    timerName: string;                     // 唯一键（不是 Id，是名字）
    timerTargetValue: (number|Long);       // 目标值（毫秒）
    timerType: number;                     // 0=正计时 1=倒计时
    showUi: boolean;                       // 是否上 HUD
    emergencyValue: (number|Long);         // 紧急阈值（毫秒）
    status: number;                        // 0=启动 1=暂停 2=停止
    currentValue: (number|Long);           // 下发瞬间的值
    sendTimeStamp: (number|Long);          // 下发瞬间的服务器时间戳 —— 墙钟基准
}

4.2 Long 转 number：四个字段都要过 LongIdOps

export type TBombTimerWithExtra = Game.Protocol.IBtTimerMsg & {
    TargetValue: number;
    SendTimeStamp: number;
    EmergencyValue: number;
    CurrentValue: number;
};

public SetInfo(info: Game.Protocol.IBtTimerMsg): void {
    if (!info) { return; }
    const targetValue   = LongIdOps.GetConstrained64BitId(info.timerTargetValue, '行为树计时器-目标值');
    const sendTimeStamp = LongIdOps.GetConstrained64BitId(info.sendTimeStamp,    '行为树计时器-发送时间戳');
    const emergencyValue= LongIdOps.GetConstrained64BitId(info.emergencyValue,   '行为树计时器-紧急值');
    const currentValue  = LongIdOps.GetConstrained64BitId(info.currentValue,    '行为树计时器-当前值');

    const timerWithExtra: TBombTimerWithExtra = {
        ...info,
        TargetValue: targetValue, SendTimeStamp: sendTimeStamp,
        EmergencyValue: emergencyValue, CurrentValue: currentValue,
    };
    this.Timers.set(info.timerName, timerWithExtra);
}

4.3 唯一键是 timerName 字符串

Timers: Map<string, TBombTimerWithExtra>，键是字符串名字不是数字 Id。 好处是策划在行为树里起名就是键，不用维护 Id 表； 代价是拼错名字不会报错，只会静默地建出一个新计时器。 排查「计时器不显示」时要核对名字大小写。

5. HUD 层 LevelUiTimerView

5.1 双驱动：事件 + 50ms 轮询

private Refresh(): void {
    const displayTimerName = ControllerHolder.BombTimerController.GetDisplayTimerName();
    if (!displayTimerName) {                          // 没有可显示的 → 关 UI 停轮询
        this.ClearTimer();
        if (this.IsUiActive) { this.SetUiActive(false); this.IsUiActive = false; }
        return;
    }
    if (displayTimerName === this.CurrentDisplayTimerName && TimerSystem.Has(this.RefreshTimer)) {
        return;         // 同一个计时器且轮询还活着 → 什么都不做，避免重复起 Timer
    }
    this.CurrentDisplayTimerName = displayTimerName;
    this.OnUpdate(displayTimerName);
    if (!this.IsUiActive) { void this.PlayAnimation(EUiSequenceType.Start); }   // 隐→显才播入场
    this.SetUiActive(true);
    this.IsUiActive = true;
    this.RefreshTimer = TimerSystem.Forever(this.OnTimerRefresh, 50);
}

5.2 紧急态：两套文本 + 抖动动画

const isEmergency = ControllerHolder.BombTimerController.IsTimerEmergency(displayTimerName);

// 检测紧急状态切换
if (isEmergency && !this.IsLastEmergency) {
    void this.PlayAnimation(EUiSequenceType.Shaking);   // 只在"刚进入紧急"时播一次
}

// MM:SS:CC 三段拆分
const totalSeconds  = Math.floor(timerValue / 1000);
const minutes       = Math.floor(totalSeconds / 60);
const seconds       = totalSeconds % 60;
const milliseconds  = timerValue % 1000;
const minutesStr      = minutes.toString().padStart(2, '0');
const secondsStr      = seconds.toString().padStart(2, '0');
const millisecondsStr = Math.floor(milliseconds / 10).toString().padStart(2, '0');   // 取百分秒

if (isEmergency) {
    this.TxtLeftRed?.SetText(minutesStr); ... this.TxtLeft?.SetText(''); ...
    this.PnlTimerTipsRed?.SetUIActive(true);
    this.PnlTimerTips?.SetUIActive(false);
} else { /* 反过来 */ }
this.IsLastEmergency = isEmergency;

5.3 View 层的越界二次判定

const timerType = ModelManager.BombTimerModel?.GetTimerType(displayTimerName);
if (timerType === EBombTimerType.CountUp && timerValue > targetValue) {
    this.ClearTimer(); return;
} else if (timerType === EBombTimerType.CountDown && timerValue < 0) {
    this.ClearTimer(); return;
}

Model 的 GetDisplayTime 已经钳制过了，这里理论上永远不成立。 保留它是防御性冗余——View 不信任 Model 的钳制， 万一 Model 改了钳制逻辑，UI 也不会显示出负数。 代价是这段是死代码，读代码的人会困惑。取舍见仁见智。

6. 常见修改场景

6.1 加一个「显示优先级」字段

6.2 支持同屏显示多个计时器

这是大改。当前架构假设「HUD 只有一个」： CurrentDisplayTimerName 是单值、RefreshTimer 是单个、UI 节点是固定的 6 个 Text。 要改成多个，需要：

• GetDisplayTimerName() → GetDisplayTimerNames(): string[]
• View 改成列表 + Item 池（参考 爬塔星级 HUD 的 DungeonStarTimeItem 做法）
• 轮询 Timer 保持单个，一次 tick 刷所有 Item

6.3 排查「计时器不显示 / 显示错了」

7. 面试怎么讲