游戏引擎 / 系统课时
把角色属性改成配置数据
把角色属性改成配置数据
角色脚本如果直接写死生命值、移动速度和攻击力,调整平衡就需要反复改代码。本节把这些参数移到 JSON 资源,交由组件统一读取与校验,同时把当前生命值留在运行状态中,做到改数值不改玩法逻辑。
学习目标
- 区分角色的初始配置和战斗中的实时状态。
- 使用
JsonAsset为 Cocos Creator 3.8 组件提供数值。 - 验证配置格式,并通过组件接口给玩法代码读取。
分清模板参数与实时状态
maxHp、moveSpeed、attack 是设计期参数;currentHp 会随受伤、治疗变化,不应写回共享配置。比如两名敌人引用同一份数值表,也必须分别保存自己的当前生命值,否则一名敌人受伤可能污染另一名的状态。
| 数据 | 来源 | 变化时机 |
|---|---|---|
| 最大生命值、移动速度、攻击力 | JSON 配置 | 调整数值并重新加载资源 |
| 当前生命值 | 组件实例 | 受到伤害、恢复生命时 |

编写可编辑的属性文件
在项目中创建 assets/config/player-default.json。这份配置不需要进入 resources 文件夹,因为我们将直接在编辑器中绑定资源引用。
{
"maxHp": 100,
"moveSpeed": 240,
"attack": 15
}这里约定生命值为正整数,速度和攻击力为非负有限数字。JSON 只保存数据,不写函数或注释。不同角色可以使用结构相同、数值不同的 JSON 文件,而不必复制移动与战斗脚本。
在组件中读取和校验
创建 assets/scripts/PlayerStats.ts,将下列组件挂到 Player 节点。在属性检查器中,把 player-default.json 拖入 Config Asset 属性槽。onLoad 在组件初始化时读取绑定的资源,失败时不把无效数值带入战斗系统。
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);
}
}预期输出(资源已正确绑定、进入预览后):
角色属性:HP=100/100,速度=240,攻击=15接入玩法并验证改数值的效果
移动脚本从该组件的 speed 获取速度,攻击逻辑读取 attackPower,HUD 显示 hp/maxHp。对角色调用 applyDamage(20) 后,其 hp 为 80,配置中的 maxHp 仍为 100。不要把“当前生命”直接写在 JSON 上,因为资源可能被多个实例引用。
将 JSON 中 moveSpeed 改为 300 并重新运行预览,预期日志速度变成 300,其余参数不变;将 attack 改成字符串 "15",预期出现“角色配置字段不合法”,不会使用错误配置。示例的数值单位由你的移动脚本约定,若按 UI 坐标移动,可将速度理解为每秒移动的坐标单位。