add more api docs (#13937)

* print the engine version

* refine docs

* refine docs

* refine docs

* add more docs

* fix some error

* add pipeline and task docs

* refine

* refine

* fix d.ts error

* refine and add uuid getter

* fix syntax

* refine link
This commit is contained in:
Santy-Wang
2023-01-10 12:00:45 +08:00
committed by GitHub
parent 8ac1888f16
commit e2a04dd7bd
41 changed files with 1674 additions and 1054 deletions
+4 -5
View File
@@ -24,7 +24,6 @@
import { warnID } from '../../core';
import { safeMeasureText } from './text-utils';
import { CompleteCallback, IDownloadParseOptions } from '../../asset/asset-manager/shared';
import downloader from '../../asset/asset-manager/downloader';
import factory from '../../asset/asset-manager/factory';
import { TTFFont } from '../assets/ttf-font';
@@ -35,7 +34,7 @@ const ccdocument = ccwindow.document;
interface IFontLoadHandle {
fontFamilyName: string;
refWidth: number;
onComplete: CompleteCallback;
onComplete: ((err: Error | null, data?: any | null) => void);
startTime: number;
}
@@ -110,7 +109,7 @@ function checkFontLoaded () {
}
// refer to https://github.com/typekit/webfontloader/blob/master/src/core/nativefontwatchrunner.js
function nativeCheckFontLoaded (start: number, font: string, callback: CompleteCallback): void {
function nativeCheckFontLoaded (start: number, font: string, callback: ((err: Error | null, data?: any | null) => void)): void {
const loader = new Promise<void>((resolve, reject) => {
const check = () => {
const now = Date.now();
@@ -151,7 +150,7 @@ function nativeCheckFontLoaded (start: number, font: string, callback: CompleteC
});
}
export function loadFont (url: string, options: IDownloadParseOptions, onComplete: CompleteCallback) {
export function loadFont (url: string, options: Record<string, any>, onComplete: ((err: Error | null, data?: any | null) => void)) {
const fontFamilyName = getFontFamily(url);
// Already loaded fonts
if (_fontFaces[fontFamilyName]) {
@@ -228,7 +227,7 @@ export function getFontFamily (fontHandle: string): string {
return fontFamilyName;
}
function createFont (id: string, data: string, options: IDownloadParseOptions, onComplete: CompleteCallback<TTFFont>) {
function createFont (id: string, data: string, options: Record<string, any>, onComplete: ((err: Error | null, data?: TTFFont | null) => void)) {
const out = new TTFFont();
out._nativeUrl = id;
out._nativeAsset = data;
+245 -173
View File
@@ -1,3 +1,4 @@
/* eslint-disable max-len */
/*
Copyright (c) 2019-2023 Xiamen Yaji Software Co., Ltd.
@@ -28,33 +29,27 @@ import { error, sys, Settings, settings, path, cclegacy } from '../../core';
import Bundle from './bundle';
import Cache, { ICache } from './cache';
import CacheManager from './cache-manager';
import dependUtil from './depend-util';
import downloader from './downloader';
import dependUtil, { DependUtil } from './depend-util';
import downloader, { Downloader } from './downloader';
import factory from './factory';
import fetch from './fetch';
import * as helper from './helper';
import load from './load';
import packManager from './pack-manager';
import parser from './parser';
import { IPipe, Pipeline } from './pipeline';
import parser, { Parser } from './parser';
import { Pipeline } from './pipeline';
import preprocess from './preprocess';
import releaseManager from './release-manager';
import RequestItem from './request-item';
import {
CompleteCallbackWithData,
ProgressCallback,
IBundleOptions,
IOptions,
IRemoteOptions,
presets,
Request,
references,
IJsonAssetOptions,
assets, BuiltinBundleName, bundles, fetchPipeline, files, parsed, pipeline, transformPipeline, assetsOverrideMap } from './shared';
assets, BuiltinBundleName, bundles, fetchPipeline, files, parsed, pipeline, transformPipeline, assetsOverrideMap, IRequest } from './shared';
import Task from './task';
import { combine, parse, replaceOverrideAsset } from './url-transformer';
import { asyncify, parseParameters } from './utilities';
import { IAddressableInfo, IAssetInfo, IPackInfo, ISceneInfo } from './config';
/**
* @zh
@@ -74,33 +69,33 @@ export interface IAssetManagerOptions {
/**
* @zh
* 所有 bundle 的版本信息
* 所有 bundle 的版本信息。
* @en
* Version for all bundles
* Version for all bundles.
*/
bundleVers?: Record<string, string>;
/**
* @zh
* 远程服务器地址
* 远程服务器地址。
* @en
* Remote server address
* Remote server address.
*/
server?: string;
/**
* @zh
* 配置为子包的 bundle
* 配置为子包的 bundle。
* @en
* All subpackages
* All subpackages.
*/
subpackages?: string[];
/**
* @zh
* 配置为远程包的 bundle
* 配置为远程包的 bundle。
* @en
* All remote bundles
* All remote bundles.
*/
remoteBundles?: string[];
@@ -109,85 +104,90 @@ export interface IAssetManagerOptions {
/**
* @en
* This module controls asset's behaviors and information, include loading, releasing etc. it is a singleton
* All member can be accessed with `assetManager`.
* You can access it via [[assetManager]].
*
* @zh
* 此模块管理资源的行为和信息,包括加载,释放等,这是一个单例,所有成员能够通过 `assetManager` 调用
*
* 此模块管理资源的行为和信息,包括加载,释放等,这是一个单例,你能够通过 `assetManager` 访问它。
*/
export class AssetManager {
/**
* @en
* Normal loading pipeline
* Normal loading pipeline. Asset manager uses this pipeline to load all assets, it has an additional asset parsing process compared to the fetchPipeline.
*
* @zh
* 正常加载管线
*
* 正常加载管线。Asset manager 使用此管线来加载所有资源,他与 fetchPipeline 相比额外多了资源的解析过程。
*/
public pipeline: Pipeline = pipeline.append(preprocess).append(load);
/**
* @en
* Fetching pipeline
* Fetching pipeline. Asset manager uses this pipeline to preload all assets, which lacks the asset parsing process compared to the pipeline.
*
* @zh
* 下载管线
* 下载管线。Asset manager 使用此管线来预加载所有资源,他与 pipeline 相比缺少了资源的解析过程。
*
*/
public fetchPipeline: Pipeline = fetchPipeline.append(preprocess).append(fetch);
/**
* @en
* Url transformer
* Url transformer. Asset manager uses this pipeline to convert the uuid, path, etc. to the path of the final file path to be loaded.
* You can customize this pipeline to redirect the path to the path you want.
*
* @zh
* Url 转换器
* Url 转换器。Asset manager 使用此管线将 uuid, 路径等信息转换为最终要加载的文件路径。你可以自定义此管线将路径重定向到你想要的路径。
*
*/
public transformPipeline: Pipeline = transformPipeline.append(parse).append(replaceOverrideAsset).append(combine);
/**
* @en
* The collection of bundle which is already loaded, you can remove cache with [[removeBundle]]
* The collection of bundle which is already loaded, you can remove cache with [[removeBundle]].
*
* @zh
* 已加载 bundle 的集合, 你能通过 [[removeBundle]] 来移除缓存
* 已加载 bundle 的集合, 你能通过 [[removeBundle]] 来移除缓存。
*
*/
public bundles: ICache<Bundle> = bundles;
/**
* @en
* The collection of asset which is already loaded, you can remove cache with [[releaseAsset]]
* The collection of asset which is already loaded, you can remove cache with [[releaseAsset]].
*
* @zh
* 已加载资源的集合, 你能通过 [[releaseAsset]] 来移除缓存
* 已加载资源的集合, 你能通过 [[releaseAsset]] 来移除缓存。
*/
public assets: ICache<Asset> = assets;
/**
* @internal only using in L10N for now
* @internal only using in L10N for now.
*/
public readonly assetsOverrideMap = assetsOverrideMap;
/**
* @internal
*/
public generalImportBase = '';
/**
* @internal
*/
public generalNativeBase = '';
/**
* @en
* Manage relationship between asset and its dependencies
* Manage relationship between asset and its dependencies.
*
* @zh
* 管理资源依赖关系
* 管理资源间依赖关系。
*/
public dependUtil = dependUtil;
/**
* @en
* Whether or not load asset forcibly, if it is true, asset will be loaded regardless of error
* A flag indicates whether to force loading assets and ignore errors.
*
* @zh
* 是否强制加载资源, 如果为 true ,加载资源将会忽略报错
* 是否强制加载资源标志, 如果为 true,加载资源时将会忽略错误。
*
*/
public force = EDITOR || PREVIEW;
@@ -197,57 +197,58 @@ export class AssetManager {
* Whether to use image bitmap to load image first. If enabled, images loading will become faster but memory usage will increase.
*
* @zh
* 是否优先使用 image bitmap 来加载图片,启用之后,图片加载速度会更快, 但内存占用会变高,
* 是否优先使用 image bitmap 来加载图片,启用之后,图片加载速度会更快, 但内存占用会变高。
*
*/
public allowImageBitmap = !sys.isMobile;
/**
* @en
* Some useful function
* Some useful functions, such as the convert function between url and uuid.
*
* @zh
* 一些有用的方法
* 一些有用的方法, 例如 url 与 uuid 之间的转换方法。
*
*/
public utils = helper;
/**
* @en
* Manage all downloading task
* The downloader used by `assetManager`.It manages all downloading tasks.
*
* @zh
* 管理所有下载任务
* `assetManager` 所使用的下载器,管理所有下载任务。
*
*/
public downloader = downloader;
/**
* @en
* Manage all parsing task
* The parser used by `assetManager`.It manages all parsing tasks.
*
* @zh
* 管理所有解析任务
* `assetManager` 所使用的解析器,管理所有解析任务。
*
*/
public parser = parser;
/**
* @en
* Manage all packed asset
* Manage all packed assets.
*
* @zh
* 管理所有合并后的资源
* 管理所有合并后的资源。
*
* @deprecated Since v3.7, this is an engine internal interface. You usually don't need to care about how resources are merged and split.
*/
public packManager = packManager;
/**
* @en
* Whether or not cache the loaded asset
* Whether to cache loaded assets.
*
* @zh
* 是否缓存已加载的资源
* 是否缓存已加载的资源。
*
*/
public cacheAsset = true;
@@ -257,45 +258,75 @@ export class AssetManager {
* Cache manager is a module which controls all caches downloaded from server in non-web platform.
*
* @zh
* 缓存管理器是一个模块,在非 WEB 平台上,用于管理所有从服务器上下载下来的缓存
* 缓存管理器是一个模块,在非 WEB 平台上,用于管理所有从服务器上下载下来的缓存。
*
*/
public cacheManager: CacheManager | null = null;
/**
* @en
* The preset of options
* The preset of options.
*
* @zh
* 可选参数的预设集
* 可选参数的预设集。
*
*/
public presets = presets;
/**
* @internal
*/
public factory = factory;
public preprocessPipe: IPipe = preprocess;
/**
* @internal
*/
public preprocessPipe = preprocess;
public fetchPipe: IPipe = fetch;
/**
* @internal
*/
public fetchPipe = fetch;
public loadPipe: IPipe = load;
/**
* @internal
*/
public loadPipe = load;
/**
* @internal
*/
public references = references;
private _releaseManager = releaseManager;
private _files = files;
private _parsed = parsed;
private _parsePipeline = BUILD ? null : new Pipeline('parse existing json', [this.loadPipe]);
private _projectBundles: string[] = [];
private static _instance: AssetManager;
/**
* @en
* The builtin 'main' bundle
* A global singleton instance of [[AssetManager]], which you can access directly through [[assetManager]].
*
* @zh
* 内置 main 包
* [[AssetManager]] 的全局单例,你可以直接通过 [[assetManager]] 访问。
*/
static get instance () {
if (!this._instance) {
this._instance = new AssetManager();
}
return this._instance;
}
private constructor () {}
/**
* @en
* The builtin 'main' bundle.
*
* @zh
* 内置 main 包。
*/
public get main (): Bundle | null {
return bundles.get(BuiltinBundleName.MAIN) || null;
@@ -303,10 +334,10 @@ export class AssetManager {
/**
* @en
* The builtin 'resources' bundle
* The builtin 'resources' bundle.
*
* @zh
* 内置 resources 包
* 内置 resources 包。
*
*/
public get resources (): Bundle | null {
@@ -315,13 +346,14 @@ export class AssetManager {
/**
* @en
* Initialize assetManager with options
* Initializes assetManager with options.
* This method will be called automatically when the engine starts, you should not call this method manually at any time.
*
* @zh
* 初始化资源管理器
*
* @param options - the configuration
* 初始化资源管理器,引擎在启动时,将会自动调用此方法,你不应该在任何时候手动调用此方法。
*
* @param options @en The configuration of asset manager. @zh 资源管理器的配置选项。
* @internal
*/
public init (options: IAssetManagerOptions = {}) {
const server = options.server || settings.querySettings(Settings.Category.ASSETS, 'server') || '';
@@ -355,13 +387,13 @@ export class AssetManager {
/**
* @en
* Get the bundle which has been loaded
* Gets the bundle which has been loaded with the name of bundle.
*
* @zh
* 获取已加载的分包
* 通过包名称获取已加载的分包。
*
* @param name - The name of bundle
* @return - The loaded bundle
* @param name @en The name of bundle. @zh 资源包的名称。
* @returns @en The loaded bundle. @zh 已加载的资源包。
*
* @example
* // ${project}/assets/test1
@@ -376,16 +408,14 @@ export class AssetManager {
/**
* @en
* Remove this bundle. NOTE: The asset within this bundle will not be released automatically,
* you can call [[AssetManager.Bundle.releaseAll]] manually before remove it if you need
* Removes this bundle. NOTE: The asset within this bundle will not be released automatically,
* you can call [[AssetManager.Bundle.releaseAll]] manually before removing it if you need.
*
* @zh
* 移除此包, 注意:这个包内的资源不会自动释放, 如果需要的话你可以在摧毁之前手动调用 [[AssetManager.Bundle.releaseAll]] 进行释放
* 移除此包, 注意:这个包内的资源不会自动释放, 如果需要的话你可以在摧毁之前手动调用 [[AssetManager.Bundle.releaseAll]] 进行释放。
*
* @param bundle - The bundle to be removed
* @param bundle @en The bundle to be removed. @zh 准备移除的 Bundle。
*
* @typescript
* removeBundle(bundle: AssetManager.Bundle): void
*/
public removeBundle (bundle: Bundle) {
bundle._destroy();
@@ -394,37 +424,36 @@ export class AssetManager {
/**
* @en
* General interface used to load assets with a progression callback and a complete callback. You can achieve almost all
* effect you want with combination of `requests` and `options`.It is highly recommended that you use more simple API,
* such as `load`, `loadDir` etc. Every custom parameter in `options` will be distribute to each of `requests`. if request
* already has same one, the parameter in request will be given priority. Besides, if request has dependencies, `options`
* will distribute to dependencies too. Every custom parameter in `requests` will be transferred to handler of `downloader`
* and `parser` as `options`. You can register you own handler downloader or parser to collect these custom parameters for some effect.
* General interface used to load assets with a progression callback and a complete callback.
* It is highly recommended that you use more simple API, such as `load`, `loadDir` etc. You can pass
* some additional data via the `options` parameter, and the parameters in `options` will affect this loading.
* The optional parameter will be transferred to handler of `downloader` and `parser` as `options`. You can
* register you own handler downloader or parser to collect these custom parameters for some effect.
*
* Reserved Keyword: `uuid`, `url`, `path`, `dir`, `scene`, `type`, `priority`, `preset`, `audioLoadMode`, `ext`,
* Reserved Keywords for additional parameters: `uuid`, `url`, `path`, `dir`, `scene`, `type`, `priority`, `preset`, `audioLoadMode`, `ext`,
* `bundle`, `onFileProgress`, `maxConcurrency`, `maxRequestsPerFrame`, `maxRetryCount`, `version`, `xhrResponseType`,
* `xhrWithCredentials`, `xhrMimeType`, `xhrTimeout`, `xhrHeader`, `reloadAsset`, `cacheAsset`, `cacheEnabled`,
* Please DO NOT use these words as custom options!
* Please DO NOT use these words as your own options!
*
* @zh
* 通用加载资源接口,可传入进度回调以及完成回调,通过组合 `request` 和 `options` 参数,几乎可以实现和扩展所有想要的加载效果。非常建议
* 你使用更简单的API,例如 `load`、`loadDir` 等。`options` 中的自定义参数将会分发到 `requests` 的每一项中,如果request中已存在同名的
* 参数则以 `requests` 中为准,同时如果有其他依赖资源,则 `options` 中的参数会继续向依赖项中分发。request中的自定义参数都会以 `options`
* 形式传入加载流程中的 `downloader`, `parser` 的方法中, 你可以扩展 `downloader`, `parser` 收集参数完成想实现的效果。
* 通用加载资源接口,可传入进度回调以及完成回调,建议你使用更简单的API,例如 `load`、`loadDir` 等。你可以通过 `options` 参数额外传递一些数据,`options` 中的参数将会影响本次加载。
* 额外参数会传入加载流程中的 `downloader`, `parser` 的处理方法中, 你可以扩展 `downloader`, `parser` 收集参数完成想实现的效果。
*
* 保留关键字: `uuid`, `url`, `path`, `dir`, `scene`, `type`, `priority`, `preset`, `audioLoadMode`, `ext`, `bundle`, `onFileProgress`,
* 额外参数保留关键字: `uuid`, `url`, `path`, `dir`, `scene`, `type`, `priority`, `preset`, `audioLoadMode`, `ext`, `bundle`, `onFileProgress`,
* `maxConcurrency`, `maxRequestsPerFrame`, `maxRetryCount`, `version`, `xhrResponseType`, `xhrWithCredentials`, `xhrMimeType`, `xhrTimeout`, `xhrHeader`,
* `reloadAsset`, `cacheAsset`, `cacheEnabled`, 请不要使用这些字段为自定义参数!
* `reloadAsset`, `cacheAsset`, `cacheEnabled`, 请不要使用这些字段为你自己的参数!
*
* @param requests - The request you want to load
* @param options - Optional parameters
* @param onProgress - Callback invoked when progression change
* @param onProgress.finished - The number of the items that are already completed
* @param onProgress.total - The total number of the items
* @param onProgress.item - The current request item
* @param onComplete - Callback invoked when finish loading
* @param onComplete.err - The error occurred in loading process.
* @param onComplete.data - The loaded content
* @param requests @en The loading requests. @zh 加载请求。
* @param options @en Optional parameters. @zh 可选参数。
* @param onProgress @en Callback invoked when the loading progress change. @zh 加载进度发生变化时执行的回调。
* @param onProgress.finished
* @en The number of request items that have finished loading.
* @zh 已经完成加载的资源数量。
* @param onProgress.total @en The number of all request items to be loaded. @zh 所有待加载的资源数量。
* @param onProgress.item @en The finished request item. @zh 当前完成的加载项。
* @param onComplete @en Callback invoked when all assets loaded. @zh 所有资源加载完成后的回调。
* @param onComplete.err @en Error message during loading, or null if loaded successfully. @zh 加载过程中的错误信息,如果加载成功则为 null。
* @param onComplete.data @en The loaded data, or null if an error occurred during loading. @zh 已加载的数据,如果加载过程中有错误发生,则为 null。
*
* @example
* assetManager.loadAny({url: 'http://example.com/a.png'}, (err, img) => log(img));
@@ -432,7 +461,7 @@ export class AssetManager {
* assetManager.loadAny([{ uuid: '0cbZa5Y71CTZAccaIFluuZ'}, {url: 'http://example.com/a.png'}], (err, assets) => log(assets));
* assetManager.downloader.register('.asset', (url, options, onComplete) => {
* url += '?userName=' + options.userName + "&password=" + options.password;
* assetManager.downloader.downloadFile(url, null, onComplete);
* // other logic.
* });
* assetManager.parser.register('.asset', (file, options, onComplete) => {
* var json = JSON.parse(file);
@@ -440,20 +469,20 @@ export class AssetManager {
* var model = json[options.model];
* onComplete(null, {skin, model});
* });
* assetManager.loadAny({ url: 'http://example.com/my.asset', skin: 'xxx', model: 'xxx', userName: 'xxx', password: 'xxx' });
* assetManager.loadAny({ url: 'http://example.com/my.asset' }, { skin: 'xxx', model: 'xxx', userName: 'xxx', password: 'xxx' });
*
*/
public loadAny (requests: Request, options: IOptions | null, onProgress: ProgressCallback | null, onComplete: CompleteCallbackWithData | null): void;
public loadAny (requests: Request, onProgress: ProgressCallback | null, onComplete: CompleteCallbackWithData | null): void;
public loadAny (requests: Request, options: IOptions | null, onComplete?: CompleteCallbackWithData | null): void;
public loadAny<T extends Asset> (requests: string, onComplete?: CompleteCallbackWithData<T> | null): void;
public loadAny<T extends Asset> (requests: string[], onComplete?: CompleteCallbackWithData<T[]> | null): void;
public loadAny (requests: Request, onComplete?: CompleteCallbackWithData | null): void;
public loadAny (requests: string | string[] | IRequest | Array<IRequest>, options: { [key: string]: any, preset?: string } | null, onProgress: ((finished: number, total: number, item: RequestItem) => void) | null, onComplete: ((err: Error | null, data: any) => void) | null): void;
public loadAny (requests: string | string[] | IRequest | Array<IRequest>, onProgress: ((finished: number, total: number, item: RequestItem) => void) | null, onComplete: ((err: Error | null, data: any) => void) | null): void;
public loadAny (requests: string | string[] | IRequest | Array<IRequest>, options: { [key: string]: any, preset?: string } | null, onComplete?: ((err: Error | null, data: any) => void) | null): void;
public loadAny<T extends Asset> (requests: string, onComplete?: ((err: Error | null, data: T) => void) | null): void;
public loadAny<T extends Asset> (requests: string[], onComplete?: ((err: Error | null, data: T[]) => void) | null): void;
public loadAny (requests: string | string[] | IRequest | Array<IRequest>, onComplete?: ((err: Error | null, data: any) => void) | null): void;
public loadAny (
requests: Request,
options?: IOptions | ProgressCallback | CompleteCallbackWithData | null,
onProgress?: ProgressCallback | CompleteCallbackWithData | null,
onComplete?: CompleteCallbackWithData | null,
requests: string | string[] | IRequest | Array<IRequest>,
options?: { [key: string]: any, preset?: string } | ((finished: number, total: number, item: RequestItem) => void) | ((err: Error | null, data: any) => void) | null,
onProgress?: ((finished: number, total: number, item: RequestItem) => void) | ((err: Error | null, data: any) => void) | null,
onComplete?: ((err: Error | null, data: any) => void) | null,
) {
const { options: opts, onProgress: onProg, onComplete: onComp } = parseParameters(options, onProgress, onComplete);
opts.preset = opts.preset || 'default';
@@ -466,40 +495,44 @@ export class AssetManager {
* @en
* General interface used to preload assets with a progression callback and a complete callback.It is highly recommended that you use
* more simple API, such as `preloadRes`, `preloadResDir` etc. Everything about preload is just likes `assetManager.loadAny`, the
* difference is `assetManager.preloadAny` will only download asset but not parse asset. You need to invoke `assetManager.loadAny(preloadTask)`
* difference is `assetManager.preloadAny` will only download asset but not parse asset. You need to invoke `assetManager.loadAny()`
* to finish loading asset
*
* @zh
* 通用预加载资源接口,可传入进度回调以及完成回调,非常建议你使用更简单的 API ,例如 `preloadRes`, `preloadResDir` 等。`preloadAny` 和 `loadAny`
* 几乎一样,区别在于 `preloadAny` 只会下载资源,不会去解析资源,你需要调用 `assetManager.loadAny(preloadTask)` 来完成资源加载。
* 几乎一样,区别在于 `preloadAny` 只会下载资源,不会去解析资源,你需要调用 `assetManager.loadAny()` 来完成资源加载。
*
* @param requests - The request you want to preload
* @param options - Optional parameters
* @param onProgress - Callback invoked when progression change
* @param onProgress.finished - The number of the items that are already completed
* @param onProgress.total - The total number of the items
* @param onProgress.item - The current request item
* @param onComplete - Callback invoked when finish preloading
* @param onComplete.err - The error occurred in preloading process.
* @param onComplete.items - The preloaded content
* @param requests @en The preloading requests. @zh 预加载请求。
* @param options @en Optional parameters. @zh 可选参数。
* @param onProgress @en Callback invoked when the preloading progress change. @zh 预加载进度发生变化时执行的回调。
* @param onProgress.finished
* @en The number of request items that have finished preloading.
* @zh 已经完成加载的资源数量。
* @param onProgress.total @en The number of all request items to be preloaded. @zh 所有待预加载的资源数量。
* @param onProgress.item @en The finished request item. @zh 当前完成的预加载项。
* @param onComplete @en Callback invoked when all assets preloaded. @zh 所有资源预加载完成后的回调。
* @param onComplete.err
* @en The error occurred in preloading process. Or null if preloaded successfully.
* @zh 预加载过程中的发生的错误,如果预加载成功则为 null。
* @param onComplete.items @en The preloaded content. @zh 完成预加载的内容。
*
* @example
* assetManager.preloadAny('0cbZa5Y71CTZAccaIFluuZ', (err) => assetManager.loadAny('0cbZa5Y71CTZAccaIFluuZ'));
*
*/
public preloadAny (
requests: Request,
options: IOptions | null,
onProgress: ProgressCallback | null,
onComplete: CompleteCallbackWithData<RequestItem[]>|null): void;
public preloadAny (requests: Request, onProgress: ProgressCallback | null, onComplete: CompleteCallbackWithData<RequestItem[]> | null): void;
public preloadAny (requests: Request, options: IOptions | null, onComplete?: CompleteCallbackWithData<RequestItem[]> | null): void;
public preloadAny (requests: Request, onComplete?: CompleteCallbackWithData<RequestItem[]> | null): void;
requests: string | string[] | IRequest | Array<IRequest>,
options: { [key: string]: any, preset?: string } | null,
onProgress: ((finished: number, total: number, item: RequestItem) => void) | null,
onComplete: ((err: Error | null, data: RequestItem[]) => void)|null): void;
public preloadAny (requests: string | string[] | IRequest | Array<IRequest>, onProgress: ((finished: number, total: number, item: RequestItem) => void) | null, onComplete: ((err: Error | null, data: RequestItem[]) => void) | null): void;
public preloadAny (requests: string | string[] | IRequest | Array<IRequest>, options: { [key: string]: any, preset?: string } | null, onComplete?: ((err: Error | null, data: RequestItem[]) => void) | null): void;
public preloadAny (requests: string | string[] | IRequest | Array<IRequest>, onComplete?: ((err: Error | null, data: RequestItem[]) => void) | null): void;
public preloadAny (
requests: Request,
options?: IOptions | ProgressCallback | CompleteCallbackWithData<RequestItem[]> | null,
onProgress?: ProgressCallback | CompleteCallbackWithData<RequestItem[]> | null,
onComplete?: CompleteCallbackWithData<RequestItem[]> | null,
requests: string | string[] | IRequest | Array<IRequest>,
options?: { [key: string]: any, preset?: string } | ((finished: number, total: number, item: RequestItem) => void) | ((err: Error | null, data: RequestItem[]) => void) | null,
onProgress?: ((finished: number, total: number, item: RequestItem) => void) | ((err: Error | null, data: RequestItem[]) => void) | null,
onComplete?: ((err: Error | null, data: RequestItem[]) => void) | null,
) {
const { options: opts, onProgress: onProg, onComplete: onComp } = parseParameters(options, onProgress, onComplete);
opts.preset = opts.preset || 'preload';
@@ -510,18 +543,25 @@ export class AssetManager {
/**
* @en
* Load remote asset with url, such as audio, image, text and so on.
* Loads remote asset with url, such as audio, image, text and so on.
* Note that `loadRemote` uses the extension name in the url to determine how to load the asset.
* If you pass in a url without the extension name, you need to specify the `ext` parameter
* in the `options` to indicate how you want the asset loaded. See the third example below.
*
* @zh
* 使用 url 加载远程资源,例如音频,图片,文本等等。
* 使用 url 加载远程资源,例如音频,图片,文本等等。需要注意的是 `loadRemote` 是通过 url 中的扩展名判断以何种方式加载该资源,
* 如果你传入的 url 中没有携带后缀名,你需要额外指定 `options` 中的 `ext` 参数来表明你需要何种方式加载该资源。请参考下面的第三个示例。
*
* @param url - The url of asset
* @param options - Some optional parameters
* @param options.audioLoadMode - Indicate which mode audio you want to load
* @param options.ext - If the url does not have a extension name, you can specify one manually.
* @param onComplete - Callback invoked when finish loading
* @param onComplete.err - The error occurred in loading process.
* @param onComplete.asset - The loaded texture
* @param url @en The url of asset. @zh 资源的 URL 链接。
* @param options @en Some optional parameters. @zh 一些可选参数。
* @param options.ext
* @en If the url does not have an extension name, you can specify one manually. This will affect the way the assets are loaded.
* @zh 如果 URL 链接中没有包含扩展名,你可以手动指定一个扩展名。这将会影响资源的加载方式。
* @param onComplete @en Callback invoked when finish loading. @zh 当完成加载时触发的回调函数。
* @param onComplete.err @en The error occurred in loading process. Or null if loaded successfully. @zh 加载过程中出现的错误,如果加载成功则为 null。
* @param onComplete.asset
* @en The loaded asset. If there is an error in the loading process, this asset will be null.
* @zh 加载好的资源,如果加载过程出现了错误,资源将会 null。
*
* @example
* assetManager.loadRemote('http://www.cloud.com/test1.jpg', (err, texture) => console.log(err));
@@ -529,10 +569,10 @@ export class AssetManager {
* assetManager.loadRemote('http://www.cloud.com/test3', { ext: '.png' }, (err, texture) => console.log(err));
*
*/
public loadRemote<T extends Asset> (url: string, options: IRemoteOptions | null, onComplete?: CompleteCallbackWithData<T> | null): void;
public loadRemote<T extends Asset> (url: string, onComplete?: CompleteCallbackWithData<T> | null): void;
public loadRemote<T extends Asset> (url: string, options?: IRemoteOptions | CompleteCallbackWithData<T> | null, onComplete?: CompleteCallbackWithData<T> | null) {
const { options: opts, onComplete: onComp } = parseParameters<CompleteCallbackWithData<T>>(options, undefined, onComplete);
public loadRemote<T extends Asset> (url: string, options: { [k: string]: any, ext?: string } | null, onComplete?: ((err: Error | null, data: T) => void) | null): void;
public loadRemote<T extends Asset> (url: string, onComplete?: ((err: Error | null, data: T) => void) | null): void;
public loadRemote<T extends Asset> (url: string, options?: { [k: string]: any, ext?: string } | ((err: Error | null, data: T) => void) | null, onComplete?: ((err: Error | null, data: T) => void) | null) {
const { options: opts, onComplete: onComp } = parseParameters<((err: Error | null, data: T) => void)>(options, undefined, onComplete);
if (!opts.reloadAsset && this.assets.has(url)) {
asyncify(onComp)(null, this.assets.get(url));
@@ -555,26 +595,42 @@ export class AssetManager {
/**
* @en
* load bundle
* loads bundle with bundle name or URL. When you have configured a bundle in your project, you can load the bundle by the name configured in your project.
* Or when you put the bundle on the server, you can also load it by the full url address.
*
* Note: When you load a remote bundle by name, the bundle will be cached locally after download and will continue to use that cache in future, even if
* the version of the bundle file on your server has changed. When you need to load the latest bundle, you can pass an additional `version` parameter in the
* optional parameters and the asset system will compare this version number with the local cache, if the comparison fails, the asset system will pull
* the latest version of the bundle data from the server again.
*
* @zh
* 加载资源包
* 通过包名称或 url 加载资源包。当你在项目中配置了 Bundle 后,你可以通过项目中配置的名称来加载该 Bundle。
* 或者当你将 bundle 放在服务器上时,你也可以通过完整的 url 地址进行加载。
*
* @param nameOrUrl - The name or root path of bundle
* @param options - Some optional paramter, same like downloader.downloadFile
* @param options.version - The version of this bundle, you can check config.json in this bundle
* @param onComplete - Callback when bundle loaded or failed
* @param onComplete.err - The occurred error, null indicates success
* @param onComplete.bundle - The loaded bundle
* 注意:当你用名称加载远程 bundle 时,该 bundle 在下载后将会缓存在本地并在后续持续使用该缓存,即使你服务器上的 bundle 文件版本已经发生变化。当你需要加载
* 最新的 bundle 时,你可以在可选参数中额外传入一个 `version` 参数,资源系统将比对此版本号与本地缓存是否一致,如果比对失败,则资源系统将重新从服务器上拉取
* 最新版本的 bundle 数据。
*
* @param nameOrUrl @en The name or root path of bundle. @zh 待加载的 bundle 在项目中的名称或在服务器上的 url 路径。
* @param options @en Some optional parameters. @zh 一些可选参数。
* @param options.version
* @en The version of the bundle, which you can get in the editor's build system, or directly by looking at the md5 hash value in the `config.json` path in the bundle directory after the build.
* @zh bundle 的版本号,你可以在编辑器的构建系统中获取,或者直接查看构建后的 bundle 目录中 config.json 路径中的 md5 hash 值。
* @param onComplete @en Callback invoked when bundle loaded or failed. @zh bundle 加载完成的回调。
* @param onComplete.err @en The occurred error during the loading, Or null if loaded successfully. @zh 加载过程中发生的错误,如果加载成功则为 null。
* @param onComplete.bundle
* @en The loaded bundle. If there is an error in the loading process, this bundle will be null.
* @zh 加载完成的 bundle。如果加载过程中出现了错误,则为 null。
*
* @example
* loadBundle('myBundle', (err, bundle) => console.log(bundle));
* loadBundle('http://localhost:8080/test', null, (err, bundle) => console.log(err));
*
*/
public loadBundle (nameOrUrl: string, options: IBundleOptions | null, onComplete?: CompleteCallbackWithData<Bundle> | null): void;
public loadBundle (nameOrUrl: string, onComplete?: CompleteCallbackWithData<Bundle> | null): void;
public loadBundle (nameOrUrl: string, options?: IBundleOptions | CompleteCallbackWithData<Bundle> | null, onComplete?: CompleteCallbackWithData<Bundle> | null) {
const { options: opts, onComplete: onComp } = parseParameters<CompleteCallbackWithData<Bundle>>(options, undefined, onComplete);
public loadBundle (nameOrUrl: string, options: { [k: string]: any, version?: string } | null, onComplete?: ((err: Error | null, data: Bundle) => void) | null): void;
public loadBundle (nameOrUrl: string, onComplete?: ((err: Error | null, data: Bundle) => void) | null): void;
public loadBundle (nameOrUrl: string, options?: { [k: string]: any, version?: string } | ((err: Error | null, data: Bundle) => void) | null, onComplete?: ((err: Error | null, data: Bundle) => void) | null) {
const { options: opts, onComplete: onComp } = parseParameters<((err: Error | null, data: Bundle) => void)>(options, undefined, onComplete);
const bundleName = path.basename(nameOrUrl);
@@ -611,7 +667,7 @@ export class AssetManager {
* 比如说,当你释放一个 texture 资源,这个 texture 和它的 gl 贴图数据都会被释放。
* 注意,这个函数可能会导致资源贴图或资源所依赖的贴图不可用,如果场景中存在节点仍然依赖同样的贴图,它们可能会变黑并报 GL 错误。
*
* @param asset - The asset to be released
* @param asset @en The asset to be released. @zh 被释放的资源。
*
* @example
* // release a texture which is no longer need
@@ -627,7 +683,7 @@ export class AssetManager {
* Release all unused assets. Refer to [[releaseAsset]] for detailed information.
*
* @zh
* 释放所有没有用到的资源。详细信息请参考 [[releaseAsset]]
* 释放所有没有用到的资源。详细信息请参考 [[releaseAsset]]。
*
* @engineInternal
*
@@ -643,7 +699,7 @@ export class AssetManager {
* Release all assets. Refer to [[releaseAsset]] for detailed information.
*
* @zh
* 释放所有资源。详细信息请参考 [[releaseAsset]]
* 释放所有资源。详细信息请参考 [[releaseAsset]]。
*
*/
public releaseAll () {
@@ -657,25 +713,25 @@ export class AssetManager {
* @param json
* @param options
* @param onComplete
* @private
* @internal
*/
public loadWithJson<T extends Asset> (
json: Record<string, any>,
options: IJsonAssetOptions | null,
onProgress: ProgressCallback | null,
onComplete: CompleteCallbackWithData<T> | null): void;
public loadWithJson<T extends Asset> (json: Record<string, any>, onProgress: ProgressCallback | null, onComplete: CompleteCallbackWithData<T> | null): void;
public loadWithJson<T extends Asset> (json: Record<string, any>, options: IJsonAssetOptions | null, onComplete?: CompleteCallbackWithData<T> | null): void;
public loadWithJson<T extends Asset> (json: Record<string, any>, onComplete?: CompleteCallbackWithData<T> | null): void;
options: { [key: string]: any, assetId?: string } | null,
onProgress: ((finished: number, total: number, item: RequestItem) => void) | null,
onComplete: ((err: Error | null, data: T) => void) | null): void;
public loadWithJson<T extends Asset> (json: Record<string, any>, onProgress: ((finished: number, total: number, item: RequestItem) => void) | null, onComplete: ((err: Error | null, data: T) => void) | null): void;
public loadWithJson<T extends Asset> (json: Record<string, any>, options: { [key: string]: any, assetId?: string }, onComplete?: ((err: Error | null, data: T) => void) | null): void;
public loadWithJson<T extends Asset> (json: Record<string, any>, onComplete?: ((err: Error | null, data: T) => void) | null): void;
public loadWithJson<T extends Asset> (
json: Record<string, any>,
options?: IJsonAssetOptions | CompleteCallbackWithData<T> | null,
onProgress?: ProgressCallback | CompleteCallbackWithData<T> | null,
onComplete?: CompleteCallbackWithData<T> | null,
options?: { [key: string]: any, assetId?: string } | ((err: Error | null, data: T) => void) | null,
onProgress?: ((finished: number, total: number, item: RequestItem) => void) | ((err: Error | null, data: T) => void) | null,
onComplete?: ((err: Error | null, data: T) => void) | null,
) {
if (BUILD) { throw new Error('Only valid in Editor'); }
const { options: opts, onProgress: onProg, onComplete: onComp } = parseParameters<CompleteCallbackWithData<T>>(options, onProgress, onComplete);
const { options: opts, onProgress: onProg, onComplete: onComp } = parseParameters<((err: Error | null, data: T) => void)>(options, onProgress, onComplete);
const item = RequestItem.create();
item.isNative = false;
@@ -706,6 +762,10 @@ AssetManager.Cache = Cache;
AssetManager.RequestItem = RequestItem;
AssetManager.Bundle = Bundle;
AssetManager.BuiltinBundleName = BuiltinBundleName;
AssetManager.CacheManager = CacheManager;
AssetManager.Downloader = Downloader;
AssetManager.Parser = Parser;
AssetManager.DependUtil = DependUtil;
export declare namespace AssetManager {
export { Pipeline };
@@ -714,7 +774,19 @@ export declare namespace AssetManager {
export { RequestItem };
export { Bundle };
export { BuiltinBundleName };
export { CacheManager };
export type { ICache };
export type { IAssetInfo, IPackInfo, IAddressableInfo, ISceneInfo, IRequest };
export { DependUtil };
export { Downloader };
export { Parser };
}
export default cclegacy.assetManager = new AssetManager();
/**
* @en `assetManager` is a global singleton instance of [[AssetManager]].
* The engine uses `assetManager` to manage all asset and asset bundle, including loading, releasing, etc.
* @zh `assetManager` 为 [[AssetManager]] 的全局单例,引擎使用 `assetManager` 来完成所有资源和资源包的管理工作,包括加载,释放等。
*/
const assetManager = cclegacy.assetManager = AssetManager.instance;
export default assetManager;
cclegacy.AssetManager = AssetManager;
+235 -190
View File
@@ -1,3 +1,4 @@
/* eslint-disable max-len */
/*
Copyright (c) 2019-2023 Xiamen Yaji Software Co., Ltd.
@@ -28,23 +29,23 @@ import { error, errorID, cclegacy } from '../../core';
import Config, { IAddressableInfo, IAssetInfo, IConfigOption, ISceneInfo } from './config';
import releaseManager from './release-manager';
import RequestItem from './request-item';
import { assets, AssetType, bundles, CompleteCallbackWithData, CompleteCallbackNoData, IAssetOptions, ProgressCallback, RequestType } from './shared';
import { assets, bundles, RequestType } from './shared';
import { parseLoadResArgs, parseParameters } from './utilities';
/**
* @en
* A bundle contains an amount of assets(includes scene), you can load, preload, release asset which is in this bundle
* A bundle contains an amount of assets(includes scene), you can load, preload, release asset which is in this bundle.
*
* @zh
* 一个包含一定数量资源(包括场景)的包,你可以加载,预加载,释放此包内的资源
* 一个包含一定数量资源(包括场景)的包,你可以加载,预加载,释放此包内的资源。
*
*/
export default class Bundle {
private _config: Config = new Config();
/**
* for internal use
* @private
* For internal use.
* @engineInternal
*/
public get config (): Config {
return this._config;
@@ -52,10 +53,10 @@ export default class Bundle {
/**
* @en
* The name of this bundle
* The name of this bundle.
*
* @zh
* 此 bundle 的名称
* 此 bundle 的名称。
*
*/
public get name (): string {
@@ -64,10 +65,10 @@ export default class Bundle {
/**
* @en
* The dependency of this bundle
* The dependent bundles of this bundle.
*
* @zh
* 此 bundle 的依赖
* 此 bundle 的依赖包。
*
*/
public get deps (): string[] {
@@ -76,10 +77,10 @@ export default class Bundle {
/**
* @en
* The root path of this bundle, such like 'http://example.com/bundle1'
* The root path of this bundle, such like 'http://example.com/bundle1'.
*
* @zh
* 此 bundle 的根路径, 例如 'http://example.com/bundle1'
* 此 bundle 的根路径, 例如 'http://example.com/bundle1'。
*
*/
public get base (): string {
@@ -88,56 +89,57 @@ export default class Bundle {
/**
* @en
* Get asset's info using path, only valid when asset is in bundle folder.
* Gets asset's info using path, only valid when asset is in bundle folder.
*
* @zh
* 使用 path 获取资源的配置信息
* 使用 path 获取资源的配置信息。
*
* @param path - The relative path of asset, such as 'images/a'
* @param type - The constructor of asset, such as `Texture2D`
* @returns The asset info
* @param path @en The relative path of asset, such as 'images/a'. @zh 资源的相对路径,例如 `images/a`。
* @param type @en The constructor of asset, such as `Texture2D`. @zh 资源的类型,例如 [[Texture2D]]。
* @returns @en The asset info. @zh 资源的信息。
*
* @example
* var info = bundle.getInfoWithPath('image/a', Texture2D);
* const info = bundle.getInfoWithPath('image/a', Texture2D);
*
*/
public getInfoWithPath (path: string, type?: AssetType | null): IAddressableInfo | null {
public getInfoWithPath (path: string, type?: Constructor<Asset> | null): IAddressableInfo | null {
return this._config.getInfoWithPath(path, type);
}
/**
* @en
* Get all asset's info within specific folder
* Gets all asset's info within specific folder.
*
* @zh
* 获取在某个指定文件夹下的所有资源信息
* 获取在某个指定文件夹下的所有资源信息。
*
* @param path - The relative path of folder, such as 'images'
* @param type - The constructor should be used to filter paths
* @param out - The output array
* @returns Infos
* @param path @en The relative path of folder, such as 'images'. @zh 文件夹的相对路径,例如 `images`。
* @param type
* @en The asset type, can be used to find the information of the specified type of asset in the directory.
* @zh 资源的类型,指定后可以用来查找目录下指定类型的资源信息。
* @param out @en The output array. @zh 输出数组。
* @returns @en Queried asset information. @zh 查询到的资源信息。
*
* @example
* var infos = [];
* const infos = [];
* bundle.getDirWithPath('images', Texture2D, infos);
*/
public getDirWithPath (path: string, type?: AssetType | null, out?: IAddressableInfo[]): IAddressableInfo[] {
public getDirWithPath (path: string, type?: Constructor<Asset> | null, out?: IAddressableInfo[]): IAddressableInfo[] {
return this._config.getDirWithPath(path, type, out);
}
/**
* @en
* Get asset's info with uuid
* Get asset's information with uuid.
*
* @zh
* 通过 uuid 获取资源信息
* 通过 uuid 获取资源信息。
*
* @method getAssetInfo
* @param uuid - The asset's uuid
* @returns info
* @param uuid @en The asset's uuid. @zh 资源的 uuid。
* @returns @en The information of asset. @zh 资源的信息。
*
* @example
* var info = bundle.getAssetInfo('fcmR3XADNLgJ1ByKhqcC5Z');
* const info = bundle.getAssetInfo('fcmR3XADNLgJ1ByKhqcC5Z');
*
*/
public getAssetInfo (uuid: string): IAssetInfo | null {
@@ -146,17 +148,16 @@ export default class Bundle {
/**
* @en
* Get scene'info with name
* Gets scene's information with name.
*
* @zh
* 通过场景名获取场景信息
* 通过场景名获取场景信息。
*
* @method getSceneInfo
* @param name - The name of scene
* @return info
* @param name @en The name of scene. @zh 场景名称。
* @returns @en The information of scene. @zh 场景信息。
*
* @example
* var info = bundle.getSceneInfo('first.fire');
* const info = bundle.getSceneInfo('first.fire');
*
*/
public getSceneInfo (name: string): ISceneInfo | null {
@@ -165,12 +166,13 @@ export default class Bundle {
/**
* @en
* Initialize this bundle with options
* Initializes this bundle with options.
*
* @zh
* 初始化此 bundle
* 初始化此 bundle。
*
* @param options
* @deprecate Since v3.7, this is an internal engine interface and you should not call this interface under any circumstances.
*
*/
public init (options: IConfigOption) {
@@ -180,20 +182,30 @@ export default class Bundle {
/**
* @en
* Load the asset within this bundle by the path which is relative to bundle's path
* Loads the asset within this bundle by the path which is relative to bundle's path.
*
* @zh
* 通过相对路径加载分包中的资源。路径是相对分包文件夹路径的相对路径
* 通过相对路径加载分包中的资源。路径是相对分包文件夹路径的相对路径。
*
* @param paths - Paths of the target assets.The path is relative to the bundle's folder, extensions must be omitted.
* @param type - Only asset of type will be loaded if this argument is supplied.
* @param onProgress - Callback invoked when progression change.
* @param onProgress.finish - The number of the items that are already completed.
* @param onProgress.total - The total number of the items.
* @param onProgress.item - The finished request item.
* @param onComplete - Callback invoked when all assets loaded.
* @param onComplete.error - The error info or null if loaded successfully.
* @param onComplete.assets - The loaded assets.
* @param paths
* @en Paths of the target assets.These paths are relative to the bundle's folder, extension name must be omitted.
* @zh 需要加载的资源的路径。此路径为工程中相对于 bundle 文件夹的相对路径,路径中请不要带扩展名。
* @param type
* @en Asset type, if this parameter is passed, the asset of the corresponding type will be found in the assets of the corresponding path to finish loading.
* @zh 资源类型,如果传入此参数,则会在对应路径的资源中找到对应类型的资源完成加载。
* @param onProgress
* @en Callback invoked when the loading progress change.
* @zh 加载进度发生变化时执行的回调。
* @param onProgress.finish
* @en The number of request items that have been loaded.
* @zh 已经完成加载的资源数量。
* @param onProgress.total
* @en The number of all request items to be loaded.
* @zh 所有待加载的资源数量。
* @param onProgress.item @en The finished request item. @zh 当前完成的加载项。
* @param onComplete @en Callback invoked when all assets loaded. @zh 所有资源加载完成后的回调。
* @param onComplete.error @en Error message during loading, or null if loaded successfully. @zh 加载过程中的错误信息,如果加载成功则为 null。
* @param onComplete.assets @en The loaded asset, or null if an error occurred during loading. @zh 已加载的资源,如果加载过程中有错误发生,则为 null。
*
* @example
* // load the texture (${project}/assets/resources/textures/background.jpg) from resources
@@ -211,24 +223,24 @@ export default class Bundle {
*/
public load<T extends Asset> (
paths: string,
type: AssetType<T> | null,
onProgress: ProgressCallback | null,
onComplete: CompleteCallbackWithData<T> | null): void;
type: Constructor<T> | null,
onProgress: ((finished: number, total: number, item: RequestItem) => void) | null,
onComplete: ((err: Error | null, data: T) => void) | null): void;
public load<T extends Asset> (
paths: string[], type: AssetType<T> | null,
onProgress: ProgressCallback | null,
onComplete: CompleteCallbackWithData<T[]> | null): void;
public load<T extends Asset> (paths: string, onProgress: ProgressCallback | null, onComplete: CompleteCallbackWithData<T> | null): void;
public load<T extends Asset> (paths: string[], onProgress: ProgressCallback | null, onComplete: CompleteCallbackWithData<T[]> | null): void;
public load<T extends Asset> (paths: string, onComplete?: CompleteCallbackWithData<T> | null): void;
public load<T extends Asset> (paths: string[], onComplete?: CompleteCallbackWithData<T[]> | null): void;
public load<T extends Asset> (paths: string, type: AssetType<T> | null, onComplete?: CompleteCallbackWithData<T> | null): void;
public load<T extends Asset> (paths: string[], type: AssetType<T> | null, onComplete?: CompleteCallbackWithData<T[]> | null): void;
paths: string[], type: Constructor<T> | null,
onProgress: ((finished: number, total: number, item: RequestItem) => void) | null,
onComplete: ((err: Error | null, data: T[]) => void) | null): void;
public load<T extends Asset> (paths: string, onProgress: ((finished: number, total: number, item: RequestItem) => void) | null, onComplete: ((err: Error | null, data: T) => void) | null): void;
public load<T extends Asset> (paths: string[], onProgress: ((finished: number, total: number, item: RequestItem) => void) | null, onComplete: ((err: Error | null, data: T[]) => void) | null): void;
public load<T extends Asset> (paths: string, onComplete?: ((err: Error | null, data: T) => void) | null): void;
public load<T extends Asset> (paths: string[], onComplete?: ((err: Error | null, data: T[]) => void) | null): void;
public load<T extends Asset> (paths: string, type: Constructor<T> | null, onComplete?: ((err: Error | null, data: T) => void) | null): void;
public load<T extends Asset> (paths: string[], type: Constructor<T> | null, onComplete?: ((err: Error | null, data: T[]) => void) | null): void;
public load<T extends Asset> (
paths: string|string[],
type?: AssetType<T> | ProgressCallback | CompleteCallbackWithData<T|T[]> | null,
onProgress?: ProgressCallback | CompleteCallbackWithData<T|T[]> | null,
onComplete?: CompleteCallbackWithData<T|T[]> | null,
type?: Constructor<T> | ((finished: number, total: number, item: RequestItem) => void) | ((err: Error | null, data: T|T[]) => void) | null,
onProgress?: ((finished: number, total: number, item: RequestItem) => void) | ((err: Error | null, data: T|T[]) => void) | null,
onComplete?: ((err: Error | null, data: T|T[]) => void) | null,
) {
const { type: _type, onProgress: onProg, onComplete: onComp } = parseLoadResArgs(type, onProgress, onComplete);
const options = { __requestType__: RequestType.PATH, type: _type, bundle: this.name, __outputAsArray__: Array.isArray(paths) };
@@ -237,24 +249,34 @@ export default class Bundle {
/**
* @en
* Preload the asset within this bundle by the path which is relative to bundle's path.
* After calling this method, you still need to finish loading by calling `Bundle.load`.
* It will be totally fine to call `Bundle.load` at any time even if the preloading is not
* yet finished
* Preloads the asset within this bundle by the path which is relative to bundle's path.
* After calling this method, you still need to finish loading by calling [[Bundle.load]].
* It will be totally fine to call [[Bundle.load]] at any time even if the preloading is not
* yet finished.
*
* @zh
* 通过相对路径预加载分包中的资源。路径是相对分包文件夹路径的相对路径。调用完后,你仍然需要通过 `Bundle.load` 来完成加载。
* 就算预加载还没完成,你也可以直接调用 `Bundle.load`。
* 通过相对路径预加载分包中的资源。路径是相对分包文件夹路径的相对路径。调用完后,你仍然需要通过 [[Bundle.load]] 来完成加载。
* 就算预加载还没完成,你也可以直接调用 [[Bundle.load]]。
*
* @param paths - Paths of the target asset.The path is relative to bundle folder, extensions must be omitted.
* @param type - Only asset of type will be loaded if this argument is supplied.
* @param onProgress - Callback invoked when progression change.
* @param onProgress.finish - The number of the items that are already completed.
* @param onProgress.total - The total number of the items.
* @param onProgress.item - The finished request item.
* @param onComplete - Callback invoked when the resource loaded.
* @param onComplete.error - The error info or null if loaded successfully.
* @param onComplete.items - The preloaded items.
* @param paths
* @en Paths of the target assets.These paths are relative to the bundle's folder, extension name must be omitted.
* @zh 需要加载的资源的路径。此路径为工程中相对于 bundle 文件夹的相对路径,路径中请不要带扩展名。
* @param type
* @en Asset type, if this parameter is passed, the asset of the corresponding type will be found in the assets of the corresponding path to finish preloading.
* @zh 资源类型,如果传入此参数,则会在对应路径的资源中找到对应类型的资源完成预加载。
* @param onProgress
* @en Callback invoked when the preloading progress change.
* @zh 预加载进度发生变化时执行的回调。
* @param onProgress.finish
* @en The number of request items that have been preloaded.
* @zh 已经完成预加载的资源数量。
* @param onProgress.total
* @en The number of all request items to be preloaded.
* @zh 所有待预加载的资源数量。
* @param onProgress.item @en The finished request item. @zh 当前完成的预加载项。
* @param onComplete @en Callback invoked when all assets preloaded. @zh 所有资源预加载完成后的回调。
* @param onComplete.error @en Error message during preloading, or null if preloaded successfully. @zh 预加载过程中的错误信息,如果预加载成功则为 null。
* @param onComplete.items @en The preloaded items. @zh 预加载项。
*
* @example
* // preload the texture (${project}/assets/resources/textures/background.jpg) from resources
@@ -274,15 +296,15 @@ export default class Bundle {
* bundle2.load('imgs/cocos', SpriteFrame, (err, spriteFrame) => {});
*
*/
public preload (paths: string|string[], type: AssetType|null, onProgress: ProgressCallback|null, onComplete: CompleteCallbackWithData<RequestItem[]>|null): void;
public preload (paths: string|string[], onProgress: ProgressCallback | null, onComplete: CompleteCallbackWithData<RequestItem[]> | null): void;
public preload (paths: string|string[], onComplete?: CompleteCallbackWithData<RequestItem[]> | null): void;
public preload (paths: string|string[], type: AssetType | null, onComplete?: CompleteCallbackWithData<RequestItem[]> | null): void;
public preload (paths: string|string[], type: Constructor<Asset>|null, onProgress: ((finished: number, total: number, item: RequestItem) => void)|null, onComplete: ((err: Error | null, data: RequestItem[]) => void)|null): void;
public preload (paths: string|string[], onProgress: ((finished: number, total: number, item: RequestItem) => void) | null, onComplete: ((err: Error | null, data: RequestItem[]) => void) | null): void;
public preload (paths: string|string[], onComplete?: ((err: Error | null, data: RequestItem[]) => void) | null): void;
public preload (paths: string|string[], type: Constructor<Asset> | null, onComplete?: ((err: Error | null, data: RequestItem[]) => void) | null): void;
public preload (
paths: string|string[],
type?: AssetType | ProgressCallback | CompleteCallbackWithData<RequestItem[]> | null,
onProgress?: ProgressCallback | CompleteCallbackWithData<RequestItem[]> | null,
onComplete?: CompleteCallbackWithData<RequestItem[]> | null,
type?: Constructor<Asset> | ((finished: number, total: number, item: RequestItem) => void) | ((err: Error | null, data: RequestItem[]) => void) | null,
onProgress?: ((finished: number, total: number, item: RequestItem) => void) | ((err: Error | null, data: RequestItem[]) => void) | null,
onComplete?: ((err: Error | null, data: RequestItem[]) => void) | null,
) {
const { type: _type, onProgress: onProg, onComplete: onComp } = parseLoadResArgs(type, onProgress, onComplete);
cclegacy.assetManager.preloadAny(paths, { __requestType__: RequestType.PATH, type: _type, bundle: this.name }, onProg, onComp);
@@ -290,23 +312,28 @@ export default class Bundle {
/**
* @en
* Load all assets under a folder inside the bundle folder.<br>
* Loads all assets under a folder inside the bundle folder.<br>
* <br>
* Note: All asset paths in Creator use forward slashes, paths using backslashes will not work.
*
* @zh
* 加载目标文件夹中的所有资源, 注意:路径中只能使用斜杠,反斜杠将停止工作
* 加载目标文件夹中的所有资源, 注意:路径中只能使用斜杠,反斜杠将停止工作。
*
* @param dir - path of the target folder.The path is relative to the bundle folder, extensions must be omitted.
* @param type - Only asset of type will be loaded if this argument is supplied.
* @param onProgress - Callback invoked when progression change.
* @param onProgress.finish - The number of the items that are already completed.
* @param onProgress.total - The total number of the items.
* @param onProgress.item - The latest request item
* @param onComplete - A callback which is called when all assets have been loaded, or an error occurs.
* @param onComplete.error - If one of the asset failed, the complete callback is immediately called with the error.
* If all assets are loaded successfully, error will be null.
* @param onComplete.assets - An array of all loaded assets.
* @param dir @en The path of the target folder. The path is relative to the bundle folder. @zh 目标文件夹路径,此路径为相对于 bundle 文件夹的路径。
* @param type @en The asset type. Only specify type asset will be loaded if this argument is supplied. @zh 资源类型,如果指定了此参数,则只会加载目标文件夹下此类型的资源。
* @param onProgress
* @en Callback invoked when the loading progress change.
* @zh 加载进度发生变化时执行的回调。
* @param onProgress.finish
* @en The number of request items that have been loaded.
* @zh 已经完成加载的资源数量。
* @param onProgress.total
* @en The number of all request items to be loaded.
* @zh 所有待加载的资源数量。
* @param onProgress.item @en The finished request item. @zh 当前完成的加载项。
* @param onComplete @en Callback invoked when all assets loaded. @zh 所有资源加载完成后的回调。
* @param onComplete.error @en Error message during loading, or null if loaded successfully. @zh 加载过程中的错误信息,如果加载成功则为 null。
* @param onComplete.assets @en An array of all loaded assets. @zh 完成加载的资源数组。
*
* @example
* // load all audios (resources/audios/)
@@ -325,15 +352,15 @@ export default class Bundle {
* bundle2.loadDir('skills', SpriteFrame, null, (err, spriteFrames) => console.log(err));
*
*/
public loadDir<T extends Asset> (dir: string, type: AssetType<T> | null, onProgress: ProgressCallback | null, onComplete: CompleteCallbackWithData<T[]> | null): void;
public loadDir<T extends Asset> (dir: string, onProgress: ProgressCallback | null, onComplete: CompleteCallbackWithData<T[]> | null): void;
public loadDir<T extends Asset> (dir: string, onComplete?: CompleteCallbackWithData<T[]> | null): void;
public loadDir<T extends Asset> (dir: string, type: AssetType<T> | null, onComplete?: CompleteCallbackWithData<T[]> | null): void;
public loadDir<T extends Asset> (dir: string, type: Constructor<T> | null, onProgress: ((finished: number, total: number, item: RequestItem) => void) | null, onComplete: ((err: Error | null, data: T[]) => void) | null): void;
public loadDir<T extends Asset> (dir: string, onProgress: ((finished: number, total: number, item: RequestItem) => void) | null, onComplete: ((err: Error | null, data: T[]) => void) | null): void;
public loadDir<T extends Asset> (dir: string, onComplete?: ((err: Error | null, data: T[]) => void) | null): void;
public loadDir<T extends Asset> (dir: string, type: Constructor<T> | null, onComplete?: ((err: Error | null, data: T[]) => void) | null): void;
public loadDir<T extends Asset> (
dir: string,
type?: AssetType<T> | ProgressCallback | CompleteCallbackWithData<T[]> | null,
onProgress?: ProgressCallback | CompleteCallbackWithData<T[]> | null,
onComplete?: CompleteCallbackWithData<T[]> | null,
type?: Constructor<T> | ((finished: number, total: number, item: RequestItem) => void) | ((err: Error | null, data: T[]) => void) | null,
onProgress?: ((finished: number, total: number, item: RequestItem) => void) | ((err: Error | null, data: T[]) => void) | null,
onComplete?: ((err: Error | null, data: T[]) => void) | null,
) {
const { type: _type, onProgress: onProg, onComplete: onComp } = parseLoadResArgs(type, onProgress, onComplete);
cclegacy.assetManager.loadAny(dir, { __requestType__: RequestType.DIR, type: _type, bundle: this.name, __outputAsArray__: true }, onProg, onComp);
@@ -341,24 +368,29 @@ export default class Bundle {
/**
* @en
* Preload all assets under a folder inside the bundle folder.<br> After calling this method, you still need to
* finish loading by calling `Bundle.loadDir`.
* It will be totally fine to call `Bundle.loadDir` at any time even if the preloading is not yet finished
* Preloads all assets under a folder inside the bundle folder.<br> After calling this method, you still need to
* finish loading by calling [[Bundle.loadDir]].
* It will be totally fine to call [[Bundle.loadDir]] at any time even if the preloading is not yet finished.
*
* @zh
* 预加载目标文件夹中的所有资源。调用完后,你仍然需要通过 `Bundle.loadDir` 来完成加载。
* 就算预加载还没完成,你也可以直接调用 `Bundle.loadDir`。
* 预加载目标文件夹中的所有资源。调用完后,你仍然需要通过 [[Bundle.loadDir]] 来完成加载。
* 就算预加载还没完成,你也可以直接调用 [[Bundle.loadDir]]。
*
* @param dir - path of the target folder.The path is relative to the bundle folder, extensions must be omitted.
* @param type - Only asset of type will be preloaded if this argument is supplied.
* @param onProgress - Callback invoked when progression change.
* @param onProgress.finish - The number of the items that are already completed.
* @param onProgress.total - The total number of the items.
* @param onProgress.item - The latest request item
* @param onComplete - A callback which is called when all assets have been loaded, or an error occurs.
* @param onComplete.error - If one of the asset failed, the complete callback is immediately called with the error.
* If all assets are preloaded successfully, error will be null.
* @param onComplete.items - An array of all preloaded items.
* @param dir @en The path of the target folder. The path is relative to the bundle folder. @zh 目标文件夹路径,此路径为相对于 bundle 文件夹的路径。
* @param type @en The asset type. Only specify type asset will be preloaded if this argument is supplied. @zh 资源类型,如果指定了此参数,则只会预加载目标文件夹下此类型的资源。
* @param onProgress
* @en Callback invoked when the preloading progress change.
* @zh 预加载进度发生变化时执行的回调。
* @param onProgress.finish
* @en The number of request items that have been preloaded.
* @zh 已经完成预加载的资源数量。
* @param onProgress.total
* @en The number of all request items to be preloaded.
* @zh 所有待预加载的资源数量。
* @param onProgress.item @en The finished request item. @zh 当前完成的预加载项。
* @param onComplete @en Callback invoked when all assets preloaded. @zh 所有资源预加载完成后的回调。
* @param onComplete.error @en Error message during preloading, or null if preloaded successfully. @zh 预加载过程中的错误信息,如果预加载成功则为 null。
* @param onComplete.items @en The preloaded items. @zh 预加载项。
*
* @example
* // preload all audios (resources/audios/)
@@ -377,15 +409,15 @@ export default class Bundle {
* // wait for while
* bundle2.loadDir('skills', SpriteFrame, (err, spriteFrames) => {});
*/
public preloadDir (dir: string, type: AssetType | null, onProgress: ProgressCallback | null, onComplete: CompleteCallbackWithData<RequestItem[]> | null): void;
public preloadDir (dir: string, onProgress: ProgressCallback | null, onComplete: CompleteCallbackWithData<RequestItem[]> | null): void;
public preloadDir (dir: string, onComplete?: CompleteCallbackWithData<RequestItem[]> | null): void;
public preloadDir (dir: string, type: AssetType | null, onComplete?: CompleteCallbackWithData<RequestItem[]> | null): void;
public preloadDir (dir: string, type: Constructor<Asset> | null, onProgress: ((finished: number, total: number, item: RequestItem) => void) | null, onComplete: ((err: Error | null, data: RequestItem[]) => void) | null): void;
public preloadDir (dir: string, onProgress: ((finished: number, total: number, item: RequestItem) => void) | null, onComplete: ((err: Error | null, data: RequestItem[]) => void) | null): void;
public preloadDir (dir: string, onComplete?: ((err: Error | null, data: RequestItem[]) => void) | null): void;
public preloadDir (dir: string, type: Constructor<Asset> | null, onComplete?: ((err: Error | null, data: RequestItem[]) => void) | null): void;
public preloadDir (
dir: string,
type?: AssetType | ProgressCallback | CompleteCallbackWithData<RequestItem[]>| null,
onProgress?: ProgressCallback | CompleteCallbackWithData<RequestItem[]>| null,
onComplete?: CompleteCallbackWithData<RequestItem[]>| null,
type?: Constructor<Asset> | ((finished: number, total: number, item: RequestItem) => void) | ((err: Error | null, data: RequestItem[]) => void)| null,
onProgress?: ((finished: number, total: number, item: RequestItem) => void) | ((err: Error | null, data: RequestItem[]) => void)| null,
onComplete?: ((err: Error | null, data: RequestItem[]) => void)| null,
) {
const { type: _type, onProgress: onProg, onComplete: onComp } = parseLoadResArgs(type, onProgress, onComplete);
cclegacy.assetManager.preloadAny(dir, { __requestType__: RequestType.DIR, type: _type, bundle: this.name }, onProg, onComp);
@@ -398,31 +430,37 @@ export default class Bundle {
* @zh
* 通过场景名称加载分包中的场景资源。
*
* @param sceneName - The name of the scene to load.
* @param options - Some optional parameters
* @param onProgress - Callback invoked when progression change.
* @param onProgress.finish - The number of the items that are already completed.
* @param onProgress.total - The total number of the items.
* @param onProgress.item - The latest request item
* @param onComplete - callback, will be called after scene launched.
* @param onComplete.err - The occurred error, null indicetes success
* @param onComplete.sceneAsset - The scene asset
* @param sceneName @en The name of the scene to be loaded. @zh 待加载的场景名称。
* @param options @en Some optional parameters. @zh 可选参数。
* @param onProgress
* @en Callback invoked when the loading progress change.
* @zh 加载进度发生变化时执行的回调。
* @param onProgress.finish
* @en The number of request items that have been loaded.
* @zh 已经完成加载的资源数量。
* @param onProgress.total
* @en The number of all request items to be loaded.
* @zh 所有待加载的资源数量。
* @param onProgress.item @en The finished request item. @zh 当前完成的加载项。
* @param onComplete @en Callback invoked when the scene loaded. @zh 场景加载完成后的回调。
* @param onComplete.error @en Error message during loading, or null if loaded successfully. @zh 加载过程中的错误信息,如果加载成功则为 null。
* @param onComplete.sceneAsset @en The scene asset. @zh 加载完成的场景资源。
*
* @example
* bundle1.loadScene('first', (err, sceneAsset) => director.runScene(sceneAsset));
*
*/
public loadScene (sceneName: string, options: IAssetOptions | null, onProgress: ProgressCallback | null, onComplete: CompleteCallbackWithData<SceneAsset> | null): void;
public loadScene (sceneName: string, onProgress: ProgressCallback | null, onComplete: CompleteCallbackWithData<SceneAsset> | null): void;
public loadScene (sceneName: string, options: IAssetOptions | null, onComplete?: CompleteCallbackWithData<SceneAsset> | null): void;
public loadScene (sceneName: string, onComplete?: CompleteCallbackWithData<SceneAsset> | null): void;
public loadScene (sceneName: string, options: { [key: string]: any, preset?: 'string' } | null, onProgress: ((finished: number, total: number, item: RequestItem) => void) | null, onComplete: ((err: Error | null, data: SceneAsset) => void) | null): void;
public loadScene (sceneName: string, onProgress: ((finished: number, total: number, item: RequestItem) => void) | null, onComplete: ((err: Error | null, data: SceneAsset) => void) | null): void;
public loadScene (sceneName: string, options: { [key: string]: any, preset?: 'string' } | null, onComplete?: ((err: Error | null, data: SceneAsset) => void) | null): void;
public loadScene (sceneName: string, onComplete?: ((err: Error | null, data: SceneAsset) => void) | null): void;
public loadScene (
sceneName: string,
options?: IAssetOptions | ProgressCallback | CompleteCallbackWithData<SceneAsset> | null,
onProgress?: ProgressCallback | CompleteCallbackWithData<SceneAsset> | null,
onComplete?: CompleteCallbackWithData<SceneAsset> | null,
options?: { [key: string]: any, preset?: 'string' } | ((finished: number, total: number, item: RequestItem) => void) | ((err: Error | null, data: SceneAsset) => void) | null,
onProgress?: ((finished: number, total: number, item: RequestItem) => void) | ((err: Error | null, data: SceneAsset) => void) | null,
onComplete?: ((err: Error | null, data: SceneAsset) => void) | null,
) {
const { options: opts, onProgress: onProg, onComplete: onComp } = parseParameters<CompleteCallbackWithData<SceneAsset>>(options, onProgress, onComplete);
const { options: opts, onProgress: onProg, onComplete: onComp } = parseParameters<((err: Error | null, data: SceneAsset) => void)>(options, onProgress, onComplete);
opts.preset = opts.preset || 'scene';
opts.bundle = this.name;
@@ -443,21 +481,27 @@ export default class Bundle {
/**
* @en
* Preload the scene asset within this bundle by its name. After calling this method, you still need to finish loading
* by calling `Bundle.loadScene` or `director.loadScene`.It will be totally fine to call `Bundle.loadDir` at any
* time even if the preloading is not yet finished
* by calling [[Bundle.loadScene]] or [[Director.loadScene]].It will be totally fine to call [[Bundle.loadScene]] at any
* time even if the preloading is not yet finished.
*
* @zh
* 通过场景名称预加载分包中的场景资源.调用完后,你仍然需要通过 `Bundle.loadScene` 或 `director.loadScene` 来完成加载。
* 就算预加载还没完成,你也可以直接调用 `Bundle.loadScene` 或 `director.loadScene`。
* 通过场景名称预加载分包中的场景资源.调用完后,你仍然需要通过 [[Bundle.loadScene]] 或 [[Director.loadScene]] 来完成加载。
* 就算预加载还没完成,你也可以直接调用 [[Bundle.loadScene]] 或 [[Director.loadScene]]。
*
* @param sceneName - The name of the scene to preload.
* @param options - Some optional parameters
* @param onProgress - callback, will be called when the load progression change.
* @param onProgress.finish - The number of the items that are already completed
* @param onProgress.total - The total number of the items
* @param onProgress.item The latest request item
* @param onComplete - callback, will be called after scene loaded.
* @param onComplete.error - null or the error object.
* @param sceneName @en The name of the scene to be preloaded. @zh 待预加载的场景名称。
* @param options @en Some optional parameters. @zh 可选参数。
* @param onProgress
* @en Callback invoked when the preloading progress change.
* @zh 预加载进度发生变化时执行的回调。
* @param onProgress.finish
* @en The number of request items that have been preloaded.
* @zh 已经完成预加载的资源数量。
* @param onProgress.total
* @en The number of all request items to be preloaded.
* @zh 所有待预加载的资源数量。
* @param onProgress.item @en The finished request item. @zh 当前完成的预加载项。
* @param onComplete @en Callback invoked when the scene preloaded. @zh 场景预加载完成后的回调。
* @param onComplete.error @en Error message during preloading, or null if preloaded successfully. @zh 预加载过程中的错误信息,如果预加载成功则为 null。
*
* @example
* bundle1.preloadScene('first');
@@ -465,17 +509,17 @@ export default class Bundle {
* bundle1.loadScene('first', (err, scene) => director.runScene(scene));
*
*/
public preloadScene (sceneName: string, options: IAssetOptions | null, onProgress: ProgressCallback, onComplete: CompleteCallbackNoData | null): void;
public preloadScene (sceneName: string, onProgress: ProgressCallback | null, onComplete: CompleteCallbackNoData | null): void;
public preloadScene (sceneName: string, options: IAssetOptions | null, onComplete?: CompleteCallbackNoData | null): void;
public preloadScene (sceneName: string, onComplete?: CompleteCallbackNoData | null): void;
public preloadScene (sceneName: string, options: { [key: string]: any, preset?: 'string' } | null, onProgress: ((finished: number, total: number, item: RequestItem) => void), onComplete: ((err?: Error | null) => void) | null): void;
public preloadScene (sceneName: string, onProgress: ((finished: number, total: number, item: RequestItem) => void) | null, onComplete: ((err?: Error | null) => void) | null): void;
public preloadScene (sceneName: string, options: { [key: string]: any, preset?: 'string' } | null, onComplete?: ((err?: Error | null) => void) | null): void;
public preloadScene (sceneName: string, onComplete?: ((err?: Error | null) => void) | null): void;
public preloadScene (
sceneName: string,
options?: IAssetOptions | ProgressCallback | CompleteCallbackNoData | null,
onProgress?: ProgressCallback | CompleteCallbackNoData | null,
onComplete?: CompleteCallbackNoData | null,
options?: { [key: string]: any, preset?: 'string' } | ((finished: number, total: number, item: RequestItem) => void) | ((err?: Error | null) => void) | null,
onProgress?: ((finished: number, total: number, item: RequestItem) => void) | ((err?: Error | null) => void) | null,
onComplete?: ((err?: Error | null) => void) | null,
) {
const { options: opts, onProgress: onProg, onComplete: onComp } = parseParameters<CompleteCallbackNoData>(options, onProgress, onComplete);
const { options: opts, onProgress: onProg, onComplete: onComp } = parseParameters<((err?: Error | null) => void)>(options, onProgress, onComplete);
opts.bundle = this.name;
cclegacy.assetManager.preloadAny({ scene: sceneName }, opts, onProg, (err) => {
@@ -488,27 +532,28 @@ export default class Bundle {
/**
* @en
* Get cached asset within this bundle by path and type. <br>
* Gets cached asset within this bundle by path and type. <br>
* After you load asset with [[load]] or [[loadDir]],
* you can acquire them by passing the path to this API.
*
* NOTE:The `path` and `type` parameters passed need to be the same as those passed to `Bundle.load`,
* otherwise it may return some other resources with the same name!
* NOTE:When there are multiple asset with the same name, you can get the specific asset by specifying the type.
* Otherwise the first asset matching that name will be returned.
*
* @zh
* 通过路径与类型获取已缓存资源。在你使用 [[load]] 或者 [[loadDir]] 之后,
* 你能通过传路径通过这个 API 获取到这些资源。
*
* 注意:传入的 path 与 type 参数需要与 `Bundle.load` 加载资源时传入的参数一致,否则可能会获取到其他同名资源
* 注意:当有多个同名的资产时,你可以通过指定类型来获得具体的资产。
* 否则将返回与该名称相匹配的第一个资产。
*
* @param path - The path of asset
* @param type - Only asset of type will be returned if this argument is supplied.
* @returns - the asset has been cached
* @param path @en The path of asset. @zh 资源的路径。
* @param type @en The asset type. Only specify type asset will be returned if this argument is supplied. @zh 资源类型,指定后只会返回该类型的资源。
* @returns @en The asset has been cached. @zh 已缓存的资源。
*
* @example
* bundle1.get('music/hit', AudioClip);
*/
public get<T extends Asset> (path: string, type?: AssetType<T> | null): T | null {
public get<T extends Asset> (path: string, type?: Constructor<T> | null): T | null {
const info = this.getInfoWithPath(path, type);
if (info) {
return assets.get(info.uuid) as T || null;
@@ -519,27 +564,28 @@ export default class Bundle {
/**
* @en
* Release the asset loaded by [[load]] or [[loadDir]]
* and it's dependencies. Refer to [[AssetManager.releaseAsset]] for detailed informations.
* Releases the asset loaded by [[load]] or [[loadDir]].
* and it's dependencies. Refer to [[AssetManager.releaseAsset]] for detailed information.
*
* NOTE:The `path` and `type` parameters passed need to be the same as those passed to `Bundle.load`,
* otherwise it may release some other resources with the same name!
* NOTE:When there are multiple asset with the same name, you can specify the asset to be released by specifying the type.
* Otherwise the first resource matching that name will be released.
*
* @zh
* 释放通过 [[load]] 或者 [[loadDir]] 加载的资源。
* 详细信息请参考 [[AssetManager.releaseAsset]]
* 详细信息请参考 [[AssetManager.releaseAsset]]。
*
* 注意:传入的 path 与 type 参数需要与 `Bundle.load` 加载资源时传入的参数一致,否则可能会释放到其他同名资源
* 注意:当存在多个资源同名时,可以通过指定类型来指定要释放的资源,否则将释放第一个匹配该名称的资源。
*
* @param path - The path of asset
* @param type - Only asset of type will be released if this argument is supplied.
* @param path @en The path of asset. @zh 资源的路径。
* @param type @en The type of asset. @zh 资源的类型。
*
* @example
* // release a texture which is no longer need
* bundle1.release('misc/character/cocos');
*
*/
public release (path: string, type?: AssetType | null) {
public release (path: string, type?: Constructor<Asset> | null) {
const asset = this.get(path, type);
if (asset) {
releaseManager.tryRelease(asset, true);
@@ -548,17 +594,16 @@ export default class Bundle {
/**
* @en
* Release all unused assets within this bundle. Refer to [[AssetManager.releaseAll]] for detailed informations.
* Release all unused assets within this bundle. Refer to [[AssetManager.releaseAll]] for detailed information.
*
* @zh
* 释放此包中的所有没有用到的资源。详细信息请参考 [[AssetManager.releaseAll]]
*
* @private
* 释放此包中的所有没有用到的资源。详细信息请参考 [[AssetManager.releaseAll]]。
*
* @example
* // release all unused asset within bundle1
* bundle1.releaseUnusedAssets();
*
* @engineInternal
*/
public releaseUnusedAssets () {
assets.forEach((asset) => {
@@ -574,7 +619,7 @@ export default class Bundle {
* Release all assets within this bundle. Refer to [[AssetManager.releaseAll]] for detailed information.
*
* @zh
* 释放此包中的所有资源。详细信息请参考 [[AssetManager.releaseAll]]
* 释放此包中的所有资源。详细信息请参考 [[AssetManager.releaseAll]]。
*
* @example
* // release all asset within bundle1
@@ -599,10 +644,10 @@ export default class Bundle {
/**
* @en
* resources is a bundle and controls all asset under assets/resources
* A [[Bundle]] instance to manage all assets in assets/resources.
*
* @zh
* resources 是一个 bundle,用于管理所有在 assets/resources 下的资源
* 一个 [[Bundle]] 实例,用于管理所有在 assets/resources 下的资源。
*/
export const resources: Bundle = new Bundle();
cclegacy.resources = resources;
+29 -28
View File
@@ -27,123 +27,124 @@ import Cache from './cache';
/**
* @en
* Cache manager is a module which controls all caches downloaded from server in non-web platform, it is a singleton
* All member can be accessed with `assetManager.cacheManager`.
* You can access it via [[AssetManager.cacheManager]].
*
* @zh
* 缓存管理器是一个模块,在非 WEB 平台上,用于管理所有从服务器上下载下来的缓存,这是一个单例,所有成员能通过 `assetManager.cacheManager` 访问。
* 缓存管理器是一个模块,在非 WEB 平台上,用于管理所有从服务器上下载下来的缓存,这是一个单例,你能通过 [[AssetManager.cacheManager]] 访问它。
*
*/
export default abstract class CacheManager {
/**
* @en
* The name of cacheDir
* The name of cache directory.
*
* @zh
* 缓存目录的名称
* 缓存目录的名称。
*/
public abstract cacheDir: string;
/**
* @en
* Whether or not cache asset into user's storage space, this property only works on mini-game platforms
* Whether to cache file into user's storage space, this property only works on mini-game platforms.
*
* @zh
* 是否缓存资源到用户存储空间,此属性只在小游戏平台有效
* 是否缓存文件到用户存储空间,此属性只在小游戏平台有效。
*
*/
public abstract cacheEnabled: boolean;
/**
* @en
* Whether or not auto clear cache when storage ran out, this property only works on mini-game platforms
* Whether to clear cache automatically when storage ran out, this property only works on mini-game platforms.
*
* @zh
* 是否在存储空间满了后自动清理缓存,此属性只在小游戏平台有效
* 是否在存储空间满了后自动清理缓存,此属性只在小游戏平台有效。
*
*/
public abstract autoClear: boolean;
/**
* @en
* The interval between caching resources, this property only works on mini-game platforms, unit: ms
* The interval between caching file, this property only works on mini-game platforms, unit: ms.
*
* @zh
* 缓存资源的间隔时间,此属性只在小游戏平台有效,单位:毫秒
* 缓存文件的间隔时间,此属性只在小游戏平台有效,单位:毫秒。
*
*/
public abstract cacheInterval: number;
/**
* @en
* The interval between deleting resources, when you use `cleanLRU`, the resources will be deleted as this interval, unit: ms
* The interval between deleting file, when you use `cleanLRU`, the file will be deleted as this interval, unit: ms.
*
* @zh
* 清理资源的间隔时间,当你使用 `cleanLRU` 时,资源将以此间隔被删除,单位:毫秒
* 清理资源的间隔时间,当你使用 `cleanLRU` 时,资源将以此间隔被删除,单位:毫秒。
*
*/
public abstract deleteInterval: number;
/**
* @en
* List of all cached files
* List of all cached files.
*
* @zh
* 所有缓存文件列表
* 所有缓存文件列表。
*
*/
public abstract cachedFiles: Cache<{ bundle: string, url: string, lastTime: number }>;
/**
* @en
* Get cached path with origin url
* Gets cached path with origin url.
*
* @zh
* 通过原始 url 获取缓存后的路径
* 通过原始 url 获取缓存后的路径。
*
* @param originUrl
* @returns The cached path
* @param originUrl @en The origin url of file. @zh 文件的原始 url。
* @returns @en The path where the file is cached. @zh 该文件所缓存的路径。
*/
public abstract getCache (originUrl: string): string;
/**
* @en
* Get temporary path with origin url, this method only works on mini-game platforms
* Gets temporary path with origin url, this method only works on mini-game platforms.
*
* @zh
* 通过原始 url 获取临时文件的路径,此方法只在小游戏平台有效
* 通过原始 url 获取临时文件的路径,此方法只在小游戏平台有效。
*
* @param originUrl
* @returns The temp path
* @param originUrl @en The origin url of file. @zh 文件的原始 url。
* @returns @en The temporary path where the file is stored. @zh 该文件所存储的临时路径。
*/
public abstract getTemp (originUrl: string): string;
/**
* @en
* Clear all caches, please use with caution, If necessary, we recommend using it before the game is launched
* Clear all caches, please use with caution, If necessary, we recommend using it before the game is launched.
*
* @zh
* 清空所有缓存,请谨慎使用,如果必要的话,我们建议在游戏启动之前使用
* 清空所有缓存,请谨慎使用,如果必要的话,我们建议在游戏启动之前使用。
*
*/
public abstract clearCache (): void;
/**
* @en
* Clear part of caches with LRU strategy
* Clear part of caches with LRU strategy.
*
* @zh
* 使用 LRU 策略清空部分缓存
* 使用 LRU 策略清空部分缓存。
*
*/
public abstract clearLRU (): void;
/**
* @en
* Remove cache with origin url
* Removes cache with origin url.
*
* @zh
* 通过原始 url 移除缓存
* 通过原始 url 移除缓存。
*
* @param originUrl @en The origin url to remove from cache. @zh 要从缓存中移除的原始 url。
*/
public abstract removeCache (originUrl: string): void;
}
+128 -37
View File
@@ -24,24 +24,115 @@
import { js } from '../../core';
/**
* @zh 缓存结构的接口定义,可以用于保存数据。
* @en Interface definition of a cache structure that can be used to save data.
*/
export interface ICache<T> {
/**
* @en
* Adds a Key-Value pair to cache.
*
* @zh
* 增加键值对到缓存中。
*
* @param key @en The key. @zh 要增加的键值对中的键。
* @param val @en The value. @zh 要增加的键值对中的值。
* @returns @en The value. @zh 新增的键值对中的值。
*/
add (key: string, val: T): T;
/**
* @en
* Gets the cached content by key.
*
* @zh
* 通过 key 获取对应的 value。
*
* @param key @en The key. @zh 要查询的键。
* @returns @en The corresponding content. @zh 对应键值对中的值。
*/
get (key: string): T | undefined | null;
/**
* @en
* Checks whether or not content exists by key.
*
* @zh
* 通过 Key 判断是否存在对应的内容。
*
* @param key @en The key. @zh 要查询的键。
* @returns @en True indicates that content of the key exists. @zh 返回 True 则表明该值存在。
*/
has (key: string): boolean;
/**
* @en
* Removes the cached content by key.
*
* @zh
* 通过 Key 移除对应的内容。
*
* @param key @en The key. @zh 要移除的键值对中的键。
* @returns @en The removed content. @zh 移出的键值对中的值。
*/
remove (key: string): T | undefined | null;
/**
* @en
* Clear all contents.
*
* @zh
* 清除所有内容。
*/
clear (): void;
/**
*
* @en
* Enumerates all contents and invokes function.
*
* @zh
* 枚举所有内容并执行方法。
*
* @param func @en Function to be invoked. @zh 待执行的方法。
* @param func.val @en The value. @zh 传入的键值对中的值。
* @param func.key @en The corresponding key. @zh 传入的键值对中的键。
*/
forEach (func: (val: T, key: string) => void): void;
/**
* @en
* Enumerates all content to find one element which can fulfill condition.
*
* @zh
* 枚举所有内容,找到一个可以满足条件的元素。
*
* @param predicate @en The condition function. @zh 条件方法。
* @returns @en The first content that meets this condition. @zh 第一个符合该条件的内容。
*/
find (predicate: (val: T, key: string) => boolean): T | null;
/**
* @en
* The count of cached content.
*
* @zh
* 缓存数量。
*/
readonly count: number;
/**
* @en
* Destroy this cache。
*
* @zh
* 销毁这个 cache.
*/
destroy (): void;
}
/**
* @en
* use to cache something
* A data structure used to cache certain content.
*
* @zh
* 用于缓存某些内容
* 用于缓存某些内容的数据结构。
*
*/
export default class Cache<T = any> implements ICache<T> {
@@ -50,12 +141,12 @@ export default class Cache<T = any> implements ICache<T> {
/**
* @en
* Create a cache
* Creates a Cache.
*
* @zh
* 创建一个 cache
* 创建一个 Cache。
*
* @param map - An object used to initialize
* @param map @en An object used to initialize. @zh 用于初始化此缓存的对象。
*
*/
constructor (map?: Record<string, T>) {
@@ -70,14 +161,14 @@ export default class Cache<T = any> implements ICache<T> {
/**
* @en
* Add Key-Value to cache
* Adds a Key-Value pair to cache.
*
* @zh
* 增加键值对到缓存中
* 增加键值对到缓存中。
*
* @param key - The key
* @param val - The value
* @returns The value
* @param key @en The key. @zh 要增加的键值对中的键。
* @param val @en The value. @zh 要增加的键值对中的值。
* @returns @en The value. @zh 新增的键值对中的值。
*
* @example
* var cache = new Cache();
@@ -93,13 +184,13 @@ export default class Cache<T = any> implements ICache<T> {
/**
* @en
* Get the cached content by key
* Gets the cached content by key.
*
* @zh
* 通过 key 获取对应的 value
* 通过 key 获取对应的 value。
*
* @param key - The key
* @returns The corresponding content
* @param key @en The key. @zh 要查询的键。
* @returns @en The corresponding content. @zh 对应键值对中的值。
*
* @example
* let cache = new Cache();
@@ -112,13 +203,13 @@ export default class Cache<T = any> implements ICache<T> {
/**
* @en
* Check whether or not content exists by key
* Checks whether or not content exists by key.
*
* @zh
* 通过 Key 判断是否存在对应的内容
* 通过 Key 判断是否存在对应的内容。
*
* @param key - The key
* @returns True indicates that content of the key exists
* @param key @en The key. @zh 要查询的键。
* @returns @en True indicates that content of the key exists. @zh 返回 True 则表明该值存在。
*
* @example
* var cache = new Cache();
@@ -131,13 +222,13 @@ export default class Cache<T = any> implements ICache<T> {
/**
* @en
* Remove the cached content by key
* Removes the cached content by key.
*
* @zh
* 通过 Key 移除对应的内容
* 通过 Key 移除对应的内容。
*
* @param key - The key
* @returns The removed content
* @param key @en The key. @zh 要移除的键值对中的键。
* @returns @en The removed content. @zh 移出的键值对中的值。
*
* @example
* var cache = new Cache();
@@ -155,10 +246,10 @@ export default class Cache<T = any> implements ICache<T> {
/**
* @en
* Clear all content
* Clear all content.
*
* @zh
* 清除所有内容
* 清除所有内容。
*
* @example
* var cache = new Cache();
@@ -174,14 +265,14 @@ export default class Cache<T = any> implements ICache<T> {
/**
* @en
* Enumerate all content and invoke function
* Enumerates all content and invokes function.
*
* @zh
* 枚举所有内容并执行方法
* 枚举所有内容并执行方法。
*
* @param func - Function to be invoked
* @param func.val - The value
* @param func.key - The corresponding key
* @param func @en Function to be invoked. @zh 待执行的方法。
* @param func.val @en The value. @zh 传入的键值对中的值。
* @param func.key @en The corresponding key. @zh 传入的键值对中的键。
*
* @example
* var cache = new Cache();
@@ -196,13 +287,13 @@ export default class Cache<T = any> implements ICache<T> {
/**
* @en
* Enumerate all content to find one element which can fulfill condition
* Enumerate all content to find one element which can fulfill condition.
*
* @zh
* 枚举所有内容,找到一个可以满足条件的元素
* 枚举所有内容,找到一个可以满足条件的元素。
*
* @param predicate - The condition
* @returns content
* @param predicate @en The condition function. @zh 条件方法。
* @returns @en The first content that meets this condition. @zh 第一个符合该条件的内容。
*
* @example
* var cache = new Cache();
@@ -220,10 +311,10 @@ export default class Cache<T = any> implements ICache<T> {
/**
* @en
* The count of cached content
* The count of cached content.
*
* @zh
* 缓存数量
* 缓存数量。
*
*/
get count (): number {
@@ -232,10 +323,10 @@ export default class Cache<T = any> implements ICache<T> {
/**
* @en
* Destroy this cache
* Destroy this cache.
*
* @zh
* 销毁这个 cache
* 销毁这个 cache。
*
*/
public destroy (): void {
+75 -5
View File
@@ -26,7 +26,6 @@ import { Asset } from '../assets';
import { js, cclegacy } from '../../core';
import Cache from './cache';
import { decodeUuid, normalize } from './helper';
import { AssetType } from './shared';
export interface IConfigOption {
importBase: string;
@@ -45,26 +44,97 @@ export interface IConfigOption {
extensionMap: Record<string, string[]>;
}
/**
* @en Th asset's meta information. Used to obtain information about the asset.
* @zh 资源的元信息。用于获取资源的相关信息。
*/
export interface IAssetInfo {
/**
* @en The uuid of asset.
* @zh 资源的 uuid.
*/
uuid: string;
/**
* @en Information about the file where the asset is located. A asset can be in multiple merged files.
* @zh 资源所在文件的相关信息。一个资源可在多个合并文件中。
*/
packs?: IPackInfo[];
/**
* @en The redirect bundle of this asset. When multiple bundles with different priorities reference to the same asset,
* the asset will be stored in the bundle with the higher priority first, while the other bundles will store a record
* and the `redirect` property of that record will point to the bundle that actually stores the resource.
* @zh 资源所重定向的 bundle。当多个 bundle 引用同一份资源,且优先级不一样时,资源会优先存储在优先级高的 bundle 中,
* 其他 bundle 则会存储一条记录,并且该记录的 redirect 属性将指向真实存储此资源的 bundle。
*/
redirect?: string;
/**
* @en The version of the asset.
* @zh 资源的版本号。
*/
ver?: string;
/**
* @en The version of the native dependency of the asset.
* @zh 资源的原生依赖的版本号。
*/
nativeVer?: string;
/**
* @en The extension of the asset, or 'json' if it is null.
* This property is used to mark assets with special extensions like 'CCON'.
* @zh 资源的原生依赖的版本号。
*/
extension?: string;
}
export interface IPackInfo extends IAssetInfo {
/**
* @en Information about the merged files.
* @zh 合并文件的信息。
*/
export interface IPackInfo {
/**
* @en The unique id of this merged file.
* @zh 此合并文件的唯一 id.
*/
uuid: string;
/**
* @en The uuid of all the assets contained in this file.
* @zh 此文件中包含的所有资源的 uuid。
*/
packedUuids: string[];
/**
* @en The extension of this merged file on the file system, default is 'json'.
* @zh 此合并文件在文件系统上的扩展名,默认为 'json'.
*/
ext: string;
}
/**
* @en Addressable asset information, you can look up the path of the asset in the project and the type of the asset.
* @zh 可寻址资源的信息,你可以查询到该资源在项目中的路径与资源的类型。
*/
export interface IAddressableInfo extends IAssetInfo {
/**
* @en The relative path of this asset in the project relative to the bundle folder.
* @zh 此资源在项目中相对于 bundle 文件夹的相对路径。
*/
path: string;
ctor: AssetType;
/**
* @en The type of the asset.
* @zh 此资源的类型。
*/
ctor: Constructor<Asset>;
}
/**
* @en Information about the scene asset.
* @zh 场景资源的相关信息。
*/
export interface ISceneInfo extends IAssetInfo {
/**
* @en The path of the scene asset in the project relative to the bundle folder.
* @zh 场景资源在项目中相对 bundle 文件夹的路径。
*/
url: string;
}
@@ -199,7 +269,7 @@ export default class Config {
}
}
public getInfoWithPath (path: string, type?: AssetType | null): IAddressableInfo | null {
public getInfoWithPath (path: string, type?: Constructor<Asset> | null): IAddressableInfo | null {
if (!path) {
return null;
}
@@ -220,7 +290,7 @@ export default class Config {
return null;
}
public getDirWithPath (path: string, type?: AssetType | null, out?: IAddressableInfo[]): IAddressableInfo[] {
public getDirWithPath (path: string, type?: Constructor<Asset> | null, out?: IAddressableInfo[]): IAddressableInfo[] {
path = normalize(path);
if (path[path.length - 1] === '/') {
path = path.slice(0, -1);
+46 -18
View File
@@ -42,10 +42,10 @@ export interface IDependencies {
/**
* @en
* Control asset's dependency list, it is a singleton. All member can be accessed with `assetManager.dependUtil`
* Manages asset's dependency list, it is a singleton. You can access it via [[AssetManager.dependUtil]].
*
* @zh
* 控制资源的依赖列表,这是一个单例, 所有成员能通过 `assetManager.dependUtil` 访问
* 管理资源的依赖列表,这是一个单例, 你能通过 [[AssetManager.dependUtil]] 访问它。
*
*/
export class DependUtil {
@@ -53,23 +53,43 @@ export class DependUtil {
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
public _depends: Cache<IDependencies> = new Cache<IDependencies>();
private static _instance: DependUtil;
/**
* @en Global singleton for [[DependUtil]]. You can access it via [[AssetManager.dependUtil]].
* @zh [[DependUtil]] 的全局单例. 你可以通过 [[AssetManager.dependUtil]] 访问.
*/
static get instance () {
if (!this._instance) {
this._instance = new DependUtil();
}
return this._instance;
}
private constructor () {}
/**
* @engineInternal
*/
public init (): void {
this._depends.clear();
}
/**
* @en
* Get asset's native dependency. For example, Texture's native dependency is image.
* Gets asset's native dependency. For example, ImageAsset's native dependency is image.
* Note: You will need to have loaded this resource to query this information.
*
* @zh
* 获取资源的原生依赖,例如 Texture 的原生依赖是图片
* 获取资源的原生依赖,例如 ImageAsset 的原生依赖是图片。
* 注意:你需要加载过该资源,才能查询此信息。
*
* @param uuid - asset's uuid
* @returns native dependency
* @param uuid @en asset's uuid. @zh 资源的 uuid。
* @returns @en The native dependency information of this asset. @zh 资源的原生依赖的信息。
*
* @example
* var dep = dependUtil.getNativeDep('fcmR3XADNLgJ1ByKhqcC5Z');
* @deprecated Since v3.7, this is an engine internal interface.
* If you want to know the native dependency of the asset, use [[Asset.nativeUrl]] instead.
*/
public getNativeDep (uuid: string): Record<string, any> | null {
const depend = this._depends.get(uuid);
@@ -81,13 +101,15 @@ export class DependUtil {
/**
* @en
* Get asset's direct referencing non-native dependency list. For example, Material's non-native dependencies are Texture.
* Gets asset's direct referencing dependency list. For example, Material's dependencies are Texture, effect asset etc.
* Note: You will need to have loaded this resource to query this information.
*
* @zh
* 获取资源直接引用的非原生依赖列表,例如,材质的非原生依赖是 Texture
* 获取资源直接引用的依赖列表,例如,材质的直接依赖资源是 Texture, Effect 等。
* 注意:你需要加载过该资源,才能查询此信息。
*
* @param uuid - asset's uuid
* @returns direct referencing non-native dependency list
* @param uuid @en asset's uuid. @zh 资源的 uuid。
* @returns @en The direct referencing dependency asset list. @zh 直接引用的依赖资源列表。
*
* @example
* var deps = dependUtil.getDeps('fcmR3XADNLgJ1ByKhqcC5Z');
@@ -102,15 +124,17 @@ export class DependUtil {
/**
* @en
* Get non-native dependency list of the loaded asset, include indirect reference.
* The returned array stores the dependencies with their uuid, after retrieve dependencies,
* Gets dependency list of the loaded asset, include indirect reference.
* Note: You will need to have loaded this resource to query this information.
*
* @zh
* 获取某个已经加载好的资源的所有非原生依赖资源列表,包括间接引用的资源,并保存在数组中返回。
* 返回的数组将仅保存依赖资源的 uuid。
* 获取某个已经加载好的资源的所有依赖资源列表,包括间接引用的资源,并保存在数组中返回。
* 注意:你需要加载过该资源,才能查询此信息。
*
* @param uuid - The asset's uuid
* @returns non-native dependency list
* @param uuid @en asset's uuid. @zh 资源的 uuid。
* @returns
* @en The all dependency list including direct reference and indirect reference.
* @zh 所有依赖列表,包括直接引用的与间接引用的。
*
* @example
* var deps = dependUtil.getDepsRecursively('fcmR3XADNLgJ1ByKhqcC5Z');
@@ -123,13 +147,16 @@ export class DependUtil {
return depends;
}
/**
* @engineInternal
*/
public remove (uuid: string) {
this._depends.remove(uuid);
}
/**
* @en
* Extract dependency list from serialized data or asset and then store in cache.
* Extracts dependency list from serialized data or asset and then store in cache.
*
* @zh
* 从序列化数据或资源中提取出依赖列表,并且存储在缓存中。
@@ -143,6 +170,7 @@ export class DependUtil {
* var dependencies = parse('fcmR3XADNLgJ1ByKhqcC5Z', file);
* });
*
* @engineInternal
*/
public parse (uuid: string, json: any): IDependencies {
let out: IDependencies | null = null;
@@ -221,4 +249,4 @@ export class DependUtil {
}
}
export default new DependUtil();
export default DependUtil.instance;
+6 -5
View File
@@ -33,9 +33,10 @@ import downloader from './downloader';
import { getUuidFromURL, transform } from './helper';
import parser from './parser';
import releaseManager from './release-manager';
import { assets, BuiltinBundleName, bundles, ProgressCallback, CompleteCallback } from './shared';
import { assets, BuiltinBundleName, bundles } from './shared';
import { parseLoadResArgs, setDefaultProgressCallback } from './utilities';
import factory from './factory';
import RequestItem from './request-item';
const ImageFmts = ['.png', '.jpg', '.bmp', '.jpeg', '.gif', '.ico', '.tiff', '.webp', '.image', '.pvr', '.pkm', '.astc'];
const AudioFmts = ['.mp3', '.ogg', '.wav', '.m4a'];
@@ -92,7 +93,7 @@ export class CCLoader {
*
* @deprecated since v3.0, loader.onProgress is deprecated, please transfer onProgress to API as a parameter
*/
public set onProgress (val: ProgressCallback) {
public set onProgress (val: ((finished: number, total: number, item: RequestItem) => void)) {
setDefaultProgressCallback(val);
}
@@ -581,7 +582,7 @@ export class CCLoader {
* @param extMap Handlers for corresponding type in a map
* @deprecated since v3.0 loader.addDownloadHandlers is deprecated, please use assetManager.downloader.register instead
*/
public addDownloadHandlers (extMap: Record<string, (item: { url: string }, cb: CompleteCallback) => void>) {
public addDownloadHandlers (extMap: Record<string, (item: { url: string }, cb: ((err: Error | null, data?: any | null) => void)) => void>) {
const handler = Object.create(null);
for (const type in extMap) {
const func = extMap[type];
@@ -605,7 +606,7 @@ export class CCLoader {
* @param extMap Handlers for corresponding type in a map
* @deprecated since v3.0 loader.addLoadHandlers is deprecated, please use assetManager.parser.register instead
*/
public addLoadHandlers (extMap: Record<string, ({ content: any }, cb: CompleteCallback) => void>) {
public addLoadHandlers (extMap: Record<string, ({ content: any }, cb: ((err: Error | null, data?: any | null) => void)) => void>) {
const handler = Object.create(null);
for (const type in extMap) {
const func = extMap[type];
@@ -879,7 +880,7 @@ export const AssetLibrary = {
* @param {Asset} options.existingAsset - 加载现有资源,此参数仅在编辑器中可用。
* @deprecated since v3.0 AssetLibrary.loadAsset is deprecated, please use assetManager.loadAny instead
*/
loadAsset (uuid: string, callback: CompleteCallback, options?) {
loadAsset (uuid: string, callback: ((err: Error | null, data?: any | null) => void), options?) {
assetManager.loadAny(uuid, callback);
},
};
@@ -25,12 +25,11 @@
import { getError } from '../../core';
import { ccwindow } from '../../core/global-exports';
import { CompleteCallback, IDownloadParseOptions } from './shared';
export default function downloadDomImage (
url: string,
options: IDownloadParseOptions,
onComplete: CompleteCallback<HTMLImageElement>,
options: Record<string, any>,
onComplete: ((err: Error | null, data?: HTMLImageElement | null) => void),
): HTMLImageElement {
const img = new ccwindow.Image();
+2 -4
View File
@@ -22,15 +22,13 @@
THE SOFTWARE.
*/
import { CompleteCallback, IXHROptions } from './shared';
type FileProgressCallback = (loaded: number, total: number) => void;
export default function downloadFile (
url: string,
options: IXHROptions,
options: Record<string, any>,
onProgress: FileProgressCallback | null | undefined,
onComplete: CompleteCallback,
onComplete: ((err: Error | null, data?: any | null) => void),
): XMLHttpRequest {
const xhr = new XMLHttpRequest();
const errInfo = `download failed: ${url}, status: `;
+2 -3
View File
@@ -24,7 +24,6 @@
import { getError } from '../../core';
import { ccwindow } from '../../core/global-exports';
import { CompleteCallback, IBundleOptions } from './shared';
const ccdocument = ccwindow.document;
@@ -32,8 +31,8 @@ const downloaded = {};
export default function downloadScript (
url: string,
options: IBundleOptions,
onComplete: CompleteCallback,
options: Record<string, any>,
onComplete: ((err: Error | null, data?: any | null) => void),
): HTMLScriptElement | null {
// no need to load script again
if (downloaded[url]) {
+116 -76
View File
@@ -28,46 +28,46 @@ import Cache from './cache';
import downloadDomImage from './download-dom-image';
import downloadFile from './download-file';
import downloadScript from './download-script';
import { CompleteCallback, CompleteCallbackNoData, IBundleOptions, IDownloadParseOptions, files } from './shared';
import { files } from './shared';
import { retry, RetryFunction, urlAppendTimestamp } from './utilities';
import { IConfigOption } from './config';
import { CCON, parseCCONJson, decodeCCONBinary } from '../../serialization/ccon';
export type DownloadHandler = (url: string, options: IDownloadParseOptions, onComplete: CompleteCallback) => void;
export type DownloadHandler = (url: string, options: Record<string, any>, onComplete: ((err: Error | null, data?: any | null) => void)) => void;
interface IDownloadRequest {
id: string;
priority: number;
url: string;
options: IDownloadParseOptions;
done: CompleteCallback;
options: Record<string, any>;
done: ((err: Error | null, data?: any | null) => void);
handler: DownloadHandler;
}
const REGEX = /^(?:\w+:\/\/|\.+\/).+/;
const downloadImage = (url: string, options: IDownloadParseOptions, onComplete: CompleteCallback) => {
const downloadImage = (url: string, options: Record<string, any>, onComplete: ((err: Error | null, data?: any | null) => void)) => {
// if createImageBitmap is valid, we can transform blob to ImageBitmap. Otherwise, just use HTMLImageElement to load
const func = sys.hasFeature(sys.Feature.IMAGE_BITMAP) && cclegacy.assetManager.allowImageBitmap ? downloadBlob : downloadDomImage;
func(url, options, onComplete);
};
const downloadBlob = (url: string, options: IDownloadParseOptions, onComplete: CompleteCallback) => {
const downloadBlob = (url: string, options: Record<string, any>, onComplete: ((err: Error | null, data?: any | null) => void)) => {
options.xhrResponseType = 'blob';
downloadFile(url, options, options.onFileProgress, onComplete);
};
const downloadJson = (url: string, options: IDownloadParseOptions, onComplete: CompleteCallback<Record<string, any>>) => {
const downloadJson = (url: string, options: Record<string, any>, onComplete: ((err: Error | null, data?: Record<string, any> | null) => void)) => {
options.xhrResponseType = 'json';
downloadFile(url, options, options.onFileProgress, onComplete);
};
const downloadArrayBuffer = (url: string, options: IDownloadParseOptions, onComplete: CompleteCallback) => {
const downloadArrayBuffer = (url: string, options: Record<string, any>, onComplete: ((err: Error | null, data?: any | null) => void)) => {
options.xhrResponseType = 'arraybuffer';
downloadFile(url, options, options.onFileProgress, onComplete);
};
const downloadCCON = (url: string, options: IDownloadParseOptions, onComplete: CompleteCallback<CCON>) => {
const downloadCCON = (url: string, options: Record<string, any>, onComplete: ((err: Error | null, data?: CCON | null) => void)) => {
downloadJson(url, options, (err, json) => {
if (err) {
onComplete(err);
@@ -92,7 +92,7 @@ const downloadCCON = (url: string, options: IDownloadParseOptions, onComplete: C
});
};
const downloadCCONB = (url: string, options: IDownloadParseOptions, onComplete: CompleteCallback<CCON>) => {
const downloadCCONB = (url: string, options: Record<string, any>, onComplete: ((err: Error | null, data?: CCON | null) => void)) => {
downloadArrayBuffer(url, options, (err, arrayBuffer: ArrayBuffer) => {
if (err) {
onComplete(err);
@@ -107,12 +107,12 @@ const downloadCCONB = (url: string, options: IDownloadParseOptions, onComplete:
});
};
const downloadText = (url: string, options: IDownloadParseOptions, onComplete: CompleteCallback) => {
const downloadText = (url: string, options: Record<string, any>, onComplete: ((err: Error | null, data?: any | null) => void)) => {
options.xhrResponseType = 'text';
downloadFile(url, options, options.onFileProgress, onComplete);
};
const downloadBundle = (nameOrUrl: string, options: IBundleOptions, onComplete: CompleteCallback) => {
const downloadBundle = (nameOrUrl: string, options: Record<string, any>, onComplete: ((err: Error | null, data?: any | null) => void)) => {
const bundleName = path.basename(nameOrUrl);
let url = nameOrUrl;
if (!REGEX.test(url)) {
@@ -147,49 +147,50 @@ const downloadBundle = (nameOrUrl: string, options: IBundleOptions, onComplete:
/**
* @en
* Control all download process, it is a singleton.
* All member can be accessed with `assetManager.downloader`, it can download several types of files:
* 1. Text
* 2. Image
* 3. Audio
* 4. Assets
* 5. Scripts
* Manages all download process, it is a singleton.
* You can access it via [[AssetManager.downloader]], It can download various types of files.
*
* @zh
* 管理所有下载过程,downloader 是个单例,所有成员能通过 `assetManager.downloader` 访问,它能下载以下几种类型的文件:
* 1. 文本
* 2. 图片
* 3. 音频
* 4. 资源
* 5. 脚本
* 管理所有下载过程,downloader 是个单例,你能通过 [[AssetManager.downloader]] 访问它,它能下载各种类型的文件。
*
*/
export class Downloader {
/**
* @en Global singleton for [[Downloader]]. You can access it via [[AssetManager.downloader]].
* @zh [[Downloader]] 的全局单例. 你可以通过 [[AssetManager.downloader]] 访问.
*/
public static get instance () {
if (!Downloader._instance) {
Downloader._instance = new Downloader();
}
return Downloader._instance;
}
/**
* @en
* The maximum number of concurrent when downloading
* The maximum number of concurrent when downloading.
*
* @zh
* 下载时的最大并发数
* 下载时的最大并发数。
*/
public maxConcurrency = 6;
/**
* @en
* The maximum number of request can be launched per frame when downloading
* The maximum number of request can be launched per frame when downloading.
*
* @zh
* 下载时每帧可以启动的最大请求数
* 下载时每帧可以启动的最大请求数。
*
*/
public maxRequestsPerFrame = 6;
/**
* @en
* The address of remote server
* The address of remote server.
*
* @zh
* 远程服务器地址
* 远程服务器地址。
*
*/
public get remoteServerAddress () {
@@ -198,40 +199,67 @@ export class Downloader {
/**
* @en
* The max number of retries when fail
* The max number of retries when fail.
*
* @zh
* 失败重试次数
* 失败重试次数。
*
* @property maxRetryCount
* @type {Number}
*/
public maxRetryCount = BUILD ? 3 : 0;
/**
* Whether to automatically add a timestamp after the url.
* This function is mainly used to prevent the browser from using cache in editor mode.
* You don't need to change it at runtime.
* @internal
*/
public appendTimeStamp = !!EDITOR;
/**
* @engineInternal
*/
public limited = !EDITOR;
/**
* @en
* Wait for while before another retry, unit: ms
* Wait for while before another retry, unit: ms.
*
* @zh
* 重试的间隔时间
* 重试的间隔时间,单位为毫秒。
*
*/
public retryInterval = 2000;
/**
* Version information of all bundles.
* @engineInternal
*/
public bundleVers: Record<string, string> | null = null;
public remoteBundles: string[] = [];
/**
* Remote bundle list.
* @engineInternal
*/
public remoteBundles: ReadonlyArray<string> = [];
/**
* @deprecated Since v3.7, this is an engine internal interface. You can easily implement the functionality of this API using HTMLImageElement.
*/
public downloadDomImage = downloadDomImage;
/**
* @deprecated Since v3.7, this is an engine internal interface. You can easily implement the functionality of this API using HTMLAudioElement.
*/
public downloadDomAudio: DownloadHandler | null = null;
/**
* @deprecated Since v3.7, this is an engine internal interface. You can easily implement the functionality of this API using XMLHttpRequest.
*/
public downloadFile = downloadFile;
/**
* @deprecated Since v3.7, this is an engine internal interface. You can easily implement the functionality of this API using XMLHttpRequest.
*/
public downloadScript = downloadScript;
// default handler map
@@ -282,7 +310,7 @@ export class Downloader {
default: downloadText,
};
private _downloading = new Cache<CompleteCallback[]>();
private _downloading = new Cache<((err: Error | null, data?: any | null) => void)[]>();
private _queue: IDownloadRequest[] = [];
private _queueDirty = false;
// the number of loading thread
@@ -295,7 +323,11 @@ export class Downloader {
private _checkNextPeriod = false;
private _remoteServerAddress = '';
private _maxInterval = 1 / 30;
private static _instance: Downloader;
/**
* @engineInternal
*/
public init (remoteServerAddress = '', bundleVers: Record<string, string> = {}, remoteBundles: string[] = []) {
this._downloading.clear();
this._queue.length = 0;
@@ -306,16 +338,21 @@ export class Downloader {
/**
* @en
* Register custom handler if you want to change default behavior or extend downloader to download other format file
* Register custom handler if you want to change default behavior or extend downloader to download other format file.
*
* @zh
* 当你想修改默认行为或者拓展 downloader 来下载其他格式文件时可以注册自定义的 handler
* 当你想修改默认行为或者拓展 downloader 来下载其他格式文件时可以注册自定义的 handler。
*
* @param type - Extension likes '.jpg' or map likes {'.jpg': jpgHandler, '.png': pngHandler}
* @param handler - handler
* @param handler.url - url
* @param handler.options - some optional parameters will be transferred to handler.
* @param handler.onComplete - callback when finishing downloading
* @param type
* @en Extension name likes '.jpg' or map likes {'.jpg': jpgHandler, '.png': pngHandler}.
* @zh 扩展名,或者形如 {'.jpg': jpgHandler, '.png': pngHandler} 的映射表。
* @param handler @en Customized handling for this extension. @zh 针对此扩展名的自定义的处理方法。
* @param handler.url @en The url to be downloaded. @zh 待下载的 url.
* @param handler.options @en Some optional parameters will be transferred to handler. @zh 传递到处理方法的可选参数。
* @param handler.onComplete
* @en Callback when finishing downloading. You need to call this method manually and pass in the execution result after the custom handler
* is executed.
* @zh 完成下载后的回调。你需要在自定义处理方法执行完后手动调用此方法,并将执行结果传入。
*
* @example
* downloader.register('.tga', (url, options, onComplete) => onComplete(null, null));
@@ -323,9 +360,12 @@ export class Downloader {
* '.ext': (url, options, onComplete) => onComplete(null, null)});
*
*/
public register (type: string, handler: DownloadHandler): void;
public register (map: Record<string, DownloadHandler>): void;
public register (type: string | Record<string, DownloadHandler>, handler?: DownloadHandler) {
public register (type: string, handler: (url: string, options: Record<string, any>, onComplete: ((err: Error | null, data?: any | null) => void)) => void): void;
public register (map: Record<string, (url: string, options: Record<string, any>, onComplete: ((err: Error | null, data?: any | null) => void)) => void>): void;
public register (
type: string | Record<string, (url: string, options: Record<string, any>, onComplete: ((err: Error | null, data?: any | null) => void)) => void>,
handler?: (url: string, options: Record<string, any>, onComplete: ((err: Error | null, data?: any | null) => void)) => void,
) {
if (typeof type === 'object') {
js.mixin(this._downloaders, type);
} else {
@@ -335,29 +375,29 @@ export class Downloader {
/**
* @en
* Use corresponding handler to download file under limitation
* Use corresponding handler to download file under limitation.
*
* @zh
* 在限制下使用对应的 handler 来下载文件
* 在限制下使用对应的 handler 来下载文件。
*
* @param id - The unique id of this download
* @param url - The url should be downloaded
* @param type - The type indicates that which handler should be used to download, such as '.jpg'
* @param options - some optional parameters will be transferred to the corresponding handler.
* @param options.onFileProgress - progressive callback will be transferred to handler.
* @param options.maxRetryCount - How many times should retry when download failed
* @param options.maxConcurrency - The maximum number of concurrent when downloading
* @param options.maxRequestsPerFrame - The maximum number of request can be launched per frame when downloading
* @param options.priority - The priority of this url, default is 0, the greater number is higher priority.
* @param onComplete - callback when finishing downloading
* @param onComplete.err - The occurred error, null indicates success
* @param onComplete.content - The downloaded file
* @param id @en The unique id of this download. @zh 本次下载的唯一 id.
* @param url @en The url should be downloaded. @zh 待下载的 url。
* @param type @en The type indicates that which handler should be used to download, such as '.jpg'. @zh 要使用的处理方法的类型,例如 '.jpg'。
* @param options @en Some optional parameters will be transferred to the corresponding handler. @zh 传递到处理方法的一些可选参数。
* @param options.onFileProgress @en Progressive callback will be transferred to handler. @zh 传递到处理方法的进度回调。
* @param options.maxRetryCount @en How many times should retry when download failed. @zh 下载失败后的重试数量。
* @param options.maxConcurrency @en The maximum number of concurrent when downloading. @zh 下载的最大并行数。
* @param options.maxRequestsPerFrame @en The maximum number of request can be launched per frame when downloading. @zh 每帧能发起的最大请求数量,在下载时。
* @param options.priority @en The priority of this url, default is 0, the greater number is higher priority. @zh 下载的优先级,值越大优先级越高。
* @param onComplete @en Callback when finishing downloading. @zh 完成下载后的回调。
* @param onComplete.err @en The occurred error, null indicates success. @zh 下载过程中出现的错误,如果为 null 则表明下载成功。
* @param onComplete.content @en The downloaded file. @zh 下载下来的文件内容。
*
* @example
* download('http://example.com/test.tga', '.tga', { onFileProgress: (loaded, total) => console.log(loaded/total) },
* onComplete: (err) => console.log(err));
*/
public download (id: string, url: string, type: string, options: IDownloadParseOptions, onComplete: CompleteCallback): void {
public download (id: string, url: string, type: string, options: Record<string, any>, onComplete: ((err: Error | null, data?: any | null) => void)): void {
// if it is downloaded, don't download again
const file = files.get(id);
if (file) {
@@ -397,7 +437,7 @@ export class Downloader {
// refresh
this._updateTime();
const done: CompleteCallback = (err, data) => {
const done: ((err: Error | null, data?: any | null) => void) = (err, data) => {
// when finish downloading, update _totalNum
this._totalNum--;
this._handleQueueInNextFrame(maxConcurrency, maxRequestsPerFrame);
@@ -420,7 +460,7 @@ export class Downloader {
// when retry finished, invoke callbacks
const finale = (err, result) => {
if (!err) { files.add(id, result); }
const callbacks = this._downloading.remove(id) as CompleteCallback[];
const callbacks = this._downloading.remove(id) as ((err: Error | null, data?: any | null) => void)[];
for (let i = 0, l = callbacks.length; i < l; i++) {
callbacks[i](err, result);
}
@@ -431,17 +471,19 @@ export class Downloader {
/**
* @en Load sub package with name.
* @zh 通过子包名加载子包代码。
* @param name - Sub package name
* @param completeCallback - Callback invoked when sub package loaded
* @param {Error} completeCallback.error - error information
* @zh 通过子包名加载子包。
* @param name @en Sub package name. @zh 子包名称。
* @param completeCallback @en Callback invoked when sub package loaded. @zh 子包加载完成后的回调。
* @param completeCallback.error @en Error information. Will be null if loaded successfully. @zh 错误信息。如果加载成功则为 null。
*
* @deprecated loader.downloader.loadSubpackage is deprecated, please use AssetManager.loadBundle instead
* @deprecated loader.downloader.loadSubpackage is deprecated, please use AssetManager.loadBundle instead.
*/
public loadSubpackage (name: string, completeCallback?: CompleteCallbackNoData) {
public loadSubpackage (name: string, completeCallback?: ((err?: Error | null) => void)) {
cclegacy.assetManager.loadBundle(name, null, completeCallback);
}
private constructor () {}
private _updateTime () {
const now = performance.now();
// use deltaTime as interval
@@ -481,7 +523,5 @@ export class Downloader {
}
}
}
const downloader = new Downloader();
export default downloader;
const downloader = Downloader.instance;
export default Downloader.instance;
@@ -24,13 +24,13 @@
import { EDITOR, NATIVE, PREVIEW, TEST } from 'internal:constants';
import { assert, Settings, settings } from '../../core';
import { fetchPipeline, pipeline } from './shared';
import Task, { TaskCompleteCallback } from './task';
import Task from './task';
declare const Editor: any;
if ((EDITOR || PREVIEW) && !TEST) {
const cache: {[uuid: string]: string | null} = {};
const resolveMap: { [uuid: string]: Function[] } = {};
const replaceExtension = (task: Task, done: TaskCompleteCallback) => {
const replaceExtension = (task: Task, done) => {
task.output = task.input;
(async () => {
for (let i = 0; i < task.input.length; i++) {
+10 -11
View File
@@ -32,15 +32,14 @@ import Bundle, { resources } from './bundle';
import Cache from './cache';
import { IConfigOption } from './config';
import {
assets, BuiltinBundleName, bundles, CompleteCallback, IRemoteOptions,
IDownloadParseOptions,
assets, BuiltinBundleName, bundles,
} from './shared';
import { cache } from './utilities';
import { js } from '../../core';
export type CreateHandler = (id: string, data: any, options: IDownloadParseOptions, onComplete: CompleteCallback<Asset|Bundle>) => void;
export type CreateHandler = (id: string, data: any, options: Record<string, any>, onComplete: ((err: Error | null, data?: Asset | Bundle | null) => void)) => void;
function createImageAsset (id: string, data: HTMLImageElement, options: IDownloadParseOptions, onComplete: CompleteCallback<ImageAsset>) {
function createImageAsset (id: string, data: HTMLImageElement, options: Record<string, any>, onComplete: ((err: Error | null, data?: ImageAsset | null) => void)) {
let out: ImageAsset | null = null;
let err: Error | null = null;
try {
@@ -53,33 +52,33 @@ function createImageAsset (id: string, data: HTMLImageElement, options: IDownloa
onComplete(err, out);
}
function createJsonAsset (id: string, data: Record<string, any>, options: IDownloadParseOptions, onComplete: CompleteCallback<JsonAsset>) {
function createJsonAsset (id: string, data: Record<string, any>, options: Record<string, any>, onComplete: ((err: Error | null, data?: JsonAsset | null) => void)) {
const out = new JsonAsset();
out.json = data;
onComplete(null, out);
}
function createTextAsset (id: string, data: string, options: IDownloadParseOptions, onComplete: CompleteCallback<TextAsset>) {
function createTextAsset (id: string, data: string, options: Record<string, any>, onComplete: ((err: Error | null, data?: TextAsset | null) => void)) {
const out = new TextAsset();
out.text = data;
onComplete(null, out);
}
function createBufferAsset (id: string, data: ArrayBufferView, options: IDownloadParseOptions, onComplete: CompleteCallback<BufferAsset>) {
function createBufferAsset (id: string, data: ArrayBufferView, options: Record<string, any>, onComplete: ((err: Error | null, data?: BufferAsset | null) => void)) {
const out = new BufferAsset();
out._nativeUrl = id;
out._nativeAsset = data;
onComplete(null, out);
}
function createAsset (id: string, data: any, options: IDownloadParseOptions, onComplete: CompleteCallback<Asset>) {
function createAsset (id: string, data: any, options: Record<string, any>, onComplete: ((err: Error | null, data?: Asset | null) => void)) {
const out = new Asset();
out._nativeUrl = id;
out._nativeAsset = data;
onComplete(null, out);
}
function createBundle (id: string, data: IConfigOption, options: IDownloadParseOptions, onComplete: CompleteCallback<Bundle>) {
function createBundle (id: string, data: IConfigOption, options: Record<string, any>, onComplete: ((err: Error | null, data?: Bundle | null) => void)) {
let bundle = bundles.get(data.name);
if (!bundle) {
bundle = data.name === BuiltinBundleName.RESOURCES ? resources : new Bundle();
@@ -97,7 +96,7 @@ function createBundle (id: string, data: IConfigOption, options: IDownloadParseO
}
export class Factory {
private _creating = new Cache<CompleteCallback[]>();
private _creating = new Cache<((err: Error | null, data?: any | null) => void)[]>();
private _producers: Record<string, CreateHandler> = {
// Images
@@ -147,7 +146,7 @@ export class Factory {
}
}
public create (id: string, data: any, type: string, options: IRemoteOptions, onComplete: CompleteCallback<Asset | Bundle>): void {
public create (id: string, data: any, type: string, options: Record<string, any>, onComplete: ((err: Error | null, data?: Asset | Bundle | null) => void)): void {
const handler = this._producers[type] || this._producers.default;
const asset = assets.get(id);
if (!options.reloadAsset && asset) {
+5 -5
View File
@@ -26,11 +26,11 @@ import { Asset } from '../assets';
import { error, cclegacy } from '../../core';
import packManager from './pack-manager';
import RequestItem from './request-item';
import { assets, CompleteCallbackNoData, fetchPipeline } from './shared';
import { assets, fetchPipeline } from './shared';
import Task from './task';
import { clear, forEach, getDepends } from './utilities';
export default function fetch (task: Task, done: CompleteCallbackNoData) {
export default function fetch (task: Task, done: ((err?: Error | null) => void)) {
let firstTask = false;
if (!task.progress) {
task.progress = { finish: 0, total: task.input.length, canInvoke: true };
@@ -58,7 +58,7 @@ export default function fetch (task: Task, done: CompleteCallbackNoData) {
packManager.load(item, task.options, (err, data) => {
if (err) {
if (!task.isFinish) {
if (!task.isFinished) {
if (!cclegacy.assetManager.force || firstTask) {
error(err.message, err.stack);
progress.canInvoke = false;
@@ -70,7 +70,7 @@ export default function fetch (task: Task, done: CompleteCallbackNoData) {
}
}
}
} else if (!task.isFinish) {
} else if (!task.isFinished) {
item.file = data;
task.output.push(item);
if (!item.isNative) {
@@ -85,7 +85,7 @@ export default function fetch (task: Task, done: CompleteCallbackNoData) {
cb();
});
}, () => {
if (task.isFinish) {
if (task.isFinished) {
clear(task, true);
task.dispatch('error');
return;
+21 -22
View File
@@ -23,7 +23,7 @@
*/
import { cclegacy, error } from '../../core';
import RequestItem from './request-item';
import { bundles, Request, IOptions, transformPipeline } from './shared';
import { bundles, transformPipeline } from './shared';
import Task from './task';
const _uuidRegex = /.*[/\\][0-9a-fA-F]{2}[/\\]([0-9a-fA-F-@]{8,}).*/;
@@ -32,13 +32,13 @@ export { default as decodeUuid } from '../../core/utils/decode-uuid';
/**
* @en
* Extract uuid from url
* Extracts uuid from url.
*
* @zh
* 从 url 中提取 uuid
* 从 url 中提取 uuid。
*
* @param url - url
* @returns the uuid parsed from url
* @param url @en The url to be converted. @zh 待转换的 url。
* @returns @en The uuid extracted from url. @zh url 转换为的 uuid。
*
* @example
* var url = 'res/import/fc/fc991dd7-0033-4b80-9d41-c8a86a702e59.json';
@@ -54,16 +54,16 @@ export function getUuidFromURL (url: string): string {
/**
* @en
* Transform uuid to url
* Transforms uuid to url.
*
* @zh
* 转换 uuid 为 url
* 转换 uuid 为 url。
*
* @param uuid - The uuid of asset
* @param options - Some optional parameters
* @param options.isNative - Indicates whether the path you want is a native resource path
* @param options.nativeExt - Extension of the native resource path, it is required when isNative is true
* @returns url
* @param uuid @en The uuid of asset. @zh 资源的 uuid。
* @param options @en Some optional parameters. @zh 一些可选参数。
* @param options.isNative @en Indicates whether the path you want is a native resource path. @zh 需要转换的路径是否是原生资源路径。
* @param options.nativeExt @en Extension of the native resource path, it is required when isNative is true. @zh 原生资源路径的扩展名,如果 `isNative` 为 true,则需要。
* @returns @en The url converted from uuid. @zh 从 uuid 转换而来的 url.
*
* @example
* // json path, 'assets/main/import/fc/fc991dd7-0033-4b80-9d41-c8a86a702e59.json';
@@ -90,14 +90,13 @@ export function getUrlWithUuid (uuid: string, options?: { [k: string]: any, isNa
/**
* @en
* Check if the type of asset is scene
* Checks if the type of asset is scene.
*
* @zh
* 检查资源类型是否是场景
* 检查资源类型是否是场景。
*
* @method isScene
* @param {*} asset - asset
* @returns {boolean} - whether or not type is SceneAsset
* @param asset @en The asset to be checked. @zh 待检查的资源。
* @returns @en Whether or not the asset is a SceneAsset. @zh 此资源是否是场景资源。
*
*/
export function isScene (asset) {
@@ -106,13 +105,13 @@ export function isScene (asset) {
/**
* @en
* Normalize url, strip './' and '/'
* Normalizes url, strip './' and '/'.
*
* @zh
* 标准化 url ,去除 './' 和 '/'
* 标准化 url ,去除 './' 和 '/'。
*
* @param url - url
* @returns - The normalized url
* @param url @en The url to be normalized. @zh 待标准化的 url。
* @returns @en The normalized url. @zh 标准化后的 url。
*/
export function normalize (url: string): string {
if (url) {
@@ -127,7 +126,7 @@ export function normalize (url: string): string {
return url;
}
export function transform (input: Request, options?: IOptions | null): string | string[] {
export function transform (input: string | string[] | Record<string, any> | Array<Record<string, any>>, options?: Record<string, any> | null): string | string[] {
const subTask = Task.create({ input, options });
const urls: string[] = [];
try {
+6 -6
View File
@@ -28,7 +28,7 @@ import packManager from './pack-manager';
import parser from './parser';
import { Pipeline } from './pipeline';
import RequestItem from './request-item';
import { CompleteCallbackNoData, assets, files, parsed, pipeline } from './shared';
import { assets, files, parsed, pipeline } from './shared';
import Task from './task';
import { cache, checkCircleReference, clear, forEach, gatherAsset, getDepends, setProperties } from './utilities';
import { nativeDependMap, onLoadedInvokedMap } from './depend-maps';
@@ -43,10 +43,10 @@ interface ILoadingRequest {
content: Asset;
finish: boolean;
err?: Error | null;
callbacks: Array<{ done: CompleteCallbackNoData; item: RequestItem }>;
callbacks: Array<{ done: ((err?: Error | null) => void); item: RequestItem }>;
}
export default function load (task: Task, done: CompleteCallbackNoData) {
export default function load (task: Task, done: ((err?: Error | null) => void)) {
let firstTask = false;
if (!task.progress) {
task.progress = { finish: 0, total: task.input.length, canInvoke: true };
@@ -66,7 +66,7 @@ export default function load (task: Task, done: CompleteCallbackNoData) {
options,
progress,
onComplete: (err, result) => {
if (err && !task.isFinish) {
if (err && !task.isFinished) {
if (!cclegacy.assetManager.force || firstTask) {
if (BUILD) {
error(err.message, err.stack);
@@ -87,7 +87,7 @@ export default function load (task: Task, done: CompleteCallbackNoData) {
}, () => {
options!.__exclude__ = null;
if (task.isFinish) {
if (task.isFinished) {
clear(task, true);
task.dispatch('error');
return;
@@ -173,7 +173,7 @@ const loadOneAssetPipeline = new Pipeline('loadOneAsset', [
},
]);
function loadDepends (task: Task, asset: Asset, done: CompleteCallbackNoData) {
function loadDepends (task: Task, asset: Asset, done: ((err?: Error | null) => void)) {
const { input: item, progress } = task;
const { uuid, id, options, config } = item as RequestItem;
const { cacheAsset } = options;
+6 -6
View File
@@ -30,12 +30,12 @@ import Cache from './cache';
import downloader from './downloader';
import { transform } from './helper';
import RequestItem from './request-item';
import { CompleteCallback, files, IDownloadParseOptions } from './shared';
import { files } from './shared';
export type Unpacker = (packUuid: string[], data: any, options: IDownloadParseOptions, onComplete: CompleteCallback) => void;
export type Unpacker = (packUuid: string[], data: any, options: Record<string, any>, onComplete: ((err: Error | null, data?: any | null) => void)) => void;
interface IUnpackRequest {
onComplete: CompleteCallback;
onComplete: ((err: Error | null, data?: any | null) => void);
id: string;
}
@@ -73,7 +73,7 @@ export class PackManager {
* });
*
*/
public unpackJson (pack: string[], json: any, options: IDownloadParseOptions, onComplete: CompleteCallback<Record<string, any>>): void {
public unpackJson (pack: string[], json: any, options: Record<string, any>, onComplete: ((err: Error | null, data?: Record<string, any> | null) => void)): void {
let out = js.createMap(true);
let err: Error | null = null;
@@ -170,7 +170,7 @@ export class PackManager {
* });
*
*/
public unpack (pack: string[], data: any, type: string, options: IDownloadParseOptions, onComplete: CompleteCallback): void {
public unpack (pack: string[], data: any, type: string, options: Record<string, any>, onComplete: ((err: Error | null, data?: any | null) => void)): void {
if (!data) {
onComplete(new Error('package data is wrong!'));
return;
@@ -200,7 +200,7 @@ export class PackManager {
* packManager.load(requestItem, null, (err, data) => console.log(err));
*
*/
public load (item: RequestItem, options: IDownloadParseOptions | null, onComplete: CompleteCallback): void {
public load (item: RequestItem, options: Record<string, any> | null, onComplete: ((err: Error | null, data?: any | null) => void)): void {
// if not in any package, download as uausl
if (item.isNative || !item.info || !item.info.packs) {
downloader.download(item.id, item.url, item.ext, item.options, onComplete);
+68 -32
View File
@@ -28,22 +28,22 @@ import Cache from './cache';
import deserialize from './deserialize';
import { isScene } from './helper';
import plistParser from './plist-parser';
import { CompleteCallback, IDownloadParseOptions, files, parsed } from './shared';
import { files, parsed } from './shared';
import { CCON } from '../../serialization/ccon';
import { Asset } from '../assets';
export type ParseHandler = (file: any, options: IDownloadParseOptions, onComplete: CompleteCallback) => void;
export type ParseHandler = (file: any, options: Record<string, any>, onComplete: ((err: Error | null, data?: any | null) => void)) => void;
/**
* @en
* Parse the downloaded file, it's a singleton, all member can be accessed with `assetManager.parser`
* Parse the downloaded file, it's a singleton, you can access it via [[AssetManager.parser]].
*
* @zh
* 解析已下载的文件,parser 是一个单例, 所有成员能通过 `assetManaager.parser` 访问
* 解析已下载的文件,parser 是一个单例, 你能通过 [[assetManager.parser]] 访问它。
*
*/
export class Parser {
private _parsing = new Cache<CompleteCallback[]>();
private _parsing = new Cache<((err: Error | null, data?: any | null) => void)[]>();
private _parsers: Record<string, ParseHandler> = {
'.png': this.parseImage,
@@ -67,7 +67,20 @@ export class Parser {
'.cconb': this.parseImport,
};
public parseImage (file: HTMLImageElement | Blob, options: IDownloadParseOptions, onComplete: CompleteCallback<HTMLImageElement|ImageBitmap>) {
private static _instance: Parser;
public static get instance () {
if (!this._instance) {
this._instance = new Parser();
}
return this._instance;
}
private constructor () {}
/**
* @engineInternal
*/
public parseImage (file: HTMLImageElement | Blob, options: Record<string, any>, onComplete: ((err: Error | null, data?: HTMLImageElement | ImageBitmap | null) => void)) {
if (file instanceof HTMLImageElement) {
onComplete(null, file);
return;
@@ -79,7 +92,10 @@ export class Parser {
});
}
public parsePVRTex (file: ArrayBuffer | ArrayBufferView, options: IDownloadParseOptions, onComplete: CompleteCallback<IMemoryImageSource>) {
/**
* @engineInternal
*/
public parsePVRTex (file: ArrayBuffer | ArrayBufferView, options: Record<string, any>, onComplete: ((err: Error | null, data?: IMemoryImageSource | null) => void)) {
let err: Error | null = null;
let out: IMemoryImageSource | null = null;
try {
@@ -91,7 +107,10 @@ export class Parser {
onComplete(err, out);
}
public parsePKMTex (file: ArrayBuffer | ArrayBufferView, options: IDownloadParseOptions, onComplete: CompleteCallback<IMemoryImageSource>) {
/**
* @engineInternal
*/
public parsePKMTex (file: ArrayBuffer | ArrayBufferView, options: Record<string, any>, onComplete: ((err: Error | null, data?: IMemoryImageSource | null) => void)) {
let err: Error | null = null;
let out: IMemoryImageSource | null = null;
try {
@@ -103,7 +122,10 @@ export class Parser {
onComplete(err, out);
}
public parseASTCTex (file: ArrayBuffer | ArrayBufferView, options: IDownloadParseOptions, onComplete: CompleteCallback<IMemoryImageSource>) {
/**
* @engineInternal
*/
public parseASTCTex (file: ArrayBuffer | ArrayBufferView, options: Record<string, any>, onComplete: ((err: Error | null, data?: IMemoryImageSource | null) => void)) {
let err: Error | null = null;
let out: IMemoryImageSource | null = null;
try {
@@ -115,14 +137,20 @@ export class Parser {
onComplete(err, out);
}
public parsePlist (file: string, options: IDownloadParseOptions, onComplete: CompleteCallback) {
/**
* @engineInternal
*/
public parsePlist (file: string, options: Record<string, any>, onComplete: ((err: Error | null, data?: any | null) => void)) {
let err: Error | null = null;
const result = plistParser.parse(file);
if (!result) { err = new Error('parse failed'); }
onComplete(err, result);
}
public parseImport (file: Record<string, any> | CCON, options: IDownloadParseOptions, onComplete: CompleteCallback<Asset>) {
/**
* @engineInternal
*/
public parseImport (file: Record<string, any> | CCON, options: Record<string, any>, onComplete: ((err: Error | null, data?: Asset | null) => void)) {
if (!file) {
onComplete(new Error(`The json file of asset ${options.__uuid__ as string} is empty or missing`));
return;
@@ -137,22 +165,27 @@ export class Parser {
onComplete(err, result);
}
/**
* @engineInternal
*/
public init () {
this._parsing.clear();
}
/**
* @en
* Register custom handler if you want to change default behavior or extend parser to parse other format file
* Register custom handler if you want to change default behavior or extend parser to parse other format file.
*
* @zh
* 当你想修改默认行为或者拓展 parser 来解析其他格式文件时可以注册自定义的handler
* 当你想修改默认行为或者拓展 parser 来解析其他格式文件时可以注册自定义的 handler。
*
* @param type - Extension likes '.jpg' or map likes {'.jpg': jpgHandler, '.png': pngHandler}
* @param handler - The corresponding handler
* @param handler.file - File
* @param handler.options - Some optional paramter
* @param handler.onComplete - callback when finishing parsing
* @param type
* @en Extension name likes '.jpg' or map likes {'.jpg': jpgHandler, '.png': pngHandler}.
* @zh 形如 '.jpg' 的扩展名或形如 {'.jpg': jpgHandler, '.png': pngHandler} 的映射表。
* @param handler @en The corresponding handler. @zh 对应扩展名的处理方法。
* @param handler.file @en The file to be parsed. @zh 待解析的文件。
* @param handler.options @en Some optional parameters. @zh 一些可选的参数。
* @param handler.onComplete @en The callback invoked when parsing finished. @zh 完成解析的回调。
*
* @example
* parser.register('.tga', (file, options, onComplete) => onComplete(null, null));
@@ -160,9 +193,12 @@ export class Parser {
* '.ext': (file, options, onComplete) => onComplete(null, null)});
*
*/
public register (type: string, handler: ParseHandler): void;
public register (map: Record<string, ParseHandler>): void;
public register (type: string | Record<string, ParseHandler>, handler?: ParseHandler) {
public register (type: string, handler: (file: any, options: Record<string, any>, onComplete: ((err: Error | null, data?: any | null) => void)) => void): void;
public register (map: Record<string, (file: any, options: Record<string, any>, onComplete: ((err: Error | null, data?: any | null) => void)) => void>): void;
public register (
type: string | Record<string, (file: any, options: Record<string, any>, onComplete: ((err: Error | null, data?: any | null) => void)) => void>,
handler?: (file: any, options: Record<string, any>, onComplete: ((err: Error | null, data?: any | null) => void)) => void,
) {
if (typeof type === 'object') {
js.mixin(this._parsers, type);
} else {
@@ -172,18 +208,18 @@ export class Parser {
/**
* @en
* Use corresponding handler to parse file
* Use corresponding handler to parse file.
*
* @zh
* 使用对应的handler来解析文件
* 使用对应的 handler 来解析文件。
*
* @param id - The id of file
* @param file - File
* @param type - The corresponding type of file, likes '.jpg'.
* @param options - Some optional parameters will be transferred to the corresponding handler.
* @param onComplete - callback when finishing downloading
* @param onComplete.err - The occurred error, null indicates success
* @param onComplete.content - The parsed file
* @param id @en The id of file. @zh 文件的唯一 id。
* @param file @en The data of file. @zh 文件的数据。
* @param type @en The corresponding type of file, likes '.jpg'. @zh 需要使用的解析方法类型。
* @param options @en Some optional parameters will be transferred to the corresponding handler. @zh 传递到解析方法的额外参数。
* @param onComplete @en The callback invoked when finishing parsing. @zh 完成解析的回调。
* @param onComplete.err @en The occurred error, null indicates success. @zh 解析过程中发生的错误,null 表明解析成功。
* @param onComplete.content @en The parsed data. @zh 解析后的数据。
*
* @example
* downloader.download('test.jpg', 'test.jpg', '.jpg', {}, (err, file) => {
@@ -191,7 +227,7 @@ export class Parser {
* });
*
*/
public parse (id: string, file: any, type: string, options: IDownloadParseOptions, onComplete: CompleteCallback): void {
public parse (id: string, file: any, type: string, options: Record<string, any>, onComplete: ((err: Error | null, data?: any | null) => void)): void {
const parsedAsset = parsed.get(id);
if (parsedAsset) {
onComplete(null, parsedAsset);
@@ -224,4 +260,4 @@ export class Parser {
}
}
export default new Parser();
export default Parser.instance;
+56 -53
View File
@@ -23,19 +23,14 @@
*/
import { warnID } from '../../core';
import { CompleteCallbackNoData } from './shared';
import Task from './task';
export type IAsyncPipe = (task: Task, done: CompleteCallbackNoData) => void;
export type ISyncPipe = (task: Task) => Error | void;
export type IPipe = IAsyncPipe | ISyncPipe;
/**
* @en
* Pipeline can execute the task for some effect.
* The loading pipeline can complete the loading task by executing a series of phases. [[AssetManager]] uses it to load all assets.
*
* @zh
* 管线能执行任务达到某个效果
* 加载管线能通过执行一系列阶段来完成加载任务。[[AssetManager]] 使用其来加载所有资源。
*
*/
export class Pipeline {
@@ -43,44 +38,46 @@ export class Pipeline {
/**
* @en
* The id of pipeline
* The unique id of this pipeline.
*
* @zh
* 管线的 id
* 管线的唯一 id。
*
*/
public id: number = Pipeline._pipelineId++;
/**
* @en
* The name of pipeline
* The name of this pipeline.
*
* @zh
* 管线的名字
* 此管线的名称。
*
*/
public name = '';
/**
* @en
* All pipes of pipeline
* All pipes of this pipeline.
*
* @zh
* 所有的管道
* 此管线的所有管道。
*
*/
public pipes: IPipe[] = [];
public pipes: Array<((task: Task, done: ((err?: Error | null) => void)) => void) | ((task: Task) => Error | void)> = [];
/**
* @en
* Create a new pipeline
* Creates a new pipeline.
*
* @zh
* 创建一个管线
* 创建一个管线。
*
* @param name - The name of pipeline
* @param funcs - The array of pipe, every pipe must be function which take two parameters,
* the first is a `Task` flowed in pipeline, the second is complete callback
* @param name - @en The name of pipeline. @zh 管线的名称。
* @param funcs
* @en The array of pipes to create pipeline, every pipe must be function which take two parameters,
* the first is a `Task` flowed in pipeline, the second is complete callback.
* @zh 用于创建管线的管道数组,每个管道必须是一个接受两个参数的方法,第一个参数为任务 [[Task]], 第二个参数为完成回调。
*
* @example
* const pipeline = new Pipeline('download', [
@@ -100,7 +97,7 @@ export class Pipeline {
* ]);
*
*/
constructor (name: string, funcs: IPipe[]) {
constructor (name: string, funcs: Array<((task: Task, done: ((err?: Error | null) => void)) => void) | ((task: Task) => Error | void)>) {
this.name = name;
for (let i = 0, l = funcs.length; i < l; i++) {
this.pipes.push(funcs[i]);
@@ -109,16 +106,18 @@ export class Pipeline {
/**
* @en
* At specific point insert a new pipe to pipeline
* Inserts a new pipe to pipeline at specific point .
*
* @zh
* 在某个特定的点为管线插入一个新的 pipe
* 在某个特定的点为管线插入一个新的 pipe。
*
* @param func - The new pipe
* @param func.task - The task handled with pipeline will be transferred to this function
* @param func.done - Callback you need to invoke manually when this pipe is finished. if the pipeline is synchronous, callback is unnecessary.
* @param index - The specific point you want to insert at.
* @return pipeline
* @param func @en The new pipe to be inserted. @zh 待插入的管道。
* @param func.task @en The task handled with pipeline will be transferred to this function. @zh 正在被此管线处理的任务。
* @param func.done
* @en Callback you need to invoke manually when this pipe is finished. if the pipeline is synchronous, callback is unnecessary.
* @zh 当这个管道完成时,你需要手动调用回调。如果管道是同步的,回调就没有必要。
* @param index @en The specific point you want to insert at. @zh 要插入进的位置。
* @return @en Returns the Pipeline itself, which can be used to make chain calls. @zh 返回 Pipeline 本身,可以用于做链式调用。
*
* @example
* var pipeline = new Pipeline('test', []);
@@ -128,7 +127,7 @@ export class Pipeline {
* }, 0);
*
*/
public insert (func: IPipe, index: number): Pipeline {
public insert (func: ((task: Task, done: ((err?: Error | null) => void)) => void) | ((task: Task) => Error | void), index: number): Pipeline {
if (index > this.pipes.length) {
warnID(4921);
return this;
@@ -140,15 +139,19 @@ export class Pipeline {
/**
* @en
* Append a new pipe to the pipeline
* Appends a new pipe to the pipeline.
*
* @zh
* 添加一个管道到管线中
* 添加一个管道到管线中。
*
* @param func - The new pipe
* @param func.task - The task handled with pipeline will be transferred to this function
* @param func.done - Callback you need to invoke manually when this pipe is finished. if the pipeline is synchronous, callback is unnecessary.
* @return pipeline
* @param func @en The new pipe to be appended. @zh 要追加的新管道。
* @param func.task
* @en The task handled with pipeline will be transferred to this function.
* @zh 正在被此管线处理的任务。
* @param func.done
* @en Callback you need to invoke manually when this pipe is finished. if the pipeline is synchronous, callback is unnecessary.
* @zh 当这个管道完成时,你需要手动调用回调。如果管道是同步的,回调就没有必要。
* @return @en Returns the Pipeline itself, which can be used to make chain calls. @zh 返回 Pipeline 本身,可以用于做链式调用。
*
* @example
* var pipeline = new Pipeline('test', []);
@@ -158,20 +161,20 @@ export class Pipeline {
* });
*
*/
public append (func: IPipe): Pipeline {
public append (func: ((task: Task, done: ((err?: Error | null) => void)) => void) | ((task: Task) => Error | void)): Pipeline {
this.pipes.push(func);
return this;
}
/**
* @en
* Remove pipe which at specific point
* Removes pipe which at specific point.
*
* @zh
* 移除特定位置的管道
* 移除特定位置的管道。
*
* @param index - The specific point
* @return pipeline
* @param index @en The specific point. @zh 指定位置的索引。
* @return @en Returns the Pipeline itself, which can be used to make chain calls. @zh 返回 Pipeline 本身,可以用于做链式调用。
*
* @example
* var pipeline = new Pipeline('test', (task, done) => {
@@ -188,13 +191,13 @@ export class Pipeline {
/**
* @en
* Execute task synchronously
* Executes task synchronously.
*
* @zh
* 同步执行任务
* 同步执行任务。
*
* @param task - The task will be executed
* @returns result
* @param task @en The task will be executed. @zh 要执行的任务。
* @returns @en The execution result. @zh 执行结果。
*
* @example
* var pipeline = new Pipeline('sync', [(task) => {
@@ -209,12 +212,12 @@ export class Pipeline {
public sync (task: Task): any {
const pipes = this.pipes;
if (pipes.length === 0) { return null; }
task.isFinish = false;
task.isFinished = false;
for (let i = 0, l = pipes.length; i < l;) {
const pipe = pipes[i] as ISyncPipe;
const pipe = pipes[i] as ((task: Task) => Error | void);
const result = pipe(task);
if (result) {
task.isFinish = true;
task.isFinished = true;
return result;
}
i++;
@@ -223,18 +226,18 @@ export class Pipeline {
task.output = null;
}
}
task.isFinish = true;
task.isFinished = true;
return task.output as unknown;
}
/**
* @en
* Execute task asynchronously
* Executes task asynchronously.
*
* @zh
* 异步执行任务
* 异步执行任务。
*
* @param task - The task will be executed
* @param task @en The task will be executed. @zh 待执行的任务。
*
* @example
* var pipeline = new Pipeline('sync', [(task, done) => {
@@ -249,7 +252,7 @@ export class Pipeline {
public async (task: Task): void {
const pipes = this.pipes;
if (pipes.length === 0) { return; }
task.isFinish = false;
task.isFinished = false;
this._flow(0, task);
}
@@ -257,7 +260,7 @@ export class Pipeline {
const pipe = this.pipes[index];
pipe(task, (result) => {
if (result) {
task.isFinish = true;
task.isFinished = true;
task.dispatch('complete', result);
} else {
index++;
@@ -267,7 +270,7 @@ export class Pipeline {
task.output = null;
this._flow(index, task);
} else {
task.isFinish = true;
task.isFinished = true;
task.dispatch('complete', result, task.output);
}
}
+2 -2
View File
@@ -22,10 +22,10 @@
THE SOFTWARE.
*/
import { CompleteCallbackNoData, RequestType, transformPipeline } from './shared';
import { RequestType, transformPipeline } from './shared';
import Task from './task';
export default function preprocess (task: Task, done: CompleteCallbackNoData) {
export default function preprocess (task: Task, done: ((err?: Error | null) => void)) {
const options = task.options;
const subOptions = Object.create(null);
const leftOptions = Object.create(null);
+34 -25
View File
@@ -26,19 +26,19 @@ import Config, { IAssetInfo } from './config';
/**
* @en
* A collection of information about a request
* A collection of information about a request.
*
* @zh
* 请求的相关信息集合
* 请求的相关信息集合。
*
*/
export default class RequestItem {
/**
* @en
* The id of request, combined from uuid and isNative
* The id of request, combined from uuid and isNative.
*
* @zh
* 请求的 id, 由 uuid 和 isNative 组合而成
* 请求的 id, 由 uuid 和 isNative 组合而成。
*/
get id (): string {
if (!this._id) {
@@ -47,16 +47,19 @@ export default class RequestItem {
return this._id;
}
/**
* @engineInternal
*/
public static MAX_DEAD_NUM = 500;
/**
* @en
* Create a new request item from pool
* Create a new request item from pool.
*
* @zh
* 从对象池中创建 requestItem
* 从对象池中创建 requestItem。
*
* @returns requestItem
* @returns @en return a newly created RequestItem. @zh 返回一个刚创建的 `RequestItem`。
*
*/
public static create (): RequestItem {
@@ -74,84 +77,90 @@ export default class RequestItem {
/**
* @en
* The uuid of request
* The uuid of request.
*
* @zh
* 请求资源的uuid
* 所请求资源的 uuid。
*
*/
public uuid = '';
/**
* @engineInternal only used for L10N asset replacement.
*/
public overrideUuid = '';
/**
* @en
* The final url of request
* The final url of request.
*
* @zh
* 请求的最终url
* 请求的最终 url。
*
*/
public url = '';
/**
* @en
* The extension name of asset
* The extension name of asset.
*
* @zh
* 资源的扩展名
* 资源的扩展名。
*
*/
public ext = '.json';
/**
* @en
* The content of asset
* The content of asset.
*
* @zh
* 资源的内容
* 资源的内容。
*
*/
public content: any = null;
/**
* @en
* The file of asset
* The file of asset.
*
* @zh
* 资源的文件
* 资源的文件。
*
*/
public file: any = null;
/**
* @en
* The information of asset
* The information of asset.
*
* @zh
* 资源的相关信息
* 资源的相关信息。
*
*/
public info: IAssetInfo | null = null;
/**
* @engineInternal
*/
public config: Config | null = null;
/**
* @en
* Whether or not it is native asset
* Whether or not it is native asset.
*
* @zh
* 资源是否是原生资源
* 资源是否是原生资源。
*
*/
public isNative = false;
/**
* @en
* Custom options
* Custom options.
*
* @zh
* 自定义参数
* 自定义参数。
*
*/
public options: Record<string, any> = Object.create(null);
@@ -160,10 +169,10 @@ export default class RequestItem {
/**
* @en
* Recycle this for reuse
* Recycle this to be reused.
*
* @zh
* 回收 requestItem 用于复用
* 回收 requestItem 用于复用。
*
*/
public recycle (): void {
+8 -62
View File
@@ -27,70 +27,8 @@ import { Asset } from '../assets/asset';
import Bundle from './bundle';
import Cache from './cache';
import { Pipeline } from './pipeline';
import RequestItem from './request-item';
import WeakCache from './weak-cache';
export type CompleteCallback<T = any> = (err: Error | null, data?: T | null) => void;
export type CompleteCallbackNoData = (err?: Error | null) => void;
export type CompleteCallbackWithData<T = any> = (err: Error | null, data: T) => void;
export type ProgressCallback = (finished: number, total: number, item: RequestItem) => void;
export type Request = string | string[] | IRequest | Array<IRequest>;
export interface IRequest extends IOptions {
uuid?: string;
url?: string;
path?: string;
dir?: string;
scene?: string;
}
export interface IOptions extends IBundleOptions, IRemoteOptions {
type?: typeof Asset;
bundle?: string;
}
export interface IRemoteOptions extends IAssetOptions {
ext?: string;
}
export interface IXHROptions extends Record<string, any> {
xhrResponseType?: XMLHttpRequestResponseType;
xhrWithCredentials?: boolean;
xhrTimeout?: number;
xhrHeader?: Record<string, string>;
xhrMimeType?: string;
}
export interface IAssetOptions extends INativeAssetOptions {
reloadAsset?: boolean;
cacheAsset?: boolean;
}
export interface IJsonAssetOptions extends IAssetOptions {
assetId?: string;
}
export interface IDownloadParseOptions extends IXHROptions {
priority?: number;
audioLoadMode?: number;
onFileProgress?: (loaded: number, total: number) => void;
maxConcurrency?: number;
maxRequestsPerFrame?: number;
maxRetryCount?: number;
cacheEnabled?: boolean;
}
export interface IBundleOptions extends INativeAssetOptions {
version?: string;
scriptAsyncLoading?: boolean;
}
export interface INativeAssetOptions extends IDownloadParseOptions {
preset?: string;
}
export type AssetType<T = Asset> = Constructor<T>;
export const assets = EDITOR ? new WeakCache<Asset>() : new Cache<Asset>();
export const files = new Cache();
export const parsed = new Cache();
@@ -114,6 +52,14 @@ export enum RequestType {
SCENE = 'scene',
}
export interface IRequest extends Record<string, any> {
uuid?: string;
url?: string;
path?: string;
dir?: string;
scene?: string;
}
export const presets: Record<string, Record<string, any>> = {
default: {
+112 -79
View File
@@ -22,13 +22,10 @@
THE SOFTWARE.
*/
export type TaskCompleteCallback = (err: Error | null | undefined, data: any) => void;
export type TaskProgressCallback = (...args: any[]) => void;
export type TaskErrorCallback = (...args: any[]) => void;
export interface ITaskOption {
onComplete?: TaskCompleteCallback | null;
onProgress?: TaskProgressCallback | null;
onError?: TaskErrorCallback | null;
onComplete?: ((err: Error | null | undefined, data: any) => void) | null;
onProgress?: ((...args: any[]) => void) | null;
onError?: ((...args: any[]) => void) | null;
input: any;
progress?: any;
options?: Record<string, any> | null;
@@ -36,32 +33,40 @@ export interface ITaskOption {
/**
* @en
* Task is used to run in the pipeline for some effect
* Tasks are the smallest unit of data running in the pipeline, You can create a task and pass in the input information,
* and then get the output of that task after it has been executed in the pipeline to use.
*
* @zh
* 任务用于在管线中运行以达成某种效果
* 任务是在管线中运行的最小数据单位,你可以创建一个任务并传入输入信息,在经过管线执行后获取该任务的输出来使用。
*
*/
export default class Task {
/**
* @engineInternal
*/
public static MAX_DEAD_NUM = 500;
/**
* @en
* Create a new task from pool
* Create a new task from pool.
*
* @zh
* 从对象池中创建 task
* 从对象池中创建 task。
*
* @static
* @method create
* @param options - Some optional paramters
* @param options.onComplete - Callback when the task complete, if the pipeline is synchronous, onComplete is unnecessary.
* @param options.onProgress - Continuously callback when the task is runing, if the pipeline is synchronous, onProgress is unnecessary.
* @param options.onError - Callback when something goes wrong, if the pipeline is synchronous, onError is unnecessary.
* @param options.input - Something will be handled with pipeline
* @param options.progress - Progress information, you may need to assign it manually when multiple pipeline share one progress
* @param options.options - Custom parameters
* @returns task
* @param options @en Some optional parameters. @zh 一些可选参数。
* @param options.onComplete
* @en Callback when the task complete, if the pipeline is synchronous, onComplete is unnecessary.
* @zh 任务完成后的回调,如果流水线是同步的,onComplete 是不必要的。
* @param options.onProgress
* @en Continuously callback when the task is running, if the pipeline is synchronous, onProgress is unnecessary.
* @zh 在任务运行时持续回调,如果管道是同步的,onProgress 是不必要的。
* @param options.onError
* @en Callback when something goes wrong, if the pipeline is synchronous, onError is unnecessary.
* @zh 出错时的回调,如果流水线是同步的,onError 是不必要的。
* @param options.input @en Something will be handled with pipeline. @zh 需要被此管道处理的任务数据。
* @param options.progress @en Progress information. @zh 进度信息。
* @param options.options @en Custom parameters. @zh 自定义参数。
* @returns @en return a newly created task. @zh 返回一个新创建的任务。
*
*/
public static create (options: ITaskOption): Task {
@@ -81,117 +86,138 @@ export default class Task {
/**
* @en
* The id of task
* The id of task.
*
* @zh
* 任务id
* 任务 id。
*
*/
public id: number = Task._taskId++;
/**
* @en
* The callback when task is completed
* The callback when task is completed.
*
* @zh
* 完成回调
* 完成回调。
*
*/
public onComplete: TaskCompleteCallback | null = null;
public onComplete: ((err: Error | null | undefined, data: any) => void) | null = null;
/**
* @en
* The callback of progression
* The callback of progression.
*
* @zh
* 进度回调
* 进度回调。
*
*/
public onProgress: TaskProgressCallback | null = null;
public onProgress: ((...args: any[]) => void) | null = null;
/**
* @en
* The callback when something goes wrong
* The callback when something goes wrong.
*
* @zh
* 错误回调
* 错误回调。
*
*/
public onError: TaskErrorCallback | null = null;
public onError: ((...args: any[]) => void) | null = null;
/**
* @en
* The source of task
* The source data of task.
*
* @zh
* 任务的源
* 任务的源数据。
*
*/
public source: any = null;
/**
* @en
* The output of task
* The output of task.
*
* @zh
* 任务的输出
* 任务的输出。
*/
public output: any = null;
/**
* @en
* The input of task
* The input of task.
*
* @zh
* 任务的输入
* 任务的输入。
*
*/
public input: any = null;
/**
* @en
* The progression of task
* The progression of task.
*
* @zh
* 任务的进度
* 任务的进度。
*
*/
public progress: any = null;
/**
* @en
* Custom options
* Custom options.
*
* @zh
* 自定义参数
* 自定义参数。
*
*/
public options: Record<string, any> | null = null;
/**
* @en
* Whether or not this task is completed
*
* @zh
* 此任务是否已经完成
*
* @deprecated Typo. Since v3.7, please use [[Task.isFinished]] instead.
*/
public isFinish = true;
public get isFinish () {
return this.isFinished;
}
/**
* @deprecated Typo. Since v3.7, please use [[Task.isFinished]] instead.
*/
public set isFinish (val: boolean) {
this.isFinished = val;
}
/**
* @en
* Create a new Task
* Whether or not this task is completed.
*
* @zh
* 创建一个任务
* 此任务是否已经完成。
*
* @param options - Some optional paramters
* @param options.onComplete - Callback when the task is completed, if the pipeline is synchronous, onComplete is unnecessary.
* @param options.onProgress - Continuously callback when the task is runing, if the pipeline is synchronous, onProgress is unnecessary.
* @param options.onError - Callback when something goes wrong, if the pipeline is synchronous, onError is unnecessary.
* @param options.input - Something will be handled with pipeline
* @param options.progress - Progress information, you may need to assign it manually when multiple pipeline share one progress
* @param options.options - Custom parameters
*/
public isFinished = true;
/**
* @en
* Create a new Task.
*
* @zh
* 创建一个任务。
*
* @param options @en Some optional parameters. @zh 一些可选参数。
* @param options.onComplete
* @en Callback when the task complete, if the pipeline is synchronous, onComplete is unnecessary.
* @zh 任务完成后的回调,如果流水线是同步的,onComplete 是不必要的。
* @param options.onProgress
* @en Continuously callback when the task is running, if the pipeline is synchronous, onProgress is unnecessary.
* @zh 在任务运行时持续回调,如果管道是同步的,onProgress 是不必要的。
* @param options.onError
* @en Callback when something goes wrong, if the pipeline is synchronous, onError is unnecessary.
* @zh 出错时的回调,如果流水线是同步的,onError 是不必要的。
* @param options.input @en Something will be handled with pipeline. @zh 需要被此管道处理的任务数据。
* @param options.progress @en Progress information. @zh 进度信息。
* @param options.options @en Custom parameters. @zh 自定义参数。
* @returns @en return a newly created task. @zh 返回一个新创建的任务。
*/
public constructor (options?: ITaskOption) {
this.set(options);
@@ -199,21 +225,28 @@ export default class Task {
/**
* @en
* Set parameters of this task
* Set parameters of this task.
*
* @zh
* 设置任务的参数
* 设置任务的参数。
*
* @param options - Some optional parameters
* @param options.onComplete - Callback when the task is completed, if the pipeline is synchronous, onComplete is unnecessary.
* @param options.onProgress - Continuously callback when the task is running, if the pipeline is synchronous, onProgress is unnecessary.
* @param options.onError - Callback when something goes wrong, if the pipeline is synchronous, onError is unnecessary.
* @param options.input - Something will be handled with pipeline
* @param options.progress - Progress information, you may need to assign it manually when multiple pipeline share one progress
* @param options.options - Custom parameters
* @param options @en Some optional parameters. @zh 一些可选参数。
* @param options.onComplete
* @en Callback when the task complete, if the pipeline is synchronous, onComplete is unnecessary.
* @zh 任务完成后的回调,如果流水线是同步的,onComplete 是不必要的。
* @param options.onProgress
* @en Continuously callback when the task is running, if the pipeline is synchronous, onProgress is unnecessary.
* @zh 在任务运行时持续回调,如果管道是同步的,onProgress 是不必要的。
* @param options.onError
* @en Callback when something goes wrong, if the pipeline is synchronous, onError is unnecessary.
* @zh 出错时的回调,如果流水线是同步的,onError 是不必要的。
* @param options.input @en Something will be handled with pipeline. @zh 需要被此管道处理的任务数据。
* @param options.progress @en Progress information. @zh 进度信息。
* @param options.options @en Custom parameters. @zh 自定义参数。
* @returns @en return a newly created task. @zh 返回一个新创建的任务。
*
* @example
* var task = new Task();
* const task = new Task();
* task.set({input: ['test'], onComplete: (err, result) => console.log(err), onProgress: (finish, total) => console.log(finish / total)});
*
*/
@@ -230,21 +263,21 @@ export default class Task {
/**
* @en
* Dispatch event
* Dispatch event with any parameter.
*
* @zh
* 发布事件
* 分发事件,可以传递任意参数。
*
* @param event - The event name
* @param param1 - Parameter 1
* @param param2 - Parameter 2
* @param param3 - Parameter 3
* @param param4 - Parameter 4
* @param event @en The event name. @zh 事件名称。
* @param param1 @en The parameter 1. @zh 参数 1。
* @param param2 @en The parameter 2. @zh 参数 2。
* @param param3 @en The parameter 3. @zh 参数 3。
* @param param4 @en The parameter 4. @zh 参数 4。
*
* @example
* var task = Task.create();
* Task.onComplete = (msg) => console.log(msg);
* Task.dispatch('complete', 'hello world');
* const task = Task.create();
* task.onComplete = (msg) => console.log(msg);
* task.dispatch('complete', 'hello world');
*
*/
public dispatch (event: string, param1?: any, param2?: any, param3?: any, param4?: any): void {
@@ -276,10 +309,10 @@ export default class Task {
/**
* @en
* Recycle this for reuse
* Recycle this task to be reused.
*
* @zh
* 回收 task 用于复用
* 回收 task 用于复用。
*
*/
public recycle (): void {
+17 -17
View File
@@ -30,16 +30,16 @@ import { dependMap, nativeDependMap } from './depend-maps';
import dependUtil from './depend-util';
import { isScene } from './helper';
import RequestItem from './request-item';
import { assets, AssetType, CompleteCallbackNoData, CompleteCallback, IOptions, ProgressCallback, references } from './shared';
import { assets, references } from './shared';
import Task from './task';
let defaultProgressCallback: ProgressCallback | null = null;
let defaultProgressCallback: ((finished: number, total: number, item: RequestItem) => void) | null = null;
declare class WeakRef {
constructor (obj: any);
}
export function setDefaultProgressCallback (onProgress: ProgressCallback) {
export function setDefaultProgressCallback (onProgress: (finished: number, total: number, item: RequestItem) => void) {
defaultProgressCallback = onProgress;
}
@@ -67,9 +67,9 @@ export function urlAppendTimestamp (url: string, append: boolean): string {
return url;
}
export type RetryFunction = (times: number, done: CompleteCallback) => void;
export type RetryFunction = (times: number, done: ((err: Error | null, data?: any | null) => void)) => void;
export function retry (process: RetryFunction, times: number, wait: number, onComplete: CompleteCallback, index = 0) {
export function retry (process: RetryFunction, times: number, wait: number, onComplete: ((err: Error | null, data?: any | null) => void), index = 0) {
process(index, (err, result) => {
index++;
if (!err || index > times) {
@@ -182,7 +182,7 @@ export function gatherAsset (task: Task) {
}
}
type ForEachFunction<T> = (item: T, done: CompleteCallbackNoData) => void;
type ForEachFunction<T> = (item: T, done: ((err?: Error | null) => void)) => void;
export function forEach<T = any> (array: T[], process: ForEachFunction<T>, onComplete: (errs: Error[]) => void) {
let count = 0;
@@ -208,20 +208,20 @@ export function forEach<T = any> (array: T[], process: ForEachFunction<T>, onCom
}
interface IParameters<T> {
options: IOptions;
onProgress: ProgressCallback | null;
options: Record<string, any>;
onProgress: ((finished: number, total: number, item: RequestItem) => void) | null;
onComplete: T | null;
}
interface ILoadResArgs<T> {
type: AssetType | null;
onProgress: ProgressCallback | null;
type: Constructor<Asset> | null;
onProgress: ((finished: number, total: number, item: RequestItem) => void) | null;
onComplete: T | null;
}
export function parseParameters<T extends (...args) => void> (
options: IOptions | ProgressCallback | T | null | undefined,
onProgress: ProgressCallback | T | null | undefined,
options: Record<string, any> | ((finished: number, total: number, item: RequestItem) => void) | T | null | undefined,
onProgress: ((finished: number, total: number, item: RequestItem) => void) | T | null | undefined,
onComplete: T | null | undefined): IParameters<T> {
let optionsOut: any = options;
let onProgressOut: any = onProgress;
@@ -239,7 +239,7 @@ export function parseParameters<T extends (...args) => void> (
onProgressOut = null;
}
if (onProgress !== undefined && isCallback) {
onProgressOut = options as ProgressCallback;
onProgressOut = options as ((finished: number, total: number, item: RequestItem) => void);
optionsOut = null;
}
}
@@ -248,14 +248,14 @@ export function parseParameters<T extends (...args) => void> (
}
export function parseLoadResArgs<T extends (...args) => void> (
type: AssetType | ProgressCallback | T | null | undefined,
onProgress: ProgressCallback | T | null | undefined,
type: Constructor<Asset> | ((finished: number, total: number, item: RequestItem) => void) | T | null | undefined,
onProgress: ((finished: number, total: number, item: RequestItem) => void) | T | null | undefined,
onComplete: T | null | undefined): ILoadResArgs<T> {
let typeOut: any = type;
let onProgressOut: any = onProgress;
let onCompleteOut: any = onComplete;
if (onComplete === undefined) {
const isValidType = js.isChildClassOf(type as AssetType, Asset);
const isValidType = js.isChildClassOf(type as Constructor<Asset>, Asset);
if (onProgress) {
onCompleteOut = onProgress as T;
if (isValidType) {
@@ -267,7 +267,7 @@ export function parseLoadResArgs<T extends (...args) => void> (
typeOut = null;
}
if (onProgress !== undefined && !isValidType) {
onProgressOut = type as ProgressCallback;
onProgressOut = type as ((finished: number, total: number, item: RequestItem) => void);
typeOut = null;
}
}
+89 -16
View File
@@ -76,12 +76,24 @@ export class Asset extends Eventify(CCObject) {
public loaded = true;
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
* @en
* The UUID of this asset.
*
* @zh
* 资源的 UUID。
*
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future, please use [[Asset.uuid]] instead.
*/
public declare _uuid: string;
/**
* @internal
* @en
* Indicates whether this asset is a default asset.
*
* @zh
* 表明此资源是否是默认资源。
*
* @deprecated Since v3.7, this is an internal engine interface and you should not call this interface under any circumstances.
*/
public declare isDefault: boolean;
@@ -96,8 +108,14 @@ export class Asset extends Eventify(CCObject) {
*/
@serializable
public _native = '';
/**
* @internal
* @en
* Path to native dependency.
* @zh
* 原生依赖的路径。
*
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
*/
public _nativeUrl = '';
@@ -106,9 +124,9 @@ export class Asset extends Eventify(CCObject) {
/**
* @en
* Returns the url of this asset's native object, if none it will returns an empty string.
* Returns the url of this asset's native object, will return an empty string if this asset does not have any native dependency.
* @zh
* 返回该资源对应的目标平台资源的 URL,如果没有将返回一个空字符串。
* 返回该资源对应的目标平台资源的 URL,如果此资源没有原生依赖将返回一个空字符串。
* @readOnly
*/
get nativeUrl () {
@@ -131,6 +149,17 @@ export class Asset extends Eventify(CCObject) {
return this._nativeUrl;
}
/**
* @en
* The UUID of this asset.
*
* @zh
* 资源的 UUID。
*/
get uuid () {
return this._uuid;
}
/**
* @en
* The underlying native asset of this asset if one is available.<br>
@@ -188,7 +217,7 @@ export class Asset extends Eventify(CCObject) {
* 否则,返回空字符串。<br>
* 子类可能会覆盖此方法。
* @method toString
* @return {String}
* @returns @en String representation of this asset. @zh 此资源的字符串表示。
*/
public toString () {
return this.nativeUrl;
@@ -199,7 +228,7 @@ export class Asset extends Eventify(CCObject) {
* 返回一个序列化后的对象
*
* @method serialize
* @return {String}
* @returns {String}
* @private
*/
public serialize () { }
@@ -234,7 +263,15 @@ export class Asset extends Eventify(CCObject) {
public createNode? (callback: CreateNodeCallback): void;
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
* @en
* Get native dependency information.
*
* @zh
* 获取原生依赖信息。
*
* @returns @en The native dependency information. @zh 原生依赖信息。
*
* @deprecated Since v3.7, this is an internal engine interface and you should not call this interface under any circumstances.
*/
public get _nativeDep () {
if (this._native) {
@@ -245,10 +282,10 @@ export class Asset extends Eventify(CCObject) {
/**
* @en
* The number of reference
* Current reference count to this asset.
*
* @zh
* 引用的数量
* 当前该资源被引用的数量。
*/
public get refCount (): number {
return this._ref;
@@ -256,12 +293,13 @@ export class Asset extends Eventify(CCObject) {
/**
* @en
* Add references of asset
* Increase the reference count. This will prevent assets from being automatically recycled.
* When you no longer need to hold the asset, you need to using [[decRef]] to decrease the refCount.
*
* @zh
* 增加资源的引用
* 增加资源的引用。这将阻止资源被自动释放。当你不再需要持有该资源时,你需要调用 [[decRef]] 来减少引用计数。
*
* @return itself
* @returns @en The asset itself. @zh 此资源本身。
*
*/
public addRef (): Asset {
@@ -271,12 +309,12 @@ export class Asset extends Eventify(CCObject) {
/**
* @en
* Reduce references of asset and it will be auto released when refCount equals 0.
* Decrease the reference count and it will be auto released when refCount equals 0.
*
* @zh
* 减少资源的引用并尝试进行自动释放。
* 减少资源的引用,如果引用数量为 0,则将自动释放该资源。
*
* @return itself
* @return @en The asset itself. @zh 此资源本身。
*
*/
public decRef (autoRelease = true): Asset {
@@ -289,17 +327,52 @@ export class Asset extends Eventify(CCObject) {
return this;
}
/**
* @en
* A callback after the asset is loaded that you can use to initialize the asset's internal data.
*
* @zh
* 资源加载后的回调,你可以用于初始化资源的内部数据。
*
* @deprecated Since v3.7, this is an internal engine interface and you should not call this interface under any circumstances.
*/
public onLoaded () {}
/**
* @en
* Initializes default asset.
*
* @zh
* 初始化为默认资源。
*
* @deprecated Since v3.7, this is an internal engine interface and you should not call this interface under any circumstances.
*/
public initDefault (uuid?: string) {
if (uuid) { this._uuid = uuid; }
this.isDefault = true;
}
/**
* @en
* Used to verify this asset is an available asset.
*
* @zh
* 用于验证此资源是否为可用资源。
*
* @returns @zh 是否是可用资源。@en Whether this asset is available or not.
* @deprecated Since v3.7, this is an internal engine interface and you should not call this interface under any circumstances.
*/
public validate (): boolean {
return true;
}
/**
* @en
* Destroy this asset and its internal data.
*
* @zh
* 销毁此资源以及其内部数据。
*/
public destroy () {
debug(getError(12101, this._uuid));
return super.destroy();
+7
View File
@@ -26,6 +26,13 @@ import { ccclass, override } from 'cc.decorator';
import { assertIsNonNullable, cclegacy } from '../../core';
import { Asset } from './asset';
/**
* @en
* `BufferAsset` is a kind of assets whose internal data is a section of memory buffer
* that you can access through the [[BufferAsset.buffer]] function.
* @zh
* `BufferAsset` 是一类资产,其内部数据是一段内存缓冲,你可以通过 [[BufferAsset.buffer]] 函数获取其内部数据。
*/
@ccclass('cc.BufferAsset')
export class BufferAsset extends Asset {
private _buffer: ArrayBuffer | null = null;
+33 -5
View File
@@ -211,8 +211,10 @@ const legacyBuiltinEffectNames = [
@ccclass('cc.EffectAsset')
export class EffectAsset extends Asset {
/**
* @en Register the effect asset to the static map
* @en Register the effect asset to the static map.
* @zh 将指定 effect 注册到全局管理器。
*
* @param asset @en The effect asset to be registered. @zh 待注册的 effect asset。
*/
public static register (asset: EffectAsset) {
EffectAsset._effects[asset.name] = asset;
@@ -222,6 +224,8 @@ export class EffectAsset extends Asset {
/**
* @en Unregister the effect asset from the static map
* @zh 将指定 effect 从全局管理器移除。
*
* @param asset - @en The effect asset to be removed. @zh 待移除的 effect asset。
*/
public static remove (asset: EffectAsset | string) {
if (typeof asset !== 'string') {
@@ -240,8 +244,11 @@ export class EffectAsset extends Asset {
}
/**
* @en Get the effect asset by the given name.
* @en Gets the effect asset by the given name.
* @zh 获取指定名字的 effect 资源。
*
* @param name - @en The name of effect you want to get. @zh 想要获取的 effect 的名字。
* @returns @en The effect. @zh 你查询的 effect.
*/
public static get (name: string) {
if (EffectAsset._effects[name]) { return EffectAsset._effects[name]; }
@@ -257,14 +264,28 @@ export class EffectAsset extends Asset {
}
/**
* @en Get all registered effect assets.
* @en Gets all registered effect assets.
* @zh 获取所有已注册的 effect 资源。
* @returns @en All registered effects. @zh 所有已注册的 effect 资源。
*/
public static getAll () { return EffectAsset._effects; }
/**
* @engineInternal
*/
protected static _effects: Record<string, EffectAsset> = {};
/**
* @engineInternal
*/
public static isLayoutValid (): boolean { return EffectAsset._layoutValid; }
/**
* @engineInternal
*/
public static setLayoutValid (): void { EffectAsset._layoutValid = true; }
/**
* @engineInternal
*/
protected static _layoutValid = true;
/**
@@ -291,13 +312,17 @@ export class EffectAsset extends Asset {
@editable
public combinations: EffectAsset.IPreCompileInfo[] = [];
/**
* @en Whether to hide in editor mode.
* @zh 是否在编辑器内隐藏。
*/
@serializable
@editorOnly
public hideInEditor = false;
/**
* @en The loaded callback which should be invoked by the [[CCLoader]], will automatically register the effect.
* @zh 通过 [[CCLoader]] 加载完成时的回调,将自动注册 effect 资源。
* @en The loaded callback which should be invoked by the [[AssetManager]], will automatically register the effect.
* @zh 通过 [[AssetManager]] 加载完成时的回调,将自动注册 effect 资源。
*/
public onLoaded () {
if (cclegacy.rendering && cclegacy.rendering.enableEffectImport) {
@@ -310,6 +335,9 @@ export class EffectAsset extends Asset {
if (!EDITOR || cclegacy.GAME_VIEW) { cclegacy.game.once(cclegacy.Game.EVENT_RENDERER_INITED, this._precompile, this); }
}
/**
* @engineInternal
*/
protected _precompile () {
if (cclegacy.rendering && cclegacy.rendering.enableEffectImport) {
(cclegacy.rendering.programLib as ProgramLibrary).precompileEffect(deviceManager.gfxDevice, this);
+34 -34
View File
@@ -175,8 +175,8 @@ function isNativeImage (imageSource: ImageSource): imageSource is (HTMLImageElem
}
/**
* @en Image Asset.
* @zh 图像资源。
* @en Image Asset. The image resource stores the raw data of the image and you can use this resource to create any Texture resource.
* @zh 图像资源。图像资源存储了图像的原始数据,你可以使用此资源来创建任意 [[TextureBase]] 资源。
*/
@ccclass('cc.ImageAsset')
export class ImageAsset extends Asset {
@@ -202,8 +202,8 @@ export class ImageAsset extends Asset {
* * * *
* ****************************** *
* *************************************
* @param files @zh 压缩纹理数组 @en Compressed Texture Arrays
* @returns out @zh 合并后的压缩纹理数据 @en Merged compressed texture data
* @param files @zh 压缩纹理数组。 @en Compressed Texture Arrays.
* @returns out @zh 合并后的压缩纹理数据。 @en Merged compressed texture data.
*/
public static mergeCompressedTextureMips (files: ArrayBuffer[] | ArrayBufferView[]) {
let out = new Uint8Array(0);
@@ -253,8 +253,8 @@ export class ImageAsset extends Asset {
}
/**
* @param file 解析压缩纹理
* @param type 压缩纹理类型
* @param file 解析压缩纹理。
* @param type 压缩纹理类型。
* @engineInternal
*/
public static parseCompressedTextures (file: ArrayBuffer | ArrayBufferView, type: number) {
@@ -296,13 +296,13 @@ export class ImageAsset extends Asset {
}
/**
* @zh 解析压缩纹理
* @param file @zh ccon 文件
* @param levelIndex @zh 当前 mipmap 层级
* @param beginOffset @zh 压缩纹理开始时的偏移
* @param endOffset @zh 压缩纹理结束时的偏移
* @param type @zh 压缩纹理类型
* @param out @zh 压缩纹理输出
* @zh 解析压缩纹理。
* @param file @zh 压缩纹理原始数据。
* @param levelIndex @zh 当前 mipmap 层级。
* @param beginOffset @zh 压缩纹理开始时的偏移。
* @param endOffset @zh 压缩纹理结束时的偏移。
* @param type @zh 压缩纹理类型。
* @param out @zh 压缩纹理输出。
* @engineInternal
*/
public static parseCompressedTexture (file: ArrayBuffer | ArrayBufferView, levelIndex: number,
@@ -323,12 +323,12 @@ export class ImageAsset extends Asset {
}
/**
* @zh 解析 PVR 格式的压缩纹理
* @param file @zh ccon 文件
* @param levelIndex @zh 当前 mipmap 层级
* @param beginOffset @zh 压缩纹理开始时的偏移
* @param endOffset @zh 压缩纹理结束时的偏移
* @param out @zh 压缩纹理输出
* @zh 解析 PVR 格式的压缩纹理。
* @param file @zh 压缩纹理原始数据。
* @param levelIndex @zh 当前 mipmap 层级。
* @param beginOffset @zh 压缩纹理开始时的偏移。
* @param endOffset @zh 压缩纹理结束时的偏移。
* @param out @zh 压缩纹理输出。
* @engineInternal
*/
public static parsePVRTexture (file: ArrayBuffer | ArrayBufferView, levelIndex: number,
@@ -375,12 +375,12 @@ export class ImageAsset extends Asset {
}
/**
* @zh 解析 PKM 格式的压缩纹理
* @param file @zh ccon 文件
* @param levelIndex @zh 当前 mipmap 层级
* @param beginOffset @zh 压缩纹理开始时的偏移
* @param endOffset @zh 压缩纹理结束时的偏移
* @param out @zh 压缩纹理输出
* @zh 解析 PKM 格式的压缩纹理。
* @param file @zh 压缩纹理原始数据。
* @param levelIndex @zh 当前 mipmap 层级。
* @param beginOffset @zh 压缩纹理开始时的偏移。
* @param endOffset @zh 压缩纹理结束时的偏移。
* @param out @zh 压缩纹理输出。
* @engineInternal
*/
public static parsePKMTexture (file: ArrayBuffer | ArrayBufferView, levelIndex: number,
@@ -409,12 +409,12 @@ export class ImageAsset extends Asset {
}
/**
* @zh 解析 ASTC 格式的压缩纹理
* @param file @zh ccon 文件
* @param levelIndex @zh 当前 mipmap 层级
* @param beginOffset @zh 压缩纹理开始时的偏移
* @param endOffset @zh 压缩纹理结束时的偏移
* @param out @zh 压缩纹理输出
* @zh 解析 ASTC 格式的压缩纹理。
* @param file @zh 压缩纹理原始数据。
* @param levelIndex @zh 当前 mipmap 层级。
* @param beginOffset @zh 压缩纹理开始时的偏移。
* @param endOffset @zh 压缩纹理结束时的偏移。
* @param out @zh 压缩纹理输出。
* @engineInternal
*/
public static parseASTCTexture (file: ArrayBuffer | ArrayBufferView, levelIndex: number,
@@ -571,7 +571,7 @@ export class ImageAsset extends Asset {
/**
* @en Reset the source of the image asset.
* @zh 重置此图像资源使用的原始图像源。
* @param data The new source
* @param data @en The new source. @zh 新的图片数据源。
*/
public reset (data: ImageSource) {
if (isImageBitmap(data)) {
@@ -602,7 +602,7 @@ export class ImageAsset extends Asset {
// SERIALIZATION
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
* @engineInternal
*/
// eslint-disable-next-line consistent-return
public _serialize () {
@@ -631,7 +631,7 @@ export class ImageAsset extends Asset {
}
/**
* @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
* @engineInternal
*/
public _deserialize (data: any) {
let fmtStr = '';
+1 -1
View File
@@ -39,7 +39,7 @@ export default class JsonAsset extends Asset {
*/
@serializable
@editable
public json: object | null = null;
public json: Record<string, any> | null = null;
}
cclegacy.JsonAsset = JsonAsset;
+71 -18
View File
@@ -98,23 +98,44 @@ export class Material extends Asset {
return hash;
}
/**
* @engineInternal
*/
@type(EffectAsset)
protected _effectAsset: EffectAsset | null = null;
/**
* @internal
*/
@serializable
protected _techIdx = 0;
/**
* @internal
*/
@serializable
protected _defines: MacroRecord[] = [];
/**
* @internal
*/
@serializable
protected _states: PassOverrides[] = [];
/**
* @internal
*/
@serializable
protected _props: Record<string, MaterialPropertyFull | MaterialPropertyFull[]>[] = [];
/**
* @internal
*/
protected _passes: Pass[] = [];
/**
* @internal
*/
protected _hash = 0;
constructor () {
@@ -162,16 +183,16 @@ export class Material extends Asset {
}
/**
* @en The parent material
* @zh 父材质
* @en The parent material.
* @zh 父材质。
*/
get parent (): Material | null {
return null;
}
/**
* @en The owner render component
* @zh 该材质所归属的渲染组件
* @en The owner render component.
* @zh 该材质所归属的渲染组件。
*/
get owner (): Renderer | null {
return null;
@@ -180,7 +201,7 @@ export class Material extends Asset {
/**
* @en Initialize this material with the given information.
* @zh 根据所给信息初始化这个材质,初始化正常结束后材质即可立即用于渲染。
* @param info Material description info.
* @param info @en Material description info. @zh 材质描述信息
*/
public initialize (info: IMaterialInfo) {
if (this._passes.length) {
@@ -195,6 +216,12 @@ export class Material extends Asset {
this._update();
}
/**
* @en Reset the material with the given information.
* @zh 使用指定的信息重置该材质。
*
* @param info @en Material description info. @zh 材质描述信息。
*/
public reset (info: IMaterialInfo) { // to be consistent with other assets
this.initialize(info);
}
@@ -219,8 +246,8 @@ export class Material extends Asset {
/**
* @en Recompile the shader with the specified macro overrides. Allowed only on material instances.
* @zh 使用指定预处理宏重新编译当前 pass(数组)中的 shader。只允许对材质实例执行。
* @param overrides The shader macro override values.
* @param passIdx The pass to apply to. Will apply to all passes if not specified.
* @param overrides @en The shader macro override values. @zh 宏的覆盖值,用于编译不同 Shader 变体。
* @param passIdx @en The pass to apply to. Will apply to all passes if not specified. @zh 要重编的 pass 索引,如果没有指定,则重编所有 pass。
*/
public recompileShaders (overrides: MacroRecord, passIdx?: number) {
console.warn(`Shaders in material asset '${this.name}' cannot be modified at runtime, please instantiate the material first.`);
@@ -237,8 +264,8 @@ export class Material extends Asset {
}
/**
* @en Callback function after material is loaded in [[CCLoader]]. Initialize the resources automatically.
* @zh 通过 [[CCLoader]] 加载完成时的回调,将自动初始化材质资源。
* @en Callback function after material is loaded in [[AssetManager]]. Initialize the resources automatically.
* @zh 通过 [[AssetManager]] 加载完成时的回调,将自动初始化材质资源。
*/
public onLoaded () {
this._update();
@@ -247,7 +274,7 @@ export class Material extends Asset {
/**
* @en Reset all the uniforms to the default value specified in [[EffectAsset]].
* @zh 重置材质的所有 uniform 参数数据为 [[EffectAsset]] 中的默认初始值。
* @param clearPasses Will the rendering data be cleared too?
* @param clearPasses @en Whether to clear the rendering data too. @zh 是否同时清空渲染数据。
*/
public resetUniforms (clearPasses = true) {
this._props.length = this._passes.length;
@@ -266,9 +293,11 @@ export class Material extends Asset {
* @zh
* 设置材质 uniform 参数的统一入口。<br>
* 注意如果需要每帧更新 uniform,建议使用 [[renderer.Pass.setUniform]] 以获得更好的性能。
* @param name The target uniform name.
* @param val The target value.
* @param passIdx The pass to apply to. Will apply to all passes if not specified.
* @param name @en The target uniform name. @zh 目标 Uniform 名称。
* @param val @en The target value. @zh 需要设置的目标值。
* @param passIdx
* @en The pass to apply to. Will apply to all passes if not specified.
* @zh 设置此属性的 pass 索引,如果没有指定,则会设置此属性到所有 pass 上。
*/
public setProperty (name: string, val: MaterialPropertyFull | MaterialPropertyFull[], passIdx?: number) {
let success = false;
@@ -297,15 +326,18 @@ export class Material extends Asset {
/**
* @en
* Get the specified uniform value for this material.<br>
* Gets the specified uniform value for this material.<br>
* Note that only uniforms set through [[Material.setProperty]] can be acquired here.<br>
* For the complete rendering data, use [[renderer.Pass.getUniform]] instead.
* @zh
* 获取当前材质的指定 uniform 参数的值。<br>
* 注意只有通过 [[Material.setProperty]] 函数设置的参数才能从此函数取出,<br>
* 如需取出完整的渲染数据,请使用 [[renderer.Pass.getUniform]]。
* @param name The property or uniform name.
* @param passIdx The target pass index. If not specified, return the first found value in all passes.
* @param name @en The property or uniform name. @zh 属性或 Uniform 的名称。
* @param passIdx
* @en The target pass index. If not specified, return the first found value in all passes.
* @zh 目标 pass 索引,如果没指定,则返回所有 pass 中第一个找到的值。
* @return @en The acquired material properties. @zh 获取的材质属性。
*/
public getProperty (name: string, passIdx?: number): Readonly<MaterialPropertyFull | MaterialPropertyFull[]> {
if (passIdx === undefined) { // try get property in all possible passes
@@ -326,8 +358,8 @@ export class Material extends Asset {
/**
* @en Copy the target material, with optional overrides.
* @zh 复制目标材质到当前实例,允许提供重载信息。
* @param mat The material to be copied.
* @param overrides The overriding states on top of the original material.
* @param mat @en The material to be copied. @zh 需要拷贝的原始材质。
* @param overrides @en The overriding states on top of the original material. @zh 需要在原始材质上覆盖的状态。
*/
public copy (mat: Material, overrides?: IMaterialInfo) {
this._techIdx = mat._techIdx;
@@ -348,6 +380,9 @@ export class Material extends Asset {
this._update();
}
/**
* @engineInternal
*/
protected _fillInfo (info: IMaterialInfo) {
if (info.technique !== undefined) { this._techIdx = info.technique; }
if (info.effectAsset) {
@@ -359,6 +394,9 @@ export class Material extends Asset {
if (info.states) { this._prepareInfo(info.states, this._states); }
}
/**
* @engineInternal
*/
protected _prepareInfo (patch: Record<string, unknown> | Record<string, unknown>[], cur: Record<string, unknown>[]) {
let patchArray = patch;
if (!Array.isArray(patchArray)) { // fill all the passes if not specified
@@ -370,6 +408,9 @@ export class Material extends Asset {
}
}
/**
* @engineInternal
*/
protected _createPasses () {
const tech = this._effectAsset!.techniques[this._techIdx || 0];
if (!tech) { return []; }
@@ -394,6 +435,9 @@ export class Material extends Asset {
return passes;
}
/**
* @engineInternal
*/
protected _update (keepProps = true) {
if (this._effectAsset) {
this._passes = this._createPasses();
@@ -418,6 +462,9 @@ export class Material extends Asset {
this._hash = Material.getHash(this);
}
/**
* @engineInternal
*/
protected _uploadProperty (pass: Pass, name: string, val: MaterialPropertyFull | MaterialPropertyFull[]) {
const handle = pass.getHandle(name);
if (!handle) { return false; }
@@ -448,6 +495,9 @@ export class Material extends Asset {
return true;
}
/**
* @engineInternal
*/
protected _bindTexture (pass: Pass, handle: number, val: MaterialPropertyFull, index?: number) {
const binding = Pass.getBindingFromHandle(handle);
if (val instanceof Texture) {
@@ -463,6 +513,9 @@ export class Material extends Asset {
}
}
/**
* @engineInternal
*/
protected _doDestroy () {
if (this._passes && this._passes.length) {
for (const pass of this._passes) {
+24 -20
View File
@@ -69,7 +69,7 @@ export class RenderTexture extends TextureBase {
/**
* @en Initialize the render texture. Using IRenderTextureCreateInfo.
* @zh 初始化渲染贴图。设置渲染贴图的名称、尺寸、渲染通道信息。
* @param info @en The create info of render texture @zh 渲染贴图的创建信息
* @param info @en The create info of render texture. @zh 渲染贴图的创建信息。
*/
public initialize (info: IRenderTextureCreateInfo) {
this._name = info.name || '';
@@ -81,7 +81,7 @@ export class RenderTexture extends TextureBase {
/**
* @en Reset the render texture. User may change the name, size or render pass info of the render texture.
* @zh 重新初始化渲染贴图。用户可以更改渲染贴图的名称、尺寸、渲染通道信息。
* @param info @en The create info of render texture @zh 渲染贴图的创建信息
* @param info @en The create info of render texture. @zh 渲染贴图的创建信息。
*/
public reset (info: IRenderTextureCreateInfo) { // to be consistent with other assets
this.initialize(info);
@@ -102,10 +102,10 @@ export class RenderTexture extends TextureBase {
}
/**
* @en Resize the render texture
* @zh 修改渲染贴图的尺寸
* @param width The pixel width, the range is from 1 to 2048
* @param height The pixel height, the range is from 1 to 2048
* @en Resize the render texture.
* @zh 修改渲染贴图的尺寸。
* @param width @en The pixel width to resize to, the range is from 1 to 2048. @zh 需要调整到的像素宽度,范围为 1-2048。
* @param height @en The pixel height to resize to, the range is from 1 to 2048. @zh 需要调整到的像素高度,范围为 1-2048。
*/
public resize (width: number, height: number) {
this._width = Math.floor(clamp(width, 1, 2048));
@@ -139,16 +139,17 @@ export class RenderTexture extends TextureBase {
// To be compatible with material property interface
/**
* @en Gets the related [[gfx.Texture]] resource, it's also the color attachment for the render window
* @zh 获取渲染贴图的 GFX 资源,同时也是渲染窗口所指向的颜色缓冲贴图资源
* @en Gets the related [[gfx.Texture]] resource, it's also the color attachment for the render window.
* @zh 获取渲染贴图的 GFX 资源,同时也是渲染窗口所指向的颜色缓冲贴图资源。
* @return @en The low level gfx texture. @zh 底层的 gfx 贴图。
*/
public getGFXTexture (): Texture | null {
return this._window && this._window.framebuffer.colorTextures[0];
}
/**
* @en Callback function after render texture is loaded in [[CCLoader]]. Initialize the render texture.
* @zh 通过 [[CCLoader]] 加载完成时的回调,初始化渲染贴图。
* @en Callback function after render texture is loaded in [[AssetManager]]. Initialize the render texture.
* @zh 通过 [[AssetManager]] 加载完成时的回调,初始化渲染贴图。
*/
public onLoaded () {
this._initWindow();
@@ -157,7 +158,8 @@ export class RenderTexture extends TextureBase {
/**
* @en Implementation of the render texture initialization.
* @zh 初始化渲染贴图的具体实现。
* @param info @en The create info of render texture @zh 渲染贴图的创建信息
* @param info @en The create info of render texture. @zh 渲染贴图的创建信息。
* @engineInternal
*/
protected _initWindow (info?: IRenderTextureCreateInfo) {
const root = cclegacy.director.root as Root;
@@ -182,8 +184,9 @@ export class RenderTexture extends TextureBase {
/**
* @en Initialize the render texture with uuid. The default size is 1x1.
* @zh 初始化渲染贴图。使用uuid进行初始化,贴图的尺寸为 1x1。
* @param uuid @en asset uuid @zh 资源 uuid
* @zh 初始化渲染贴图。使用 uuid 进行初始化,贴图的尺寸为 1x1。
* @param uuid @en asset uuid. @zh 资源 uuid。
* @deprecated Since v3.7, this is an internal engine interface and you should not call this interface under any circumstances.
*/
public initDefault (uuid?: string) {
super.initDefault(uuid);
@@ -194,20 +197,21 @@ export class RenderTexture extends TextureBase {
/**
* @en Validate the correctness of the render texture.
* @zh 验证渲染贴图的正确性。
* @deprecated Since v3.7, this is an internal engine interface and you should not call this interface under any circumstances.
*/
public validate () {
return this.width >= 1 && this.width <= 2048 && this.height >= 1 && this.height <= 2048;
}
/**
* @en Read pixel buffer from render texture @zh 从 render texture 读取像素数据
* @param x @en The location on x axis @zh 起始位置X轴坐标
* @param y @en The location on y axis @zh 起始位置Y轴坐标
* @param width @en The pixel width @zh 像素宽度
* @param height @en The pixel height @zh 像素高度
* @param buffer @en The buffer to hold pixel data @zh 像素缓存
* @en Read pixel buffer from render texture. @zh 从 render texture 读取像素数据。
* @param x @en The location on x axis. @zh 起始位置X轴坐标。
* @param y @en The location on y axis. @zh 起始位置Y轴坐标。
* @param width @en The pixel width. @zh 像素宽度。
* @param height @en The pixel height. @zh 像素高度。
* @param buffer @en The buffer to hold pixel data. @zh 像素缓存。
*/
public readPixels (x = 0, y = 0, width?: number, height?: number, buffer?: Uint8Array) : Uint8Array | null {
public readPixels (x = 0, y = 0, width?: number, height?: number, buffer?: Uint8Array): Uint8Array | null {
width = width || this.width;
height = height || this.height;
const gfxTexture = this.getGFXTexture();
+32 -32
View File
@@ -37,38 +37,38 @@ import { Mesh } from '../../3d/assets/mesh';
export type IBArray = Uint8Array | Uint16Array | Uint32Array;
/**
* @en The interface of geometric information
* @en The interface of geometric information.
* @zh 几何信息。
*/
export interface IGeometricInfo {
/**
* @en Vertex positions
* @en Vertex positions.
* @zh 顶点位置。
*/
positions: Float32Array;
/**
* @en Indices data
* @en Indices data.
* @zh 索引数据。
*/
indices?: IBArray;
/**
* @en Whether the geometry is treated as double sided
* @en Whether the geometry is treated as double sided.
* @zh 是否将图元按双面对待。
*/
doubleSided?: boolean;
/**
* @en The bounding box
* @en The bounding box.
* @zh 此几何体的轴对齐包围盒。
*/
boundingBox: { max: Vec3 | Readonly<Vec3>; min: Vec3 | Readonly<Vec3> };
}
/**
* @en Flat vertex buffer
* @zh 扁平化顶点缓冲区
* @en Flat vertex buffer.
* @zh 扁平化顶点缓冲区。
*/
export interface IFlatBuffer {
stride: number;
@@ -83,17 +83,17 @@ export interface IFlatBuffer {
export class RenderingSubMesh {
/**
* @en
* mesh object where this sub mesh locates
* mesh object where this sub mesh locates.
* @zh
* 子网格所处的网格模型对象
* 子网格所处的网格模型对象。
*/
public mesh?: Mesh;
/**
* @en
* sub mesh's index in mesh
* sub mesh's index in mesh.
* @zh
* 子网格在网格模型中的索引
* 子网格在网格模型中的索引。
*/
public subMeshIdx?: number;
@@ -125,14 +125,14 @@ export class RenderingSubMesh {
/**
* @en
* sub mesh's constructor
* sub mesh's constructor.
* @zh
* 子网格构造函数
* @param vertexBuffers @en vertex buffers @zh 顶点缓冲区数组
* @param attributes @en vertex attributes @zh 顶点属性数组
* @param primitiveMode @en primitive mode @zh 图元类型
* @param indexBuffer @en index buffer @zh 索引缓冲区
* @param indirectBuffer @en indirect buffer @zh 间接缓冲区
* 子网格构造函数。
* @param vertexBuffers @en vertex buffers. @zh 顶点缓冲区数组。
* @param attributes @en vertex attributes. @zh 顶点属性数组。
* @param primitiveMode @en primitive mode. @zh 图元类型。
* @param indexBuffer @en index buffer. @zh 索引缓冲区。
* @param indirectBuffer @en indirect buffer. @zh 间接缓冲区。
*/
constructor (
vertexBuffers: Buffer[], attributes: Attribute[], primitiveMode: PrimitiveMode,
@@ -149,31 +149,31 @@ export class RenderingSubMesh {
}
/**
* @en All vertex attributes used by the sub mesh
* @en All vertex attributes used by the sub mesh.
* @zh 所有顶点属性。
*/
get attributes () { return this._attributes; }
/**
* @en All vertex buffers used by the sub mesh
* @en All vertex buffers used by the sub mesh.
* @zh 使用的所有顶点缓冲区。
*/
get vertexBuffers () { return this._vertexBuffers; }
/**
* @en Index buffer used by the sub mesh
* @en Index buffer used by the sub mesh.
* @zh 使用的索引缓冲区,若未使用则无需指定。
*/
get indexBuffer () { return this._indexBuffer; }
/**
* @en Indirect buffer used by the sub mesh
* @en Indirect buffer used by the sub mesh.
* @zh 间接绘制缓冲区。
*/
get indirectBuffer () { return this._indirectBuffer; }
/**
* @en Primitive mode used by the sub mesh
* @en Primitive mode used by the sub mesh.
* @zh 图元类型。
*/
get primitiveMode () { return this._primitiveMode; }
@@ -234,8 +234,8 @@ export class RenderingSubMesh {
public invalidateGeometricInfo () { this._geometricInfo = undefined; }
/**
* @en the draw range
* @zh 渲染范围
* @en the draw range.
* @zh 渲染范围。
*/
set drawInfo (info: DrawInfo | null | undefined) {
this._drawInfo = info;
@@ -246,13 +246,13 @@ export class RenderingSubMesh {
}
/**
* @en Flatted vertex buffers
* @en Flatted vertex buffers.
* @zh 扁平化的顶点缓冲区。
*/
get flatBuffers () { return this._flatBuffers; }
/**
* @en generate flatted vertex buffers
* @en generate flatted vertex buffers.
* @zh 生成扁平化的顶点缓冲区。
*/
public genFlatBuffers () {
@@ -292,7 +292,7 @@ export class RenderingSubMesh {
}
/**
* @en The vertex buffer for joint after mapping
* @en The vertex buffer for joint after mapping.
* @zh 骨骼索引按映射表处理后的顶点缓冲。
*/
get jointMappedBuffers () {
@@ -344,14 +344,14 @@ export class RenderingSubMesh {
}
/**
* @en The input assembler info
* @zh 输入汇集器信息
* @en The input assembler info.
* @zh 输入汇集器信息。
*/
get iaInfo () { return this._iaInfo; }
/**
* @en destroy sub mesh
* @zh 销毁子网格
* @en Destroys sub mesh.
* @zh 销毁子网格。
*/
public destroy () {
for (let i = 0; i < this.vertexBuffers.length; i++) {
+55 -11
View File
@@ -59,27 +59,40 @@ function canGenerateMipmap (device: Device, w: number, h: number) {
*/
@ccclass('cc.SimpleTexture')
export class SimpleTexture extends TextureBase {
/**
* @engineInternal
*/
protected _gfxTexture: Texture | null = null;
/**
* @engineInternal
*/
protected _gfxTextureView: Texture | null = null;
private _mipmapLevel = 1;
// Cache these data to reduce JSB invoking.
private _textureWidth = 0;
private _textureHeight = 0;
/**
* @engineInternal
*/
protected _baseLevel = 0;
/**
* @engineInternal
*/
protected _maxLevel = 1000;
/**
* @en The mipmap level of the texture
* @zh 贴图中的 Mipmap 层级数量
* @en The mipmap level of the texture.
* @zh 贴图中的 Mipmap 层级数量。
*/
get mipmapLevel () {
return this._mipmapLevel;
}
/**
* @en The GFX Texture resource
* @en The GFX Texture resource.
* @zh 获取此贴图底层的 GFX 贴图对象。
* @return @en The low level gfx texture. @zh 底层的 GFX 贴图。
*/
public getGFXTexture () {
return this._gfxTextureView;
@@ -103,8 +116,8 @@ export class SimpleTexture extends TextureBase {
* @en Update the given level mipmap image.
* @zh 更新指定层级范围内的 Mipmap。当 Mipmap 数据发生了改变时应调用此方法提交更改。
* 若指定的层级范围超出了实际已有的层级范围,只有覆盖的那些层级范围会被更新。
* @param firstLevel First level to be updated
* @param count Mipmap level count to be updated
* @param firstLevel @en First level to be updated. @zh 更新指定层的 mipmap。
* @param count @en Mipmap level count to be updated。 @zh 指定要更新层的数量。
*/
public updateMipmaps (firstLevel = 0, count?: number) {
@@ -123,9 +136,9 @@ export class SimpleTexture extends TextureBase {
* - 若图像的尺寸与 Mipmap 的尺寸相同,上传后整个 Mipmap 的数据将与图像数据一致;
* - 若图像的尺寸小于指定层级 Mipmap 的尺寸(不管是长或宽),则从贴图左上角开始,图像尺寸范围内的 Mipmap 会被更新;
* - 若图像的尺寸超出了指定层级 Mipmap 的尺寸(不管是长或宽),都将引起错误。
* @param source The source image or image data
* @param level Mipmap level to upload the image to
* @param arrayIndex The array index
* @param source @en The source image or image data. @zh 源图像或图像数据。
* @param level @en Mipmap level to upload the image to. @zh 要上传的 mipmap 层级。
* @param arrayIndex @en The array index. @zh 要上传的数组索引。
*/
public uploadData (source: HTMLCanvasElement | HTMLImageElement | ArrayBufferView | ImageBitmap, level = 0, arrayIndex = 0) {
if (!this._gfxTexture || this._mipmapLevel <= level) {
@@ -159,6 +172,9 @@ export class SimpleTexture extends TextureBase {
}
}
/**
* @engineInternal
*/
protected _assignImage (image: ImageAsset, level: number, arrayIndex?: number) {
const data = image.data;
if (!data) {
@@ -177,10 +193,16 @@ export class SimpleTexture extends TextureBase {
}
}
/**
* @engineInternal
*/
protected _checkTextureLoaded () {
this._textureReady();
}
/**
* @engineInternal
*/
protected _textureReady () {
this.loaded = true;
this.emit('load');
@@ -193,11 +215,16 @@ export class SimpleTexture extends TextureBase {
* @zh
* 设置此贴图的 mipmap 层级
* @param value The mipmap level.
* @engineInternal
*
*/
protected _setMipmapLevel (value: number) {
this._mipmapLevel = value < 1 ? 1 : value;
}
/**
* @engineInternal
*/
protected _setMipRange (baseLevel: number, maxLevel: number) {
this._baseLevel = baseLevel < 1 ? 0 : baseLevel;
this._maxLevel = maxLevel < 1 ? 0 : maxLevel;
@@ -206,8 +233,8 @@ export class SimpleTexture extends TextureBase {
/**
* @en Set mipmap level range for this texture.
* @zh 设置当前贴图的 mipmap 范围。
* @param baseLevel The base mipmap level.
* @param maxLevel The maximum mipmap level.
* @param baseLevel @en The base mipmap level. @zh 最低 mipmap 等级。
* @param maxLevel @en The maximum mipmap level. @zh 最高 mipmap 等级。
*/
public setMipRange (baseLevel: number, maxLevel: number) {
assertID(baseLevel <= maxLevel, 3124);
@@ -229,6 +256,7 @@ export class SimpleTexture extends TextureBase {
* @en This method is override by derived classes to provide GFX texture info.
* @zh 这个方法被派生类重写以提供 GFX 纹理信息。
* @param presumed The presumed GFX texture info.
* @engineInternal
*/
protected _getGfxTextureCreateInfo (presumed: PresumedGFXTextureInfo): TextureInfo | null {
return null;
@@ -238,11 +266,15 @@ export class SimpleTexture extends TextureBase {
* @en This method is overrided by derived classes to provide GFX TextureViewInfo.
* @zh 这个方法被派生类重写以提供 GFX 纹理视图信息。
* @param presumed The presumed GFX TextureViewInfo.
* @engineInternal
*/
protected _getGfxTextureViewCreateInfo (presumed: PresumedGFXTextureViewInfo): TextureViewInfo | null {
return null;
}
/**
* @engineInternal
*/
protected _tryReset () {
this._tryDestroyTextureView();
this._tryDestroyTexture();
@@ -259,12 +291,15 @@ export class SimpleTexture extends TextureBase {
/**
* @en Whether mipmaps are baked convolutional maps.
* @zh mipmaps是否为烘焙出来的卷积图。
* @zh mipmaps 是否为烘焙出来的卷积图。
*/
public isUsingOfflineMipmaps (): boolean {
return false;
}
/**
* @engineInternal
*/
protected _createTexture (device: Device) {
if (this._width === 0 || this._height === 0) { return; }
let flags = TextureFlagBit.NONE;
@@ -291,6 +326,9 @@ export class SimpleTexture extends TextureBase {
this._gfxTexture = texture;
}
/**
* @engineInternal
*/
protected _createTextureView (device: Device): Texture | null {
if (!this._gfxTexture) {
return null;
@@ -309,6 +347,9 @@ export class SimpleTexture extends TextureBase {
return device.createTexture(textureViewCreateInfo);
}
/**
* @engineInternal
*/
protected _tryDestroyTexture () {
if (this._gfxTexture) {
this._gfxTexture.destroy();
@@ -316,6 +357,9 @@ export class SimpleTexture extends TextureBase {
}
}
/**
* @engineInternal
*/
protected _tryDestroyTextureView () {
if (this._gfxTextureView) {
this._gfxTextureView.destroy();
+1 -1
View File
@@ -28,7 +28,7 @@ import { Asset } from './asset';
import { cclegacy } from '../../core';
/**
* @en Class for text file.
* @en The asset for text file.
* @zh 文本资源。
*/
@ccclass('cc.TextAsset')
+21 -12
View File
@@ -34,45 +34,45 @@ import { js, cclegacy } from '../../core';
const compressedImageAsset: ImageAsset[] = [];
/**
* @en The create information for [[Texture2D]]
* @en The create information for [[Texture2D]].
* @zh 用来创建贴图的信息。
*/
export interface ITexture2DCreateInfo {
/**
* @en The pixel width
* @en The pixel width.
* @zh 像素宽度。
*/
width: number;
/**
* @en The pixel height
* @en The pixel height.
* @zh 像素高度。
*/
height: number;
/**
* @en The pixel format
* @en The pixel format.
* @zh 像素格式。
* @default PixelFormat.RGBA8888
*/
format?: PixelFormat;
/**
* @en The mipmap level count
* @en The mipmap level count.
* @zh mipmap 层级。
* @default 1
*/
mipmapLevel?: number;
/**
* @en The selected base mipmap level
* @en The selected base mipmap level.
* @zh 选择使用的最小 mipmap 层级。
* @default 1
*/
baseLevel?: number;
/**
* @en The selected maximum mipmap level
* @en The selected maximum mipmap level.
* @zh 选择使用的最大 mipmap 层级。
* @default 1000
*/
@@ -177,6 +177,9 @@ export class Texture2D extends SimpleTexture {
@type([ImageAsset])
public _mipmaps: ImageAsset[] = [];
/**
* @engineInternal
*/
public initialize () {
this.mipmaps = this._mipmaps;
}
@@ -190,7 +193,7 @@ export class Texture2D extends SimpleTexture {
* After reset, the gfx resource will become invalid, you must use [[uploadData]] explicitly to upload the new mipmaps to GPU resources.
* @zh 将当前贴图重置为指定尺寸、像素格式以及指定 mipmap 层级。重置后,贴图的像素数据将变为未定义。
* mipmap 图像的数据不会自动更新到贴图中,你必须显式调用 [[uploadData]] 来上传贴图数据。
* @param info The create information
* @param info @en The create information. @zh 创建贴图的相关信息。
*/
public reset (info: ITexture2DCreateInfo) {
this._width = info.width;
@@ -251,7 +254,7 @@ export class Texture2D extends SimpleTexture {
/**
* @en If the level 0 mipmap image is a HTML element, then return it, otherwise return null.
* @zh 若此贴图 0 级 Mipmap 的图像资源的实际源存在并为 HTML 元素则返回它,否则返回 `null`。
* @returns HTML element or `null`
* @returns @en HTMLElement or `null`. @zh HTML 元素或者 null。
* @deprecated Please use [[ImageAsset.data]] instead
*/
public getHtmlElementObj () {
@@ -268,9 +271,9 @@ export class Texture2D extends SimpleTexture {
}
/**
* @en Gets the description of the 2d texture
* @en Gets the description of the 2d texture.
* @zh 返回此贴图的描述。
* @returns The description
* @returns @en The description. @zh 贴图的描述信息。
*/
public description () {
const url = this._mipmaps[0] ? this._mipmaps[0].url : '';
@@ -280,7 +283,7 @@ export class Texture2D extends SimpleTexture {
/**
* @en Release used GPU resources.
* @zh 释放占用的 GPU 资源。
* @deprecated please use [[destroy]] instead
* @deprecated please use [[destroy]] instead.
*/
public releaseTexture () {
this.destroy();
@@ -327,6 +330,9 @@ export class Texture2D extends SimpleTexture {
}
}
/**
* @engineInternal
*/
protected _getGfxTextureCreateInfo (presumed: PresumedGFXTextureInfo) {
const texInfo = new TextureInfo(TextureType.TEX2D);
texInfo.width = this._width;
@@ -335,6 +341,9 @@ export class Texture2D extends SimpleTexture {
return texInfo;
}
/**
* @engineInternal
*/
protected _getGfxTextureViewCreateInfo (presumed: PresumedGFXTextureViewInfo) {
const texViewInfo = new TextureViewInfo();
texViewInfo.type = TextureType.TEX2D;
+53 -23
View File
@@ -50,7 +50,7 @@ export class TextureBase extends Asset {
}
/**
* @en Pixel width of the texture
* @en Pixel width of the texture.
* @zh 此贴图的像素宽度。
*/
public get width (): number {
@@ -58,7 +58,7 @@ export class TextureBase extends Asset {
}
/**
* @en Pixel height of the texture
* @en Pixel height of the texture.
* @zh 此贴图的像素高度。
*/
public get height (): number {
@@ -67,47 +67,77 @@ export class TextureBase extends Asset {
/**
* @en The pixel format enum.
* @zh 像素格式枚举类型
* @zh 像素格式枚举类型。
*/
public static PixelFormat = PixelFormat;
/**
* @en The wrap mode enum.
* @zh 环绕模式枚举类型
* @zh 环绕模式枚举类型。
*/
public static WrapMode = WrapMode;
/**
* @en The texture filter mode enum
* @zh 纹理过滤模式枚举类型
* @en The texture filter mode enum.
* @zh 纹理过滤模式枚举类型。
*/
public static Filter = Filter;
/**
* @engineInternal
*/
@serializable
protected _format = PixelFormat.RGBA8888;
/**
* @engineInternal
*/
@serializable
protected _minFilter = Filter.LINEAR;
/**
* @engineInternal
*/
@serializable
protected _magFilter = Filter.LINEAR;
/**
* @engineInternal
*/
@serializable
protected _mipFilter = Filter.NONE;
/**
* @engineInternal
*/
@serializable
protected _wrapS = WrapMode.REPEAT;
/**
* @engineInternal
*/
@serializable
protected _wrapT = WrapMode.REPEAT;
/**
* @engineInternal
*/
@serializable
protected _wrapR = WrapMode.REPEAT;
/**
* @engineInternal
*/
@serializable
protected _anisotropy = 0;
/**
* @engineInternal
*/
protected _width = 1;
/**
* @engineInternal
*/
protected _height = 1;
private _id: string;
@@ -127,27 +157,27 @@ export class TextureBase extends Asset {
}
/**
* @en Gets the id of the texture
* @en Gets the id of the texture.
* @zh 获取标识符。
* @returns The id
* @returns @en The id of this texture. @zh 此贴图的 id。
*/
public getId () {
return this._id;
}
/**
* @en Gets the pixel format
* @en Gets the pixel format.
* @zh 获取像素格式。
* @returns The pixel format
* @returns @en The pixel format. @zh 像素格式。
*/
public getPixelFormat () {
return this._format;
}
/**
* @en Gets the anisotropy
* @en Gets the anisotropy.
* @zh 获取各向异性。
* @returns The anisotropy
* @returns @en The anisotropy. @zh 各项异性值。
*/
public getAnisotropy () {
return this._anisotropy;
@@ -158,9 +188,9 @@ export class TextureBase extends Asset {
* Be noted, if the size of the texture is not power of two, only [[WrapMode.CLAMP_TO_EDGE]] is allowed.
* @zh 设置此贴图的缠绕模式。
* 注意,若贴图尺寸不是 2 的整数幂,缠绕模式仅允许 [[WrapMode.CLAMP_TO_EDGE]]。
* @param wrapS S(U) coordinate wrap mode
* @param wrapT T(V) coordinate wrap mode
* @param wrapR R(W) coordinate wrap mode
* @param wrapS @en S(U) coordinate wrap mode. @zh S(U) 坐标系缠绕模式.
* @param wrapT @en T(V) coordinate wrap mode. @zh T(V) 坐标系缠绕模式.
* @param wrapR @en R(W) coordinate wrap mode. @zh R(W) 坐标系缠绕模式.
*/
public setWrapMode (wrapS: WrapMode, wrapT: WrapMode, wrapR?: WrapMode) {
if (wrapR === undefined) wrapR = wrapS; // wrap modes should be as consistent as possible for performance
@@ -178,10 +208,10 @@ export class TextureBase extends Asset {
}
/**
* @en Sets the texture's filter mode
* @en Sets the texture's filter mode.
* @zh 设置此贴图的过滤算法。
* @param minFilter Filter mode for scale down
* @param magFilter Filter mode for scale up
* @param minFilter @en Filter mode for scale down. @zh 贴图缩小时使用的过滤模式。
* @param magFilter @en Filter mode for scale up. @zh 贴图放大时使用的过滤模式。
*/
public setFilters (minFilter: Filter, magFilter: Filter) {
this._minFilter = minFilter;
@@ -195,9 +225,9 @@ export class TextureBase extends Asset {
}
/**
* @en Sets the texture's mip filter
* @zh 设置此贴图的缩小过滤算法。
* @param mipFilter Filter mode for scale down
* @en Sets the texture's mip filter mode.
* @zh 设置此贴图的多层 mip 过滤算法。
* @param mipFilter @en Filter mode for multiple mip level. @zh 多层 mip 过滤模式。
*/
public setMipFilter (mipFilter: Filter) {
this._mipFilter = mipFilter;
@@ -209,9 +239,9 @@ export class TextureBase extends Asset {
}
/**
* @en Sets the texture's anisotropy
* @en Sets the texture's anisotropy.
* @zh 设置此贴图的各向异性。
* @param anisotropy
* @param anisotropy @en The anisotropy to be set. @zh 待设置的各向异性数值。
*/
public setAnisotropy (anisotropy: number) {
this._anisotropy = anisotropy;
+9 -2
View File
@@ -315,7 +315,7 @@ export class TextureCube extends SimpleTexture {
* After reset, the gfx resource will become invalid, you must use [[uploadData]] explicitly to upload the new mipmaps to GPU resources.
* @zh 将当前贴图重置为指定尺寸、像素格式以及指定 mipmap 层级。重置后,贴图的像素数据将变为未定义。
* mipmap 图像的数据不会自动更新到贴图中,你必须显式调用 [[uploadData]] 来上传贴图数据。
* @param info The create information
* @param info @en The create information. @zh 创建贴图的相关信息。
*/
public reset (info: ITextureCubeCreateInfo) {
this._width = info.width;
@@ -329,6 +329,13 @@ export class TextureCube extends SimpleTexture {
this._tryReset();
}
/**
* @en Updates the given level mipmap image.
* @zh 更新指定层级范围内的 Mipmap。当 Mipmap 数据发生了改变时应调用此方法提交更改。
* 若指定的层级范围超出了实际已有的层级范围,只有覆盖的那些层级范围会被更新。
* @param firstLevel @en First level to be updated. @zh 更新指定层的 mipmap。
* @param count @en Mipmap level count to be updated。 @zh 指定要更新层的数量。
*/
public updateMipmaps (firstLevel = 0, count?: number) {
if (firstLevel >= this._mipmaps.length) {
return;
@@ -348,7 +355,7 @@ export class TextureCube extends SimpleTexture {
}
/**
* @en Destroy this texture, clear all mipmaps and release GPU resources
* @en Destroys this texture, clear all mipmaps and release GPU resources
* @zh 销毁此贴图,清空所有 Mipmap 并释放占用的 GPU 资源。
*/
public destroy () {
+3 -4
View File
@@ -25,11 +25,10 @@
import { AudioPlayer } from 'pal/audio';
import { AudioClip, AudioMeta } from './audio-clip';
import { CompleteCallback, IDownloadParseOptions } from '../asset/asset-manager/shared';
import downloader from '../asset/asset-manager/downloader';
import factory from '../asset/asset-manager/factory';
export function loadAudioPlayer (url: string, options: IDownloadParseOptions, onComplete: CompleteCallback) {
export function loadAudioPlayer (url: string, options: Record<string, any>, onComplete: ((err: Error | null, data?: any | null) => void)) {
AudioPlayer.load(url, {
audioLoadMode: options.audioLoadMode,
}).then((player) => {
@@ -47,8 +46,8 @@ export function loadAudioPlayer (url: string, options: IDownloadParseOptions, on
function createAudioClip (id: string,
data: AudioMeta,
options: IDownloadParseOptions,
onComplete: CompleteCallback<AudioClip>) {
options: Record<string, any>,
onComplete: ((err: Error | null, data?: AudioClip | null) => void)) {
const out = new AudioClip();
out._nativeUrl = id;
out._nativeAsset = data;
+2 -3
View File
@@ -38,7 +38,6 @@ import { Layers, Node } from '../scene-graph';
import { builtinResMgr } from '../asset/asset-manager/builtin-res-mgr';
import { Director, director } from './director';
import { bindingMappingInfo } from '../rendering/define';
import { IBundleOptions } from '../asset/asset-manager/shared';
import { ICustomJointTextureLayout } from '../3d/skeletal-animation/skeletal-animation-utils';
import { IPhysicsConfig } from '../physics/framework/physics-config';
import { effectSettings } from '../core/effect-settings';
@@ -174,7 +173,7 @@ export interface IGameConfig {
* 是否让游戏外框对齐到屏幕上,目前只在 web 平台生效
* @deprecated Since v3.6, Please use ```overrideSettings: { Settings.Category.SCREEN: { 'exactFitScreen': true }}``` to set this.
*/
exactFitScreen: boolean,
exactFitScreen?: boolean,
}
/**
@@ -945,7 +944,7 @@ export class Game extends EventTarget {
const preloadBundles = settings.querySettings<{ bundle: string, version: string }[]>(Settings.Category.ASSETS, 'preloadBundles');
if (!preloadBundles) return Promise.resolve([]);
return Promise.all(preloadBundles.map(({ bundle, version }) => new Promise<void>((resolve, reject) => {
const opts: IBundleOptions = {};
const opts: Record<string, any> = {};
if (version) opts.version = version;
assetManager.loadBundle(bundle, opts, (err) => {
if (err) {
+2 -3
View File
@@ -25,7 +25,6 @@
import downloader from '../asset/asset-manager/downloader';
import factory from '../asset/asset-manager/factory';
import { CompleteCallback, IDownloadParseOptions } from '../asset/asset-manager/shared';
import { log } from '../core/platform/debug';
import { VideoClip } from './assets/video-clip';
import { ccwindow } from '../core/global-exports';
@@ -33,7 +32,7 @@ import { ccwindow } from '../core/global-exports';
const ccdocument = ccwindow.document;
// eslint-disable-next-line consistent-return
export function downloadVideo (url: string, options: IDownloadParseOptions, onComplete: CompleteCallback) {
export function downloadVideo (url: string, options: Record<string, any>, onComplete: (err: Error | null, data?: any | null) => void) {
const video = ccdocument.createElement('video');
const source = ccdocument.createElement('source');
video.appendChild(source);
@@ -57,7 +56,7 @@ export function downloadVideo (url: string, options: IDownloadParseOptions, onCo
req.send();
}
function createVideoClip (id: string, data: HTMLVideoElement, options: IDownloadParseOptions, onComplete: CompleteCallback<VideoClip>) {
function createVideoClip (id: string, data: HTMLVideoElement, options: Record<string, any>, onComplete: (err: Error | null, data?: VideoClip | null) => void) {
const out = new VideoClip();
out._nativeUrl = id;
out._nativeAsset = data;