游戏引擎 / 系统课时

让资源加载过程可失败

让资源加载过程可失败

资源路径拼错时,程序仍访问尚未得到的 SpriteFrame,就会把真正的加载错误掩盖成空值异常。本节为加载过程建立成功、失败与过期结果三条边界,先独立验证提交规则,再给出 Cocos resources.load 的真实接入与预览检查。

学习目标

  • 将加载回调封装为能拒绝的 Promise。
  • 在资源成功且请求仍有效时才更新表现。
  • 验证路径错误与组件停用后的处理。

先明确何时可以提交结果

调用加载 API 后不会马上得到资源,必须在成功回调后使用它。失败应保留原错误并给界面一个可观察状态;不能只打印错误后继续访问空资源。与此同时,组件可能在等待期间停用,所以成功也需要确认这份结果仍属于当前有效请求。

可以用版本号表达请求归属:启动时记录版本,失效时递增版本,完成时比较。版本检查只阻止应用旧结果,并没有取消底层资源请求。资源仍可能进入引擎缓存,资源释放则需要根据引用所有权另外安排。

资源完成后的提交检查

独立验证加载与提交规则

文件:main.ts,完整纯 TypeScript 程序,内存加载夹具只验证成功和失败分支。

ts
export {};
async function loadAndApply(
    load: (path: string) => Promise<string>, path: string,
    apply: (asset: string) => void,
): Promise<string> {
    try {
        const asset = await load(path);
        apply(asset);
        return 'ready';
    } catch (error: unknown) {
        return error instanceof Error ? `failed:${error.message}` : 'failed:unknown';
    }
}
async function main(): Promise<void> {
    const load = async (path: string): Promise<string> => {
        if (path !== 'hero') throw new Error('not found');
        return 'hero-frame';
    };
    // 只有成功加载才会调用 apply。
    let shown = 'placeholder';
    console.log(await loadAndApply(load, 'hero', asset => { shown = asset; }));
    console.log(await loadAndApply(load, 'missing', asset => { shown = asset; }));
    console.log(shown);
}
void main().catch((error: unknown) => { throw error; });

预期输出:

text
ready
failed:not found
hero-frame

接入 SpriteFrame 资源

文件:SafeSkin.ts,片段示例,依赖 Creator 3.8、Sprite 组件与 resources 中的图片资源。

ts
import { _decorator, Component, Sprite, SpriteFrame, resources, isValid } from 'cc';
const { ccclass, property } = _decorator;
function loadFrame(path: string): Promise<SpriteFrame> {
    return new Promise((resolve, reject) => {
        resources.load(path, SpriteFrame, (error, frame) => {
            if (error) { reject(error); return; }
            if (!frame) { reject(new Error('frame missing')); return; }
            resolve(frame);
        });
    });
}
@ccclass('SafeSkin')
export class SafeSkin extends Component {
    @property
    path = 'skins/hero/spriteFrame';
    private version = 0;
    onEnable(): void {
        const request = ++this.version;
        void this.apply(request);
    }
    onDisable(): void { this.version += 1; }
    private async apply(request: number): Promise<void> {
        try {
            const frame = await loadFrame(this.path);
            // 成功也要检查组件与当前请求归属。
            if (!isValid(this) || !this.enabledInHierarchy || request !== this.version) return;
            const sprite = this.getComponent(Sprite);
            if (!sprite) throw new Error('Sprite missing');
            sprite.spriteFrame = frame;
            console.log('skin ready');
        } catch (error: unknown) {
            if (request === this.version && isValid(this) && this.enabledInHierarchy) {
                console.error(error instanceof Error ? error.message : 'load failed');
            }
        }
    }
}

预期结果:把一张可用图片导入 assets/resources/skins,命名为 hero,确认有 SpriteFrame 子资源;在 Canvas 下可见 Sprite 节点挂 SafeSkin,Inspector 保持默认路径。保存并预览,成功后显示该图片,并输出 skin ready。

按路径与时机分别验收

resources 路径相对 assets/resources,不带文件扩展名;图片的 SpriteFrame 子资源路径通常以 spriteFrame 结尾。把 path 改成不存在的值再预览,应有加载错误,原 Sprite 表现不被无效结果覆盖。具体引擎错误文本可能不同,不以固定字符串作为验收条件。

再以正确路径预览,在完成前停用组件,完成结果应被忽略;重新启用会启动新版本请求。缓存很快时不容易人工制造等待,应重点检查版本代码并通过后续竞态例程验证规则。不要人为宣称本地预览一定出现延迟或错误。

如果回调出错,先区分加载失败和应用失败:前者检查资源目录、路径和类型,后者检查 Sprite 是否存在、组件是否有效。这里 catch 统一报告,但原错误仍保留位置。资源引用释放需要结合其他使用者决定,不能为清理旧请求随意释放共享 SpriteFrame。

为了排查同一路径在不同实例上的问题,可以记录路径和请求版本,但不要为每帧打印加载状态。加载只在启用入口发起,结果只在完成时提交;这两个位置足以说明哪一次请求成功、哪一次被丢弃,以及错误发生在资源读取还是表现应用。

引擎路径与子资源规则见 Cocos 3.8 动态资源加载。本节的终端成功证明业务加载分支;真实资源导入与显示需要在 Creator 场景里验证。

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

目录与阅读设置

阅读设置

17

记录一个想法

让资源加载过程可失败

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

登录哪都通