游戏引擎 / 系统课时

把生命值显示到 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。

角色状态变化如何通知 HUD 血条和分数

由角色组件维护唯一状态

先在 assets/scripts/PlayerStats.ts 中创建状态组件并挂到 Player 节点。扣血和加分只能通过公开方法修改,然后发射同一种 stats-changed 事件;HUD 不应在每帧去寻找角色或自行计算剩余生命。

ts
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 创建时还未发生事件而显示空值的问题。

ts
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;点击一次后应该显示:

text
生命值:70/100
血条进度:0.7
得分:50

再次点击后生命值继续扣除而不会变为负数,得分继续累计。禁用再启用 HUD 节点,应重新获取最新状态且只刷新一次;角色销毁或换场景时,节点事件监听随 onDisable 解除。

排查数值正确但界面不动

如果文本显示 70/100,血条仍是满的,优先检查 HPBar 的 Bar Sprite 是否正确绑定,以及 ProgressBar 的模式与 Sprite 类型是否匹配。若文字和血条都不更新,检查 BattleHud.player 是否指向实际受伤的那名角色,而非场景里的另一个副本。

验收时至少覆盖满血、半血、零血、重复扣血、HUD 隐藏后恢复五种情况。把角色状态与界面分离后,将来更换血条样式或增加受伤提示,都无需修改战斗逻辑。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

把生命值显示到 3D HUD

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通