游戏引擎 / 系统课时
让 UI 数据跟着游戏状态变
让 UI 数据跟着游戏状态变
角色受伤后血量已经变化,界面却还显示旧数值;玩家获得金币时,又要到处寻找需要修改的 Label。本课在 Cocos Creator 3.8 中建立一条从游戏状态到 UI 的单向更新链路,使生命值、金币数量等界面内容自动跟随数据变化,并在界面重新激活时恢复正确显示。
学习目标
- 区分游戏数据和 UI 显示数据,避免直接操作界面作为业务状态。
- 使用
EventTarget发送数据变化通知,让 HUD 集中刷新。 - 正确处理初始显示、订阅清理和重复更新问题。
界面不应该成为数据来源
假设玩家拥有 100 点生命值和 0 枚金币。发生受伤事件后,游戏逻辑将生命值改为 75,同时需要更新血条、生命值文本和低血量提示。如果每个业务脚本直接寻找 Label 或 Sprite 修改显示,就容易形成多处重复逻辑。
更严重的是,当 HUD 临时隐藏、场景重建或 UI 节点尚未加载时,业务脚本可能找不到对应节点,导致数据与显示不同步。
比较可靠的做法是将职责分成三部分:
- 游戏状态:保存真正的生命值、金币等数值,负责校验和修改。
- 状态通知:数据发生有效变化时,向关心它的组件发送事件。
- 界面视图:接收通知并读取最新状态,只负责将数值转换成可见文本或进度。
游戏逻辑不应该直接把 Label.string 当作生命值存储位置。Label 只是数据的显示结果,不能作为游戏规则计算的唯一依据。
建立单向状态更新链路
本课使用一个轻量的 PlayerStore 保存玩家状态。当受伤或拾取金币发生时,先修改 Store,再发送 changed 通知,HUD 随后读取状态快照并刷新组件。

这条链路有两个必须同时成立的条件。
首先,只有状态真正变化时才发送通知,避免无效刷新。其次,UI 订阅事件后必须主动读取一次当前状态,因为界面被创建之前可能已经发生过数据变化,不能等待下一次事件才显示正确数值。
在 Cocos Creator 中,EventTarget 提供 on、off 和 emit,适合实现不依赖场景节点的轻量消息通知。数据层可以独立存在,不必为了发送状态事件创建一个隐藏节点。
实现数据仓库与 HUD 组件
新建 GameHud.ts,将玩家状态类、通知对象和 HUD 组件写在同一个示例文件中,便于直接跟做。实际项目可以将 PlayerStore 独立为数据模块,让多个界面复用。
下面的代码使用两个按钮模拟受伤和拾取金币,显示值完全来自 PlayerStore,按钮回调不直接修改 Label。
import { _decorator, Button, Component, EventTarget, Label } from 'cc';
const { ccclass, property } = _decorator;
const STATE_CHANGED = 'changed';
type PlayerSnapshot = Readonly<{
hp: number;
maxHp: number;
coins: number;
}>;
class PlayerStore {
private hp = 100;
private readonly maxHp = 100;
private coins = 0;
private readonly events = new EventTarget();
// 返回独立快照,避免界面直接修改内部状态。
snapshot(): PlayerSnapshot {
return {
hp: this.hp,
maxHp: this.maxHp,
coins: this.coins
};
}
subscribe(callback: () => void, target: object): void {
this.events.on(STATE_CHANGED, callback, target);
}
unsubscribe(callback: () => void, target: object): void {
this.events.off(STATE_CHANGED, callback, target);
}
damage(amount: number): void {
// 扣血下限为0,数值不变时不发送重复通知。
const nextHp = Math.max(0, this.hp - Math.max(0, amount));
if (nextHp === this.hp) return;
this.hp = nextHp;
this.events.emit(STATE_CHANGED);
}
collectCoin(): void {
this.coins += 1;
this.events.emit(STATE_CHANGED);
}
}
export const playerStore = new PlayerStore();
@ccclass('GameHud')
export class GameHud extends Component {
@property(Label)
hpLabel: Label | null = null;
@property(Label)
coinLabel: Label | null = null;
@property(Button)
damageButton: Button | null = null;
@property(Button)
coinButton: Button | null = null;
protected onEnable(): void {
// 先订阅,再读取快照,避免错过启用期间的变化。
playerStore.subscribe(this.refresh, this);
this.damageButton?.node.on(Button.EventType.CLICK, this.onDamage, this);
this.coinButton?.node.on(Button.EventType.CLICK, this.onCollect, this);
this.refresh();
}
protected onDisable(): void {
// on/off 使用同一回调和目标,防止失效HUD继续响应。
playerStore.unsubscribe(this.refresh, this);
this.damageButton?.node.off(Button.EventType.CLICK, this.onDamage, this);
this.coinButton?.node.off(Button.EventType.CLICK, this.onCollect, this);
}
private refresh(): void {
const data = playerStore.snapshot();
if (this.hpLabel) {
this.hpLabel.string = `生命:${data.hp}/${data.maxHp}`;
}
if (this.coinLabel) {
this.coinLabel.string = `金币:${data.coins}`;
}
}
private onDamage(): void {
playerStore.damage(25);
}
private onCollect(): void {
playerStore.collectCoin();
}
}这里的 PlayerStore 是数据的唯一修改入口。damage() 负责血量下限和无变化检查,collectCoin() 负责增加金币,HUD 只接收通知并执行 refresh()。
PlayerSnapshot 使用只读类型描述对外提供的数据,并在每次读取时创建新对象。这样界面无法通过修改返回对象中的字段改变 Store 内部值。
数据通知使用统一的 changed 事件,不需要将 UI 节点引用传给游戏逻辑。后续增加血条、金币动画或其他显示组件时,只需订阅相应状态并读取快照。
接通场景与验证显示结果
在 Canvas 下创建 HudRoot,准备两个 Label 和两个 Button,分别用于显示生命值、金币数,以及模拟受伤和拾取操作。
按照以下顺序完成场景配置:
- 创建
HpLabel和CoinLabel,为它们添加Label组件。 - 创建
DamageButton和CoinButton,设置按钮可见文字为受伤和拾取金币,并添加Button组件。 - 在
HudRoot上挂载GameHud,把两个 Label 组件拖入Hp Label、Coin Label属性,将两个 Button 组件拖入对应按钮属性。 - 保持
HudRoot初始激活,运行浏览器预览,使用两个按钮触发数据修改。
本示例的按钮监听在组件 onEnable 中自动注册,不需要再到 Button 的 Click Events 中手动添加同名响应方法。
预期页面结果:
| 操作 | 生命值显示 | 金币显示 |
|---|---|---|
| 初次运行 | 生命:100/100 | 金币:0 |
| 点击一次受伤 | 生命:75/100 | 金币:0 |
| 再点击一次受伤 | 生命:50/100 | 金币:0 |
| 点击一次拾取金币 | 生命:50/100 | 金币:1 |
| 继续受伤直到生命归零 | 生命:0/100 | 金币:1 |
如果连续受伤导致生命值已经为 0,再次点击受伤按钮,不应出现负数。由于状态没有继续变化,Store 也不会发送无效的血量变化通知。
还可以验证 UI 生命周期:临时停用 HudRoot 后,从其他游戏逻辑调用 playerStore.collectCoin() 修改状态,再重新启用 HudRoot。组件会在 onEnable 中重新订阅并读取最新快照,即使停用期间未接收事件,也能显示正确的金币数量。
处理订阅清理与更新边界
事件驱动 UI 比在每一帧检查数据更容易维护,但仍需要明确订阅和刷新边界。
组件生命周期
在 onEnable 中订阅,在 onDisable 中取消订阅,并保持回调函数和目标对象一致。这样 HUD 隐藏或销毁之后,不会继续收到发送给旧界面实例的通知。
如果某个界面需要在节点停用时继续维护数据,应让独立的数据层处理,而不是依赖已停用的显示组件接收消息。
避免把所有变化都写进 Update
不要在 HUD 的每个 update(dt) 中反复将同样的生命值、金币数写入 Label。对于只在业务操作发生时改变的属性,由数据变化事件触发刷新更直接,也能减少无意义的字符串拼接与界面更新。
本例用统一事件刷新两个数值,适合规模较小的 HUD。如果一个界面包含大量独立变化的数据,可以进一步按血量、金币、任务等类别拆分通知,或者在一帧内合并多次数据变更,再集中刷新。
处理场景切换与状态重置
示例中的 playerStore 是模块级实例,场景切换并不会自动创建一份新的玩家数据。新开局如果需要恢复 100 点生命值和 0 枚金币,应由数据层提供明确的重置操作,重置后再通知 HUD 更新。
最终需要保持的原则很简单:游戏状态负责真实数值,事件负责通知变化,UI 负责读取并呈现。 当数据来源增加、界面反复打开或跨场景重建时,这条单向链路仍然可以保持清晰,避免把同步代码散落在整个项目中。