游戏引擎 / 系统课时
把生命值显示到 3D HUD
把生命值显示到 3D HUD
角色扣血后,若屏幕上的血条仍停在满值,通常是玩法数据和 UI 之间缺少稳定的数据连接。本课在 Cocos Creator 3.8 中用角色状态组件发出变化事件,让 Canvas 上的生命值、血条和得分同步刷新,并正确清理订阅。
学习目标
- 建立角色状态与 HUD 显示之间的单向数据流。
- 使用
ProgressBar、Label与节点事件刷新生命值和得分。 - 验证初次显示、数值边界与界面启停时的订阅行为。
把 HUD 放在屏幕 UI 层
3D 玩法场景仍由主相机呈现,生命值和得分属于固定在屏幕上的 HUD,通常挂在 Canvas 下,而不是绑在角色世界坐标上。先在 Canvas 内创建 HPBar、HPText、ScoreText,把它们排在屏幕左上方,并用 Widget 做边缘适配。
为 HPBar 添加 ProgressBar,给它关联一个含 Sprite 的填充条,模式设为 HORIZONTAL。ProgressBar.progress 接收 0~1 的值,不是 0~100;HPText 和 ScoreText 则分别使用 Label.string 显示数字。如果是角色头顶随位置移动的血条,才需要额外做世界坐标到屏幕坐标的投影,本课不混用两种 HUD。

由角色组件维护唯一状态
先在 assets/scripts/PlayerStats.ts 中创建状态组件并挂到 Player 节点。扣血和加分只能通过公开方法修改,然后发射同一种 stats-changed 事件;HUD 不应在每帧去寻找角色或自行计算剩余生命。
import { _decorator, Component, CCInteger } from 'cc';
const { ccclass, property } = _decorator;
export type PlayerState = Readonly<{
hp: number;
maxHp: number;
score: number;
}>;
@ccclass('PlayerStats')
export class PlayerStats extends Component {
static readonly CHANGED = 'stats-changed';
@property({ type: CCInteger }) maxHp = 100;
private hp: number | null = null;
private score = 0;
onLoad(): void {
this.hp = Math.max(1, Math.floor(this.maxHp));
}
public getState(): PlayerState {
const max = Math.max(1, Math.floor(this.maxHp));
return { hp: this.hp ?? max, maxHp: max, score: this.score };
}
public takeDamage(value: number): void {
const damage = Number.isFinite(value) ? Math.floor(value) : 0;
if (damage <= 0) return;
const next = Math.max(0, this.getState().hp - damage);
if (next === this.getState().hp) return;
this.hp = next;
this.node.emit(PlayerStats.CHANGED, this.getState());
}
public addScore(value: number): void {
const points = Number.isFinite(value) ? Math.floor(value) : 0;
if (points <= 0) return;
this.score += points;
this.node.emit(PlayerStats.CHANGED, this.getState());
}
// 仅供测试按钮调用;正式游戏由战斗或奖励逻辑调用上面的方法。
public runDemo(): void {
this.takeDamage(30);
this.addScore(50);
}
}getState() 返回新的数值快照,让 UI 只依赖角色的当前状态。生命值下限固定为 0,最大生命值至少为 1,以免血条比例出现非法除法。重复扣血到零不会继续产生无意义的变化事件。
让 UI 订阅并呈现快照
在同目录新建 BattleHud.ts,挂到 Canvas/HUD。通过检查器分别把 Player 的 PlayerStats、HPBar 的 ProgressBar 和两个 Label 组件拖到对应字段。onEnable 负责监听,且立即读取一次状态,解决 HUD 创建时还未发生事件而显示空值的问题。
import { _decorator, Component, Label, ProgressBar } from 'cc';
import { PlayerStats, PlayerState } from './PlayerStats';
const { ccclass, property } = _decorator;
@ccclass('BattleHud')
export class BattleHud extends Component {
@property(PlayerStats) player: PlayerStats | null = null;
@property(ProgressBar) hpBar: ProgressBar | null = null;
@property(Label) hpText: Label | null = null;
@property(Label) scoreText: Label | null = null;
onEnable(): void {
if (!this.player) return;
// 同一个回调、同一个 target,才能在禁用时准确取消订阅。
this.player.node.on(PlayerStats.CHANGED, this.refresh, this);
this.refresh(this.player.getState());
}
onDisable(): void {
this.player?.node.off(PlayerStats.CHANGED, this.refresh, this);
}
private refresh(state: PlayerState): void {
if (this.hpBar) {
this.hpBar.progress = Math.max(0, Math.min(1, state.hp / state.maxHp));
}
if (this.hpText) this.hpText.string = `${state.hp}/${state.maxHp}`;
if (this.scoreText) this.scoreText.string = `${state.score}`;
}
}预期结果:预览运行后,HUD 先显示生命值 100/100、满血条和得分 0。在 Canvas 下加一个测试 Button,将其点击事件目标设为 Player,组件选 PlayerStats,处理方法选 runDemo;点击一次后应该显示:
生命值:70/100
血条进度:0.7
得分:50再次点击后生命值继续扣除而不会变为负数,得分继续累计。禁用再启用 HUD 节点,应重新获取最新状态且只刷新一次;角色销毁或换场景时,节点事件监听随 onDisable 解除。
排查数值正确但界面不动
如果文本显示 70/100,血条仍是满的,优先检查 HPBar 的 Bar Sprite 是否正确绑定,以及 ProgressBar 的模式与 Sprite 类型是否匹配。若文字和血条都不更新,检查 BattleHud.player 是否指向实际受伤的那名角色,而非场景里的另一个副本。
验收时至少覆盖满血、半血、零血、重复扣血、HUD 隐藏后恢复五种情况。把角色状态与界面分离后,将来更换血条样式或增加受伤提示,都无需修改战斗逻辑。