From e2a04dd7bda3cf44596bd887bf8922f4453958df Mon Sep 17 00:00:00 2001 From: Santy-Wang Date: Tue, 10 Jan 2023 12:00:45 +0800 Subject: [PATCH] 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 --- cocos/2d/utils/font-loader.ts | 9 +- cocos/asset/asset-manager/asset-manager.ts | 418 ++++++++++------- cocos/asset/asset-manager/bundle.ts | 425 ++++++++++-------- cocos/asset/asset-manager/cache-manager.ts | 57 +-- cocos/asset/asset-manager/cache.ts | 165 +++++-- cocos/asset/asset-manager/config.ts | 80 +++- cocos/asset/asset-manager/depend-util.ts | 64 ++- cocos/asset/asset-manager/deprecated.ts | 11 +- .../asset/asset-manager/download-dom-image.ts | 5 +- cocos/asset/asset-manager/download-file.ts | 6 +- cocos/asset/asset-manager/download-script.ts | 5 +- cocos/asset/asset-manager/downloader.ts | 192 ++++---- .../asset-manager/editor-path-replace.ts | 4 +- cocos/asset/asset-manager/factory.ts | 21 +- cocos/asset/asset-manager/fetch.ts | 10 +- cocos/asset/asset-manager/helper.ts | 43 +- cocos/asset/asset-manager/load.ts | 12 +- cocos/asset/asset-manager/pack-manager.ts | 12 +- cocos/asset/asset-manager/parser.ts | 100 +++-- cocos/asset/asset-manager/pipeline.ts | 109 ++--- cocos/asset/asset-manager/preprocess.ts | 4 +- cocos/asset/asset-manager/request-item.ts | 59 +-- cocos/asset/asset-manager/shared.ts | 70 +-- cocos/asset/asset-manager/task.ts | 191 ++++---- cocos/asset/asset-manager/utilities.ts | 34 +- cocos/asset/assets/asset.ts | 105 ++++- cocos/asset/assets/buffer-asset.ts | 7 + cocos/asset/assets/effect-asset.ts | 38 +- cocos/asset/assets/image-asset.ts | 68 +-- cocos/asset/assets/json-asset.ts | 2 +- cocos/asset/assets/material.ts | 89 +++- cocos/asset/assets/render-texture.ts | 44 +- cocos/asset/assets/rendering-sub-mesh.ts | 64 +-- cocos/asset/assets/simple-texture.ts | 66 ++- cocos/asset/assets/text-asset.ts | 2 +- cocos/asset/assets/texture-2d.ts | 33 +- cocos/asset/assets/texture-base.ts | 76 +++- cocos/asset/assets/texture-cube.ts | 11 +- cocos/audio/audio-downloader.ts | 7 +- cocos/game/game.ts | 5 +- cocos/video/video-downloader.ts | 5 +- 41 files changed, 1674 insertions(+), 1054 deletions(-) diff --git a/cocos/2d/utils/font-loader.ts b/cocos/2d/utils/font-loader.ts index 6a1e48f554..579de5d42f 100644 --- a/cocos/2d/utils/font-loader.ts +++ b/cocos/2d/utils/font-loader.ts @@ -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((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, 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) { +function createFont (id: string, data: string, options: Record, onComplete: ((err: Error | null, data?: TTFFont | null) => void)) { const out = new TTFFont(); out._nativeUrl = id; out._nativeAsset = data; diff --git a/cocos/asset/asset-manager/asset-manager.ts b/cocos/asset/asset-manager/asset-manager.ts index fbcd0e121b..758ebc374d 100644 --- a/cocos/asset/asset-manager/asset-manager.ts +++ b/cocos/asset/asset-manager/asset-manager.ts @@ -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; /** * @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 = 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 = 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 (requests: string, onComplete?: CompleteCallbackWithData | null): void; - public loadAny (requests: string[], onComplete?: CompleteCallbackWithData | null): void; - public loadAny (requests: Request, onComplete?: CompleteCallbackWithData | null): void; + public loadAny (requests: string | string[] | IRequest | Array, 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, 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, options: { [key: string]: any, preset?: string } | null, onComplete?: ((err: Error | null, data: any) => void) | null): void; + public loadAny (requests: string, onComplete?: ((err: Error | null, data: T) => void) | null): void; + public loadAny (requests: string[], onComplete?: ((err: Error | null, data: T[]) => void) | null): void; + public loadAny (requests: string | string[] | IRequest | Array, 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, + 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|null): void; - public preloadAny (requests: Request, onProgress: ProgressCallback | null, onComplete: CompleteCallbackWithData | null): void; - public preloadAny (requests: Request, options: IOptions | null, onComplete?: CompleteCallbackWithData | null): void; - public preloadAny (requests: Request, onComplete?: CompleteCallbackWithData | null): void; + requests: string | string[] | IRequest | Array, + 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, 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, options: { [key: string]: any, preset?: string } | null, onComplete?: ((err: Error | null, data: RequestItem[]) => void) | null): void; + public preloadAny (requests: string | string[] | IRequest | Array, onComplete?: ((err: Error | null, data: RequestItem[]) => void) | null): void; public preloadAny ( - requests: Request, - options?: IOptions | ProgressCallback | CompleteCallbackWithData | null, - onProgress?: ProgressCallback | CompleteCallbackWithData | null, - onComplete?: CompleteCallbackWithData | null, + requests: string | string[] | IRequest | Array, + 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 (url: string, options: IRemoteOptions | null, onComplete?: CompleteCallbackWithData | null): void; - public loadRemote (url: string, onComplete?: CompleteCallbackWithData | null): void; - public loadRemote (url: string, options?: IRemoteOptions | CompleteCallbackWithData | null, onComplete?: CompleteCallbackWithData | null) { - const { options: opts, onComplete: onComp } = parseParameters>(options, undefined, onComplete); + public loadRemote (url: string, options: { [k: string]: any, ext?: string } | null, onComplete?: ((err: Error | null, data: T) => void) | null): void; + public loadRemote (url: string, onComplete?: ((err: Error | null, data: T) => void) | null): void; + public loadRemote (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 | null): void; - public loadBundle (nameOrUrl: string, onComplete?: CompleteCallbackWithData | null): void; - public loadBundle (nameOrUrl: string, options?: IBundleOptions | CompleteCallbackWithData | null, onComplete?: CompleteCallbackWithData | null) { - const { options: opts, onComplete: onComp } = parseParameters>(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 ( json: Record, - options: IJsonAssetOptions | null, - onProgress: ProgressCallback | null, - onComplete: CompleteCallbackWithData | null): void; - public loadWithJson (json: Record, onProgress: ProgressCallback | null, onComplete: CompleteCallbackWithData | null): void; - public loadWithJson (json: Record, options: IJsonAssetOptions | null, onComplete?: CompleteCallbackWithData | null): void; - public loadWithJson (json: Record, onComplete?: CompleteCallbackWithData | 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 (json: Record, onProgress: ((finished: number, total: number, item: RequestItem) => void) | null, onComplete: ((err: Error | null, data: T) => void) | null): void; + public loadWithJson (json: Record, options: { [key: string]: any, assetId?: string }, onComplete?: ((err: Error | null, data: T) => void) | null): void; + public loadWithJson (json: Record, onComplete?: ((err: Error | null, data: T) => void) | null): void; public loadWithJson ( json: Record, - options?: IJsonAssetOptions | CompleteCallbackWithData | null, - onProgress?: ProgressCallback | CompleteCallbackWithData | null, - onComplete?: CompleteCallbackWithData | 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>(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; diff --git a/cocos/asset/asset-manager/bundle.ts b/cocos/asset/asset-manager/bundle.ts index 457433ead3..3aa70c1bcd 100644 --- a/cocos/asset/asset-manager/bundle.ts +++ b/cocos/asset/asset-manager/bundle.ts @@ -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 | 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 | 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 ( paths: string, - type: AssetType | null, - onProgress: ProgressCallback | null, - onComplete: CompleteCallbackWithData | null): void; + type: Constructor | null, + onProgress: ((finished: number, total: number, item: RequestItem) => void) | null, + onComplete: ((err: Error | null, data: T) => void) | null): void; public load ( - paths: string[], type: AssetType | null, - onProgress: ProgressCallback | null, - onComplete: CompleteCallbackWithData | null): void; - public load (paths: string, onProgress: ProgressCallback | null, onComplete: CompleteCallbackWithData | null): void; - public load (paths: string[], onProgress: ProgressCallback | null, onComplete: CompleteCallbackWithData | null): void; - public load (paths: string, onComplete?: CompleteCallbackWithData | null): void; - public load (paths: string[], onComplete?: CompleteCallbackWithData | null): void; - public load (paths: string, type: AssetType | null, onComplete?: CompleteCallbackWithData | null): void; - public load (paths: string[], type: AssetType | null, onComplete?: CompleteCallbackWithData | null): void; + paths: string[], type: Constructor | null, + onProgress: ((finished: number, total: number, item: RequestItem) => void) | null, + onComplete: ((err: Error | null, data: T[]) => void) | null): void; + public load (paths: string, onProgress: ((finished: number, total: number, item: RequestItem) => void) | null, onComplete: ((err: Error | null, data: T) => void) | null): void; + public load (paths: string[], onProgress: ((finished: number, total: number, item: RequestItem) => void) | null, onComplete: ((err: Error | null, data: T[]) => void) | null): void; + public load (paths: string, onComplete?: ((err: Error | null, data: T) => void) | null): void; + public load (paths: string[], onComplete?: ((err: Error | null, data: T[]) => void) | null): void; + public load (paths: string, type: Constructor | null, onComplete?: ((err: Error | null, data: T) => void) | null): void; + public load (paths: string[], type: Constructor | null, onComplete?: ((err: Error | null, data: T[]) => void) | null): void; public load ( paths: string|string[], - type?: AssetType | ProgressCallback | CompleteCallbackWithData | null, - onProgress?: ProgressCallback | CompleteCallbackWithData | null, - onComplete?: CompleteCallbackWithData | null, + type?: Constructor | ((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|null): void; - public preload (paths: string|string[], onProgress: ProgressCallback | null, onComplete: CompleteCallbackWithData | null): void; - public preload (paths: string|string[], onComplete?: CompleteCallbackWithData | null): void; - public preload (paths: string|string[], type: AssetType | null, onComplete?: CompleteCallbackWithData | null): void; + public preload (paths: string|string[], type: Constructor|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 | null, onComplete?: ((err: Error | null, data: RequestItem[]) => void) | null): void; public preload ( paths: string|string[], - type?: AssetType | ProgressCallback | CompleteCallbackWithData | null, - onProgress?: ProgressCallback | CompleteCallbackWithData | null, - onComplete?: CompleteCallbackWithData | null, + type?: Constructor | ((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.
+ * Loads all assets under a folder inside the bundle folder.
*
* 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 (dir: string, type: AssetType | null, onProgress: ProgressCallback | null, onComplete: CompleteCallbackWithData | null): void; - public loadDir (dir: string, onProgress: ProgressCallback | null, onComplete: CompleteCallbackWithData | null): void; - public loadDir (dir: string, onComplete?: CompleteCallbackWithData | null): void; - public loadDir (dir: string, type: AssetType | null, onComplete?: CompleteCallbackWithData | null): void; + public loadDir (dir: string, type: Constructor | null, onProgress: ((finished: number, total: number, item: RequestItem) => void) | null, onComplete: ((err: Error | null, data: T[]) => void) | null): void; + public loadDir (dir: string, onProgress: ((finished: number, total: number, item: RequestItem) => void) | null, onComplete: ((err: Error | null, data: T[]) => void) | null): void; + public loadDir (dir: string, onComplete?: ((err: Error | null, data: T[]) => void) | null): void; + public loadDir (dir: string, type: Constructor | null, onComplete?: ((err: Error | null, data: T[]) => void) | null): void; public loadDir ( dir: string, - type?: AssetType | ProgressCallback | CompleteCallbackWithData | null, - onProgress?: ProgressCallback | CompleteCallbackWithData | null, - onComplete?: CompleteCallbackWithData | null, + type?: Constructor | ((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.
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.
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 | null): void; - public preloadDir (dir: string, onProgress: ProgressCallback | null, onComplete: CompleteCallbackWithData | null): void; - public preloadDir (dir: string, onComplete?: CompleteCallbackWithData | null): void; - public preloadDir (dir: string, type: AssetType | null, onComplete?: CompleteCallbackWithData | null): void; + public preloadDir (dir: string, type: Constructor | 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 | null, onComplete?: ((err: Error | null, data: RequestItem[]) => void) | null): void; public preloadDir ( dir: string, - type?: AssetType | ProgressCallback | CompleteCallbackWithData| null, - onProgress?: ProgressCallback | CompleteCallbackWithData| null, - onComplete?: CompleteCallbackWithData| null, + type?: Constructor | ((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 | null): void; - public loadScene (sceneName: string, onProgress: ProgressCallback | null, onComplete: CompleteCallbackWithData | null): void; - public loadScene (sceneName: string, options: IAssetOptions | null, onComplete?: CompleteCallbackWithData | null): void; - public loadScene (sceneName: string, onComplete?: CompleteCallbackWithData | 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 | null, - onProgress?: ProgressCallback | CompleteCallbackWithData | null, - onComplete?: CompleteCallbackWithData | 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>(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(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.
+ * Gets cached asset within this bundle by path and type.
* 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 (path: string, type?: AssetType | null): T | null { + public get (path: string, type?: Constructor | 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 | 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; diff --git a/cocos/asset/asset-manager/cache-manager.ts b/cocos/asset/asset-manager/cache-manager.ts index 78bcc2836f..21e9ef7d93 100644 --- a/cocos/asset/asset-manager/cache-manager.ts +++ b/cocos/asset/asset-manager/cache-manager.ts @@ -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; } diff --git a/cocos/asset/asset-manager/cache.ts b/cocos/asset/asset-manager/cache.ts index cd330011bb..87b3f8d990 100644 --- a/cocos/asset/asset-manager/cache.ts +++ b/cocos/asset/asset-manager/cache.ts @@ -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 { + /** + * @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 implements ICache { @@ -50,12 +141,12 @@ export default class Cache implements ICache { /** * @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) { @@ -70,14 +161,14 @@ export default class Cache implements ICache { /** * @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 implements ICache { /** * @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 implements ICache { /** * @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 implements ICache { /** * @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 implements ICache { /** * @en - * Clear all content + * Clear all content. * * @zh - * 清除所有内容 + * 清除所有内容。 * * @example * var cache = new Cache(); @@ -174,14 +265,14 @@ export default class Cache implements ICache { /** * @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 implements ICache { /** * @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 implements ICache { /** * @en - * The count of cached content + * The count of cached content. * * @zh - * 缓存数量 + * 缓存数量。 * */ get count (): number { @@ -232,10 +323,10 @@ export default class Cache implements ICache { /** * @en - * Destroy this cache + * Destroy this cache. * * @zh - * 销毁这个 cache + * 销毁这个 cache。 * */ public destroy (): void { diff --git a/cocos/asset/asset-manager/config.ts b/cocos/asset/asset-manager/config.ts index 94244aa993..6f76b0c702 100644 --- a/cocos/asset/asset-manager/config.ts +++ b/cocos/asset/asset-manager/config.ts @@ -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; } +/** + * @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; } +/** + * @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 | 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 | null, out?: IAddressableInfo[]): IAddressableInfo[] { path = normalize(path); if (path[path.length - 1] === '/') { path = path.slice(0, -1); diff --git a/cocos/asset/asset-manager/depend-util.ts b/cocos/asset/asset-manager/depend-util.ts index c1006247ef..63aa625634 100644 --- a/cocos/asset/asset-manager/depend-util.ts +++ b/cocos/asset/asset-manager/depend-util.ts @@ -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 = new Cache(); + 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 | 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; diff --git a/cocos/asset/asset-manager/deprecated.ts b/cocos/asset/asset-manager/deprecated.ts index d1edb87def..e05b3e8780 100644 --- a/cocos/asset/asset-manager/deprecated.ts +++ b/cocos/asset/asset-manager/deprecated.ts @@ -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 void>) { + public addDownloadHandlers (extMap: Record 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 void>) { + public addLoadHandlers (extMap: Record 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); }, }; diff --git a/cocos/asset/asset-manager/download-dom-image.ts b/cocos/asset/asset-manager/download-dom-image.ts index cf94dc4507..e671f1ff18 100644 --- a/cocos/asset/asset-manager/download-dom-image.ts +++ b/cocos/asset/asset-manager/download-dom-image.ts @@ -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, + options: Record, + onComplete: ((err: Error | null, data?: HTMLImageElement | null) => void), ): HTMLImageElement { const img = new ccwindow.Image(); diff --git a/cocos/asset/asset-manager/download-file.ts b/cocos/asset/asset-manager/download-file.ts index 884999a4f1..a03fbcc978 100644 --- a/cocos/asset/asset-manager/download-file.ts +++ b/cocos/asset/asset-manager/download-file.ts @@ -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, 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: `; diff --git a/cocos/asset/asset-manager/download-script.ts b/cocos/asset/asset-manager/download-script.ts index ed6a576a54..728f723c62 100644 --- a/cocos/asset/asset-manager/download-script.ts +++ b/cocos/asset/asset-manager/download-script.ts @@ -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, + onComplete: ((err: Error | null, data?: any | null) => void), ): HTMLScriptElement | null { // no need to load script again if (downloaded[url]) { diff --git a/cocos/asset/asset-manager/downloader.ts b/cocos/asset/asset-manager/downloader.ts index b793ccb30e..86ec94b3d0 100644 --- a/cocos/asset/asset-manager/downloader.ts +++ b/cocos/asset/asset-manager/downloader.ts @@ -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, onComplete: ((err: Error | null, data?: any | null) => void)) => void; interface IDownloadRequest { id: string; priority: number; url: string; - options: IDownloadParseOptions; - done: CompleteCallback; + options: Record; + 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, 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, 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>) => { +const downloadJson = (url: string, options: Record, onComplete: ((err: Error | null, data?: Record | 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, 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) => { +const downloadCCON = (url: string, options: Record, 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) => { +const downloadCCONB = (url: string, options: Record, 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, 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, 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 | null = null; - public remoteBundles: string[] = []; + /** + * Remote bundle list. + * @engineInternal + */ + public remoteBundles: ReadonlyArray = []; + /** + * @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(); + 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 = {}, 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): void; - public register (type: string | Record, handler?: DownloadHandler) { + public register (type: string, handler: (url: string, options: Record, onComplete: ((err: Error | null, data?: any | null) => void)) => void): void; + public register (map: Record, onComplete: ((err: Error | null, data?: any | null) => void)) => void>): void; + public register ( + type: string | Record, onComplete: ((err: Error | null, data?: any | null) => void)) => void>, + handler?: (url: string, options: Record, 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, 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; diff --git a/cocos/asset/asset-manager/editor-path-replace.ts b/cocos/asset/asset-manager/editor-path-replace.ts index 3d59343bab..f1fe2b3cf9 100644 --- a/cocos/asset/asset-manager/editor-path-replace.ts +++ b/cocos/asset/asset-manager/editor-path-replace.ts @@ -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++) { diff --git a/cocos/asset/asset-manager/factory.ts b/cocos/asset/asset-manager/factory.ts index 8ba6311fac..5d77950426 100644 --- a/cocos/asset/asset-manager/factory.ts +++ b/cocos/asset/asset-manager/factory.ts @@ -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) => void; +export type CreateHandler = (id: string, data: any, options: Record, onComplete: ((err: Error | null, data?: Asset | Bundle | null) => void)) => void; -function createImageAsset (id: string, data: HTMLImageElement, options: IDownloadParseOptions, onComplete: CompleteCallback) { +function createImageAsset (id: string, data: HTMLImageElement, options: Record, 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, options: IDownloadParseOptions, onComplete: CompleteCallback) { +function createJsonAsset (id: string, data: Record, options: Record, 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) { +function createTextAsset (id: string, data: string, options: Record, 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) { +function createBufferAsset (id: string, data: ArrayBufferView, options: Record, 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) { +function createAsset (id: string, data: any, options: Record, 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) { +function createBundle (id: string, data: IConfigOption, options: Record, 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(); + private _creating = new Cache<((err: Error | null, data?: any | null) => void)[]>(); private _producers: Record = { // Images @@ -147,7 +146,7 @@ export class Factory { } } - public create (id: string, data: any, type: string, options: IRemoteOptions, onComplete: CompleteCallback): void { + public create (id: string, data: any, type: string, options: Record, 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) { diff --git a/cocos/asset/asset-manager/fetch.ts b/cocos/asset/asset-manager/fetch.ts index a6ccddaa69..e325c1947e 100644 --- a/cocos/asset/asset-manager/fetch.ts +++ b/cocos/asset/asset-manager/fetch.ts @@ -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; diff --git a/cocos/asset/asset-manager/helper.ts b/cocos/asset/asset-manager/helper.ts index a9dd6dca57..a12991b2c8 100644 --- a/cocos/asset/asset-manager/helper.ts +++ b/cocos/asset/asset-manager/helper.ts @@ -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 | Array>, options?: Record | null): string | string[] { const subTask = Task.create({ input, options }); const urls: string[] = []; try { diff --git a/cocos/asset/asset-manager/load.ts b/cocos/asset/asset-manager/load.ts index e34806028c..898bcfebe2 100644 --- a/cocos/asset/asset-manager/load.ts +++ b/cocos/asset/asset-manager/load.ts @@ -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; diff --git a/cocos/asset/asset-manager/pack-manager.ts b/cocos/asset/asset-manager/pack-manager.ts index b89dc340bc..cf3676d8d9 100644 --- a/cocos/asset/asset-manager/pack-manager.ts +++ b/cocos/asset/asset-manager/pack-manager.ts @@ -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, 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>): void { + public unpackJson (pack: string[], json: any, options: Record, onComplete: ((err: Error | null, data?: Record | 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, 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 | 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); diff --git a/cocos/asset/asset-manager/parser.ts b/cocos/asset/asset-manager/parser.ts index be212f8429..4982f766cb 100644 --- a/cocos/asset/asset-manager/parser.ts +++ b/cocos/asset/asset-manager/parser.ts @@ -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, 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(); + private _parsing = new Cache<((err: Error | null, data?: any | null) => void)[]>(); private _parsers: Record = { '.png': this.parseImage, @@ -67,7 +67,20 @@ export class Parser { '.cconb': this.parseImport, }; - public parseImage (file: HTMLImageElement | Blob, options: IDownloadParseOptions, onComplete: CompleteCallback) { + 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, 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) { + /** + * @engineInternal + */ + public parsePVRTex (file: ArrayBuffer | ArrayBufferView, options: Record, 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) { + /** + * @engineInternal + */ + public parsePKMTex (file: ArrayBuffer | ArrayBufferView, options: Record, 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) { + /** + * @engineInternal + */ + public parseASTCTex (file: ArrayBuffer | ArrayBufferView, options: Record, 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, 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 | CCON, options: IDownloadParseOptions, onComplete: CompleteCallback) { + /** + * @engineInternal + */ + public parseImport (file: Record | CCON, options: Record, 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): void; - public register (type: string | Record, handler?: ParseHandler) { + public register (type: string, handler: (file: any, options: Record, onComplete: ((err: Error | null, data?: any | null) => void)) => void): void; + public register (map: Record, onComplete: ((err: Error | null, data?: any | null) => void)) => void>): void; + public register ( + type: string | Record, onComplete: ((err: Error | null, data?: any | null) => void)) => void>, + handler?: (file: any, options: Record, 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, 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; diff --git a/cocos/asset/asset-manager/pipeline.ts b/cocos/asset/asset-manager/pipeline.ts index 79022ae73a..78c19f681d 100644 --- a/cocos/asset/asset-manager/pipeline.ts +++ b/cocos/asset/asset-manager/pipeline.ts @@ -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); } } diff --git a/cocos/asset/asset-manager/preprocess.ts b/cocos/asset/asset-manager/preprocess.ts index 003cc6f2e7..b402a10989 100644 --- a/cocos/asset/asset-manager/preprocess.ts +++ b/cocos/asset/asset-manager/preprocess.ts @@ -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); diff --git a/cocos/asset/asset-manager/request-item.ts b/cocos/asset/asset-manager/request-item.ts index a2dee831f1..96595ff872 100644 --- a/cocos/asset/asset-manager/request-item.ts +++ b/cocos/asset/asset-manager/request-item.ts @@ -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 = 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 { diff --git a/cocos/asset/asset-manager/shared.ts b/cocos/asset/asset-manager/shared.ts index 33bc4a13b2..bf32743ca8 100644 --- a/cocos/asset/asset-manager/shared.ts +++ b/cocos/asset/asset-manager/shared.ts @@ -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 = (err: Error | null, data?: T | null) => void; -export type CompleteCallbackNoData = (err?: Error | null) => void; -export type CompleteCallbackWithData = (err: Error | null, data: T) => void; -export type ProgressCallback = (finished: number, total: number, item: RequestItem) => void; -export type Request = string | string[] | IRequest | Array; - -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 { - xhrResponseType?: XMLHttpRequestResponseType; - xhrWithCredentials?: boolean; - xhrTimeout?: number; - xhrHeader?: Record; - 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 = Constructor; - export const assets = EDITOR ? new WeakCache() : new Cache(); export const files = new Cache(); export const parsed = new Cache(); @@ -114,6 +52,14 @@ export enum RequestType { SCENE = 'scene', } +export interface IRequest extends Record { + uuid?: string; + url?: string; + path?: string; + dir?: string; + scene?: string; +} + export const presets: Record> = { default: { diff --git a/cocos/asset/asset-manager/task.ts b/cocos/asset/asset-manager/task.ts index 2fef31571d..8c6032f8dd 100644 --- a/cocos/asset/asset-manager/task.ts +++ b/cocos/asset/asset-manager/task.ts @@ -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 | 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 | 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 { diff --git a/cocos/asset/asset-manager/utilities.ts b/cocos/asset/asset-manager/utilities.ts index 3e6d4f5caf..7fc56dcf6b 100644 --- a/cocos/asset/asset-manager/utilities.ts +++ b/cocos/asset/asset-manager/utilities.ts @@ -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 = (item: T, done: CompleteCallbackNoData) => void; +type ForEachFunction = (item: T, done: ((err?: Error | null) => void)) => void; export function forEach (array: T[], process: ForEachFunction, onComplete: (errs: Error[]) => void) { let count = 0; @@ -208,20 +208,20 @@ export function forEach (array: T[], process: ForEachFunction, onCom } interface IParameters { - options: IOptions; - onProgress: ProgressCallback | null; + options: Record; + onProgress: ((finished: number, total: number, item: RequestItem) => void) | null; onComplete: T | null; } interface ILoadResArgs { - type: AssetType | null; - onProgress: ProgressCallback | null; + type: Constructor | null; + onProgress: ((finished: number, total: number, item: RequestItem) => void) | null; onComplete: T | null; } export function parseParameters void> ( - options: IOptions | ProgressCallback | T | null | undefined, - onProgress: ProgressCallback | T | null | undefined, + options: Record | ((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 { let optionsOut: any = options; let onProgressOut: any = onProgress; @@ -239,7 +239,7 @@ export function parseParameters 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 void> ( } export function parseLoadResArgs void> ( - type: AssetType | ProgressCallback | T | null | undefined, - onProgress: ProgressCallback | T | null | undefined, + type: Constructor | ((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 { 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); if (onProgress) { onCompleteOut = onProgress as T; if (isValidType) { @@ -267,7 +267,7 @@ export function parseLoadResArgs void> ( typeOut = null; } if (onProgress !== undefined && !isValidType) { - onProgressOut = type as ProgressCallback; + onProgressOut = type as ((finished: number, total: number, item: RequestItem) => void); typeOut = null; } } diff --git a/cocos/asset/assets/asset.ts b/cocos/asset/assets/asset.ts index aedaaa6b93..6455de041a 100644 --- a/cocos/asset/assets/asset.ts +++ b/cocos/asset/assets/asset.ts @@ -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.
@@ -188,7 +217,7 @@ export class Asset extends Eventify(CCObject) { * 否则,返回空字符串。
* 子类可能会覆盖此方法。 * @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(); diff --git a/cocos/asset/assets/buffer-asset.ts b/cocos/asset/assets/buffer-asset.ts index a293e8301a..c22ac469ba 100644 --- a/cocos/asset/assets/buffer-asset.ts +++ b/cocos/asset/assets/buffer-asset.ts @@ -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; diff --git a/cocos/asset/assets/effect-asset.ts b/cocos/asset/assets/effect-asset.ts index 018cc78e79..4b58246482 100644 --- a/cocos/asset/assets/effect-asset.ts +++ b/cocos/asset/assets/effect-asset.ts @@ -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 = {}; + /** + * @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); diff --git a/cocos/asset/assets/image-asset.ts b/cocos/asset/assets/image-asset.ts index b1d42e0f1b..866a3987a8 100644 --- a/cocos/asset/assets/image-asset.ts +++ b/cocos/asset/assets/image-asset.ts @@ -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 = ''; diff --git a/cocos/asset/assets/json-asset.ts b/cocos/asset/assets/json-asset.ts index f1be660d7b..2afb8edc08 100644 --- a/cocos/asset/assets/json-asset.ts +++ b/cocos/asset/assets/json-asset.ts @@ -39,7 +39,7 @@ export default class JsonAsset extends Asset { */ @serializable @editable - public json: object | null = null; + public json: Record | null = null; } cclegacy.JsonAsset = JsonAsset; diff --git a/cocos/asset/assets/material.ts b/cocos/asset/assets/material.ts index cc829215c5..ef14680e7a 100644 --- a/cocos/asset/assets/material.ts +++ b/cocos/asset/assets/material.ts @@ -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[] = []; + /** + * @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 参数的统一入口。
* 注意如果需要每帧更新 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.
+ * Gets the specified uniform value for this material.
* Note that only uniforms set through [[Material.setProperty]] can be acquired here.
* For the complete rendering data, use [[renderer.Pass.getUniform]] instead. * @zh * 获取当前材质的指定 uniform 参数的值。
* 注意只有通过 [[Material.setProperty]] 函数设置的参数才能从此函数取出,
* 如需取出完整的渲染数据,请使用 [[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 { 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 | Record[], cur: Record[]) { 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) { diff --git a/cocos/asset/assets/render-texture.ts b/cocos/asset/assets/render-texture.ts index 1761837f37..d18846da0b 100644 --- a/cocos/asset/assets/render-texture.ts +++ b/cocos/asset/assets/render-texture.ts @@ -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(); diff --git a/cocos/asset/assets/rendering-sub-mesh.ts b/cocos/asset/assets/rendering-sub-mesh.ts index 494abe068b..d0aec9626b 100644 --- a/cocos/asset/assets/rendering-sub-mesh.ts +++ b/cocos/asset/assets/rendering-sub-mesh.ts @@ -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; min: Vec3 | Readonly }; } /** - * @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++) { diff --git a/cocos/asset/assets/simple-texture.ts b/cocos/asset/assets/simple-texture.ts index 6fc118a9da..dfef7d0295 100644 --- a/cocos/asset/assets/simple-texture.ts +++ b/cocos/asset/assets/simple-texture.ts @@ -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(); diff --git a/cocos/asset/assets/text-asset.ts b/cocos/asset/assets/text-asset.ts index 0d702f7f20..400e76de8a 100644 --- a/cocos/asset/assets/text-asset.ts +++ b/cocos/asset/assets/text-asset.ts @@ -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') diff --git a/cocos/asset/assets/texture-2d.ts b/cocos/asset/assets/texture-2d.ts index 260deef79e..a908cb023f 100644 --- a/cocos/asset/assets/texture-2d.ts +++ b/cocos/asset/assets/texture-2d.ts @@ -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; diff --git a/cocos/asset/assets/texture-base.ts b/cocos/asset/assets/texture-base.ts index 28e9aaaf91..a474b8d7b4 100644 --- a/cocos/asset/assets/texture-base.ts +++ b/cocos/asset/assets/texture-base.ts @@ -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; diff --git a/cocos/asset/assets/texture-cube.ts b/cocos/asset/assets/texture-cube.ts index 8a8afac52d..3777c8b980 100644 --- a/cocos/asset/assets/texture-cube.ts +++ b/cocos/asset/assets/texture-cube.ts @@ -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 () { diff --git a/cocos/audio/audio-downloader.ts b/cocos/audio/audio-downloader.ts index 88f1c34ada..2ace7a2287 100644 --- a/cocos/audio/audio-downloader.ts +++ b/cocos/audio/audio-downloader.ts @@ -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, 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) { + options: Record, + onComplete: ((err: Error | null, data?: AudioClip | null) => void)) { const out = new AudioClip(); out._nativeUrl = id; out._nativeAsset = data; diff --git a/cocos/game/game.ts b/cocos/game/game.ts index 3a69606cdd..256270cf2b 100644 --- a/cocos/game/game.ts +++ b/cocos/game/game.ts @@ -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((resolve, reject) => { - const opts: IBundleOptions = {}; + const opts: Record = {}; if (version) opts.version = version; assetManager.loadBundle(bundle, opts, (err) => { if (err) { diff --git a/cocos/video/video-downloader.ts b/cocos/video/video-downloader.ts index 25168bfab8..06c5b43e5e 100644 --- a/cocos/video/video-downloader.ts +++ b/cocos/video/video-downloader.ts @@ -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, 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) { +function createVideoClip (id: string, data: HTMLVideoElement, options: Record, onComplete: (err: Error | null, data?: VideoClip | null) => void) { const out = new VideoClip(); out._nativeUrl = id; out._nativeAsset = data;