游戏引擎 / 系统课时

把角色属性改成配置数据

把角色属性改成配置数据

角色脚本如果直接写死生命值、移动速度和攻击力,调整平衡就需要反复改代码。本节把这些参数移到 JSON 资源,交由组件统一读取与校验,同时把当前生命值留在运行状态中,做到改数值不改玩法逻辑。

学习目标

  • 区分角色的初始配置和战斗中的实时状态。
  • 使用 JsonAsset 为 Cocos Creator 3.8 组件提供数值。
  • 验证配置格式,并通过组件接口给玩法代码读取。

分清模板参数与实时状态

maxHp、moveSpeed、attack 是设计期参数;currentHp 会随受伤、治疗变化,不应写回共享配置。比如两名敌人引用同一份数值表,也必须分别保存自己的当前生命值,否则一名敌人受伤可能污染另一名的状态。

数据 来源 变化时机
最大生命值、移动速度、攻击力 JSON 配置 调整数值并重新加载资源
当前生命值 组件实例 受到伤害、恢复生命时

配置参数进入角色组件并分发到玩法系统的数据流

编写可编辑的属性文件

在项目中创建 assets/config/player-default.json。这份配置不需要进入 resources 文件夹,因为我们将直接在编辑器中绑定资源引用。

json
{
  "maxHp": 100,
  "moveSpeed": 240,
  "attack": 15
}

这里约定生命值为正整数,速度和攻击力为非负有限数字。JSON 只保存数据,不写函数或注释。不同角色可以使用结构相同、数值不同的 JSON 文件,而不必复制移动与战斗脚本。

在组件中读取和校验

创建 assets/scripts/PlayerStats.ts,将下列组件挂到 Player 节点。在属性检查器中,把 player-default.json 拖入 Config Asset 属性槽。onLoad 在组件初始化时读取绑定的资源,失败时不把无效数值带入战斗系统。

ts
import { _decorator, Component, JsonAsset } from 'cc';
const { ccclass, property } = _decorator;

interface PlayerConfig {
    maxHp: number;
    moveSpeed: number;
    attack: number;
}

@ccclass('PlayerStats')
export class PlayerStats extends Component {
    @property({ type: JsonAsset })
    configAsset: JsonAsset | null = null;

    private config: PlayerConfig | null = null;
    private currentHp = 0;

    onLoad(): void {
        // 类型断言不会校验 JSON,仍需逐字段检查。
        const data = this.configAsset?.json as Partial<PlayerConfig> | null | undefined;
        if (!data || typeof data !== 'object' || Array.isArray(data)) {
            console.error('角色配置缺失或无效');
            return;
        }
        const { maxHp, moveSpeed, attack } = data;
        if (typeof maxHp !== 'number' || !Number.isInteger(maxHp) || maxHp <= 0 ||
            typeof moveSpeed !== 'number' || !Number.isFinite(moveSpeed) || moveSpeed < 0 ||
            typeof attack !== 'number' || !Number.isFinite(attack) || attack < 0) {
            console.error('角色配置字段不合法');
            return;
        }

        // 保存每个实例自己的状态,不修改 JSON 原始对象。
        this.config = { maxHp, moveSpeed, attack };
        this.currentHp = maxHp;
        console.log(`角色属性:HP=${this.currentHp}/${maxHp},速度=${moveSpeed},攻击=${attack}`);
    }

    get speed(): number { return this.config?.moveSpeed ?? 0; }
    get attackPower(): number { return this.config?.attack ?? 0; }
    get hp(): number { return this.currentHp; }
    get maxHp(): number { return this.config?.maxHp ?? 0; }

    applyDamage(amount: number): void {
        if (!this.config || !Number.isFinite(amount) || amount <= 0) return;
        this.currentHp = Math.max(0, this.currentHp - amount);
    }
}

预期输出(资源已正确绑定、进入预览后):

text
角色属性:HP=100/100,速度=240,攻击=15

接入玩法并验证改数值的效果

移动脚本从该组件的 speed 获取速度,攻击逻辑读取 attackPower,HUD 显示 hp/maxHp。对角色调用 applyDamage(20) 后,其 hp 为 80,配置中的 maxHp 仍为 100。不要把“当前生命”直接写在 JSON 上,因为资源可能被多个实例引用。

将 JSON 中 moveSpeed 改为 300 并重新运行预览,预期日志速度变成 300,其余参数不变;将 attack 改成字符串 "15",预期出现“角色配置字段不合法”,不会使用错误配置。示例的数值单位由你的移动脚本约定,若按 UI 坐标移动,可将速度理解为每秒移动的坐标单位。

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

目录与阅读设置

阅读设置

17

记录一个想法

把角色属性改成配置数据

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

登录哪都通