游戏引擎 / 系统课时

读取关卡与物品配置

读取关卡与物品配置

如果敌人数量、掉落奖励和道具效果都写在关卡脚本里,每次换关都会牵动代码。本节把关卡与物品拆成可编辑的 JSON 资源,在运行时分别加载,并通过物品 ID 关联奖励,同时检查缺失、重复与无效数据。

学习目标

  • 设计可独立编辑的关卡文件和物品数据表。
  • 使用 Cocos Creator 3.8 的 resources.load 获取 JSON 数据。
  • 通过稳定 ID 查询物品,并验证读取失败和错误关联。

准备两份资源配置

创建 assets/resources/config/levels/level-01.json,内容描述一个关卡:敌人数为 3,通关奖励为 potion-small。关卡只保存奖励 ID,不复制药水名称和效果。

json
{
  "id": "level-01",
  "enemyCount": 3,
  "rewardItemId": "potion-small"
}

再创建 assets/resources/config/items.json。同一种物品无论被多少关卡引用,都以这份表为准。

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 查找对应物品,最后将奖励名称和效果交给结算逻辑。这样修改药水回血量只需要改物品表,不必逐个改关卡。

关卡配置通过物品 ID 关联物品表的加载和查询关系

在运行时加载并校验

创建 assets/scripts/LevelConfigReader.ts,挂到游戏场景中始终启用的节点。下例并行加载两个 JsonAsset,对关卡字段和物品行做运行时检查,用 Map 建立 ID 索引,再确认奖励引用确实存在。

ts
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);
        }
    }
}

预期输出(两份资源均存在,场景预览成功):

text
关卡=level-01,敌人=3,奖励=小型药水,回血=20

该示例只负责加载、检验和查询配置,不会自动创建三个敌人或发放道具;实际玩法应在配置确认有效后,再把 enemyCount 交给生成逻辑,把奖励记录交给结算逻辑。

修改配置并排查问题

先将关卡中的 enemyCount 改为 5,重新预览,预期日志中的敌人数变为 5。再将 rewardItemId 改为 unknown-item,预期提示“奖励物品不存在”,而不是默默发放错误奖励。把 items.json 中两行的 id 改成相同值,预期提示“物品 ID 重复”。

如果出现“配置加载失败”,先确认文件在 assets/resources 下,再核对路径大小写和是否误带 .json;如果提示格式错误,检查字段拼写、整数要求和数值类型。资源包中的 JSON 可以随构建一起发布,但它并不自动实现远程热更新;大量关卡可进一步按 Asset Bundle 分组,避免把全部内容塞进一个资源目录。

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

目录与阅读设置

阅读设置

17

记录一个想法

读取关卡与物品配置

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

登录哪都通