游戏引擎 / 系统课时
读取关卡与物品配置
读取关卡与物品配置
如果敌人数量、掉落奖励和道具效果都写在关卡脚本里,每次换关都会牵动代码。本节把关卡与物品拆成可编辑的 JSON 资源,在运行时分别加载,并通过物品 ID 关联奖励,同时检查缺失、重复与无效数据。
学习目标
- 设计可独立编辑的关卡文件和物品数据表。
- 使用 Cocos Creator 3.8 的
resources.load获取 JSON 数据。 - 通过稳定 ID 查询物品,并验证读取失败和错误关联。
准备两份资源配置
创建 assets/resources/config/levels/level-01.json,内容描述一个关卡:敌人数为 3,通关奖励为 potion-small。关卡只保存奖励 ID,不复制药水名称和效果。
{
"id": "level-01",
"enemyCount": 3,
"rewardItemId": "potion-small"
}再创建 assets/resources/config/items.json。同一种物品无论被多少关卡引用,都以这份表为准。
{
"items": [
{ "id": "potion-small", "name": "小型药水", "heal": 20 },
{ "id": "coin", "name": "金币", "heal": 0 }
]
}把文件放在 assets/resources 下是为了通过内置 resources 资源包按路径加载。调用时使用相对于该目录的路径,不写文件扩展名;例如 config/items,不是 assets/resources/config/items.json。
让关卡通过 ID 引用物品
rewardItemId 是外键式引用。读取关卡后,先加载物品表,再以 id 查找对应物品,最后将奖励名称和效果交给结算逻辑。这样修改药水回血量只需要改物品表,不必逐个改关卡。

在运行时加载并校验
创建 assets/scripts/LevelConfigReader.ts,挂到游戏场景中始终启用的节点。下例并行加载两个 JsonAsset,对关卡字段和物品行做运行时检查,用 Map 建立 ID 索引,再确认奖励引用确实存在。
import { _decorator, Component, JsonAsset, resources } from 'cc';
const { ccclass } = _decorator;
interface LevelData {
id: string;
enemyCount: number;
rewardItemId: string;
}
interface ItemData {
id: string;
name: string;
heal: number;
}
interface ItemTable { items: ItemData[]; }
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value !== null && !Array.isArray(value);
}
function isLevel(value: unknown): value is LevelData {
return isRecord(value) &&
typeof value.id === 'string' && value.id.length > 0 &&
typeof value.enemyCount === 'number' &&
Number.isInteger(value.enemyCount) && value.enemyCount >= 0 &&
typeof value.rewardItemId === 'string' && value.rewardItemId.length > 0;
}
function isItemTable(value: unknown): value is ItemTable {
return isRecord(value) && Array.isArray(value.items) &&
value.items.every((item: unknown) =>
isRecord(item) &&
typeof item.id === 'string' && item.id.length > 0 &&
typeof item.name === 'string' &&
typeof item.heal === 'number' &&
Number.isFinite(item.heal) && item.heal >= 0);
}
@ccclass('LevelConfigReader')
export class LevelConfigReader extends Component {
private loadJson(path: string): Promise<unknown> {
return new Promise((resolve, reject) => {
// resources 路径不含扩展名,加载失败要显式处理。
resources.load(path, JsonAsset, (error, asset) => {
if (error || !asset) {
reject(error ?? new Error(`找不到配置:${path}`));
return;
}
resolve(asset.json);
});
});
}
async start(): Promise<void> {
try {
const [levelRaw, itemsRaw] = await Promise.all([
this.loadJson('config/levels/level-01'),
this.loadJson('config/items')
]);
// 异步加载期间节点可能已经销毁。
if (!this.isValid) return;
if (!isLevel(levelRaw) || !isItemTable(itemsRaw)) {
console.error('关卡或物品配置格式错误');
return;
}
const byId = new Map<string, ItemData>(
itemsRaw.items.map((item): [string, ItemData] => [item.id, item])
);
if (byId.size !== itemsRaw.items.length) {
console.error('物品 ID 重复');
return;
}
const reward = byId.get(levelRaw.rewardItemId);
if (!reward) {
console.error(`奖励物品不存在:${levelRaw.rewardItemId}`);
return;
}
console.log(`关卡=${levelRaw.id},敌人=${levelRaw.enemyCount},奖励=${reward.name},回血=${reward.heal}`);
} catch (error) {
console.error('配置加载失败', error);
}
}
}预期输出(两份资源均存在,场景预览成功):
关卡=level-01,敌人=3,奖励=小型药水,回血=20该示例只负责加载、检验和查询配置,不会自动创建三个敌人或发放道具;实际玩法应在配置确认有效后,再把 enemyCount 交给生成逻辑,把奖励记录交给结算逻辑。
修改配置并排查问题
先将关卡中的 enemyCount 改为 5,重新预览,预期日志中的敌人数变为 5。再将 rewardItemId 改为 unknown-item,预期提示“奖励物品不存在”,而不是默默发放错误奖励。把 items.json 中两行的 id 改成相同值,预期提示“物品 ID 重复”。
如果出现“配置加载失败”,先确认文件在 assets/resources 下,再核对路径大小写和是否误带 .json;如果提示格式错误,检查字段拼写、整数要求和数值类型。资源包中的 JSON 可以随构建一起发布,但它并不自动实现远程热更新;大量关卡可进一步按 Asset Bundle 分组,避免把全部内容塞进一个资源目录。