@cocos/cocos-cli-types 0.0.1-alpha.17.1 → 0.0.1-alpha.17.2

package/index.d.ts

@@ -247,6 +247,8 @@ export declare namespace Assets {
         ICreateMenuInfo,
         IUerDataConfigItem,
         QueryAssetType,
+        FilterPluginOptions,
+        IPluginScriptInfo,
         IAssetMeta,
         IAssetInfo,
         AssetOperationOption,
@@ -338,6 +340,56 @@ export declare namespace Base {
     };
 }
 
+declare interface BaseItem {
+    /**
+     * @zh 在项目设置上显示的模块名称，支持 i18n 格式
+     * @en the module name displayed on the project settings, can be configured in i18n format.
+     */
+    label?: string;
+
+    /**
+     * @zh 模块详细描述，将会显示在模块鼠标上移后的提示，支持 `i18n` 的格式
+     * @en the detailed description of the module, which will be displayed in the tooltip when the mouse is moved over the module, can be configured in i18n format.
+     */
+    description?: string;
+
+    /**
+     * @zh 是否默认包含该模块
+     * @en whether the module is included by default.
+     */
+    default: boolean;
+
+    /**
+     * @zh 标识是否为只读模块，设为 `true` 后用户无法开启或关闭该模块。
+     * @en whether the module is read-only. If set to true, users cannot modify this module.
+     */
+    readonly?: boolean;
+
+    /**
+     * @zh 是否在项目设置上隐藏该模块，设为 `true` 后将不会显示在项目设置中。
+     * @en Whether to hide the module in the project settings. If set to true, it will not be displayed in the project settings.
+     */
+    hidden?: boolean;
+
+    /**
+     * @zh 默认的模块分组归属，对应 `features` 字段同级的 `categories` 中配置的目录。
+     * @en The default module group belongs to, corresponding to the directory configured under the `categories` field at the same level of the `features` field.
+     */
+    category?: string;
+
+    /**
+     * @zh 是否为必选模块，新增模块为必选模块时，旧版本升级后会强制选择此模块，否则不会选择。
+     * @en Whether it is a required module. When adding a new module, the old version will be forced to select this module after the upgrade, otherwise it will not be selected.
+     */
+    required?: boolean;
+
+    /**
+     * @zh 该模块依赖的其他模块，如果依赖了其他模块，则此模块勾选后，依赖模块也会被自动勾选。反过来，依赖的模块被移除勾选，此模块也会被一并移除。
+     * @en The other modules that this module depends on. If the module depends on other modules, the dependent modules will be automatically selected. In addition, if the dependent module is removed, this module will also be removed.
+     */
+    dependencies?: string[];
+}
+
 /** 位图字体资源的 userData */
 declare interface BitmapFontAssetUserData {
     /** 字体配置 */
@@ -348,6 +400,29 @@ declare interface BitmapFontAssetUserData {
     textureUuid: string;
 }
 
+declare interface CategoryDetail extends CategoryInfo {
+    modules: IModules;
+}
+
+declare interface CategoryInfo {
+    label?: string;
+    description?: string;
+    checkable?: boolean;
+    required?: boolean;
+}
+
+declare interface CCEModuleConfig {
+    description: string;
+    main: string;
+    types: string;
+}
+
+declare type CCEModuleMap = {
+    [moduleName: string]: CCEModuleConfig;
+} & {
+    mapLocation: string;
+};
+
 declare function close_2(): Promise<void>;
 
 export declare namespace Configuration {
@@ -445,10 +520,64 @@ declare interface EffectAssetUserData {
 
 export declare namespace Engine {
     export {
-        init_4 as init
+        init_4 as init,
+        getInfo,
+        getConfig,
+        initEngine,
+        EngineInfo,
+        IFlags,
+        MakeRequired,
+        IPhysicsConfig,
+        ICollisionMatrix,
+        IVec3Like,
+        IPhysicsMaterial,
+        ICustomJointTextureLayout,
+        IChunkContent,
+        MacroItem,
+        ISplashBackgroundColor,
+        ISplashSetting,
+        IDesignResolution,
+        IEngineModuleConfig,
+        IEngineConfig,
+        IEngineProjectConfig,
+        IInitEngineInfo,
+        CCEModuleConfig,
+        CCEModuleMap,
+        ModuleRenderConfig,
+        Migration,
+        IModuleItem,
+        Features,
+        BaseItem,
+        IFeatureItem,
+        IFeatureGroup,
+        CategoryInfo,
+        IModules,
+        IDisplayModuleItem,
+        IDisplayModuleCache,
+        CategoryDetail,
+        IModuleConfig,
+        IDefaultConfigKeys,
+        IDefaultConfig,
+        ICroppingConfigDeprecatedFeature,
+        ICroppingConfig
     };
 }
 
+declare interface EngineInfo {
+    typescript: {
+        type: 'builtin' | 'custom'; // 当前使用的引擎类型（内置或自定义)
+        builtin: string, // 内置引擎地址
+        path: string; // 当前使用的 ts 引擎路径
+    },
+    native: {
+        type: 'builtin' | 'custom'; // 当前使用的引擎类型（内置或自定义)
+        builtin: string, // 内置引擎地址
+        path: string; // 当前使用的原生引擎路径
+    },
+    tmpDir: string;
+    version: string;
+}
+
 declare type EventEmitterMethods = Pick<EventEmitter, 'on' | 'off' | 'once' | 'emit'>;
 
 declare interface ExecuteAssetDBScriptMethodOptions {
@@ -457,6 +586,10 @@ declare interface ExecuteAssetDBScriptMethodOptions {
     args?: any[];
 }
 
+declare interface Features {
+    [feature: string]: IModuleItem;
+}
+
 declare interface FileNameCheckConfig {
     // 匹配规则
     regStr: string;
@@ -501,6 +634,14 @@ declare interface FontDefDictionary {
 
 declare function get<T>(key: string, scope?: ConfigurationScope): Promise<T>;
 
+declare function get_2(): Promise<Project_2>;
+
+declare function getConfig(useDefault?: boolean): Promise<IEngineConfig>;
+
+declare function getInfo(): Promise<EngineInfo>;
+
+declare function getInfo_2(): Promise<ProjectInfo>;
+
 /** glTF 动画资源的 userData */
 declare interface GltfAnimationAssetUserData {
     gltfIndex: number;
@@ -819,6 +960,15 @@ declare interface IBaseConfiguration extends EventEmitterMethods {
     save(): Promise<boolean>;
 }
 
+declare interface IChunkContent {
+    skeleton: null | string;
+    clips: string[];
+}
+
+declare interface ICollisionMatrix {
+    [x: string]: number;
+}
+
 /**
  * 配置的格式
  */
@@ -856,6 +1006,86 @@ declare interface ICreateMenuInfo {
     fileNameCheckConfigs?: FileNameCheckConfig[];
 }
 
+declare type ICroppingConfig = {
+    name: string;
+    cache: Record<string, IDisplayModuleCache>,
+    flags: IFlags_2,
+    includeModules: string[],
+    noDeprecatedFeatures: ICroppingConfigDeprecatedFeature;
+    moduleToFallBack?: Record<string, string>;
+}
+
+declare type ICroppingConfigDeprecatedFeature = {
+    value: boolean,
+    version: string
+};
+
+declare interface ICustomJointTextureLayout {
+    textureLength: number;
+    contents: IChunkContent[];
+}
+
+declare type IDefaultConfig = {
+    key: IDefaultConfigKeys;
+    name: string;
+    diyConfig: (cache: Record<string, IDisplayModuleCache>, flags: IFlags_2, includeModules: string[]) => void;
+}
+
+declare type IDefaultConfigKeys = 'defaultConfig' | 'default2d' | 'default3d' | 'defaultNative' | 'defaultSmallGames'
+
+/**
+ * 构建使用的设计分辨率数据
+ */
+declare interface IDesignResolution {
+    height: number;
+    width: number;
+    fitWidth?: boolean;
+    fitHeight?: boolean;
+    policy?: number;
+}
+
+declare interface IDisplayModuleCache {
+    _value: boolean;
+    _option?: string; // 保存下拉选项的值
+    _flags?: IFlags_2; // 保存下拉选项的值的联动开关
+}
+
+declare interface IDisplayModuleItem extends IFeatureItem {
+    _value: boolean;
+    _option?: string;
+    options?: Record<string, IDisplayModuleItem>;
+}
+
+declare interface IEngineConfig extends IEngineModuleConfig {
+    physicsConfig: IPhysicsConfig;
+    macroConfig?: Record<string, string | number | boolean>;
+    sortingLayers: { id: number, name: string, value: number }[];
+    customLayers: { name: string, value: number }[];
+    renderPipeline?: string;
+    // 是否使用自定义管线，如与其他模块配置不匹配将会以当前选项为准
+    customPipeline?: boolean;
+    highQuality: boolean;
+
+    macroCustom: MacroItem[];
+
+    customJointTextureLayouts: ICustomJointTextureLayout[];
+    designResolution: IDesignResolution;
+    splashScreen: ISplashSetting;
+    downloadMaxConcurrency: number;
+}
+
+declare interface IEngineModuleConfig {
+    // ---- 模块配置相关 ----
+    includeModules: string[];
+    flags?: IFlags;
+    noDeprecatedFeatures?: { value: boolean, version: string };
+}
+
+declare interface IEngineProjectConfig extends Exclude<IEngineConfig, 'includeModules' | 'flags' | 'noDeprecatedFeatures'> {
+    configs?: Record<string, IEngineModuleConfig>;
+    globalConfigKey?: string;
+}
+
 declare interface IFbxSetting {
     /**
      * https://github.com/cocos-creator/FBX-glTF-conv/pull/26
@@ -892,6 +1122,59 @@ declare interface IFbxSetting {
     matchMeshNames?: boolean;
 }
 
+declare interface IFeatureGroup extends BaseItem {
+    options: { [feature: string]: IFeatureItem };
+}
+
+declare interface IFeatureItem extends BaseItem {
+    /**
+     * @zh 是否默认以及允许包含在上传的各个小游戏引擎插件内，目前由于部分引擎模块包体较大，默认不会打包在官方的微信引擎分离插件内。（临时方案）
+     * @en Whether it is included in the upload of the various engine plugins by default. Currently, because some engine modules are packaged in a large package, the official WeChat engine separation plugin does not package them by default. (Temporary solution)
+     */
+    enginePlugin?: boolean;
+
+    /**
+     * @zh 限定的使用环境，允许宏的组合条件判断，默认为空支持任意环境，配置后限定为指定环境。如设置为 "$NATIVE || $HTML5" 则仅在 native 和 html5 环境下生效。
+     * @en The restricted usage environment allows for conditional judgments using macro combinations. By default, it supports any environment, but once configured, it is limited to the specified environment. For example, if set to "$NATIVE || $HTML5", it will only take effect in native and HTML5 environments.
+     */
+    envCondition?: string;
+
+    /**
+     * @zh 当环境不符合限定的使用环境时，自动回退的模块名称。仅当 `envCondition` 配置后才有效。
+     * @en The name of the engine feature to automatically fall back to when the environment does not meet the restricted usage conditions. This is only effective when `envCondition` is configured.
+     */
+    fallback?: string;
+
+    /**
+     * @zh 当选择了某个模块时，可以做些附加的配置
+     * @en When a module is selected, additional configurations can be made
+     */
+    flags: { [k: string]: Pick<BaseItem, 'default' | 'label' | 'description'> & { 'ui-type': 'checkbox' | 'select' } }
+
+    /**
+     * @zh 是否为原生模块，这部分模块的编译模式可能是 wasm 也可能是共存或只有 asmjs，为 true 的模块，如果模块勾选构建面板上才会显示原生代码打包模式的配置。
+     * @en Whether it is a native module. This part of the module may be compiled as wasm or asmjs, and the module with this attribute will be displayed in the packaging mode configuration in the build panel if it is selected.
+     */
+    isNativeModule?: boolean;
+
+    /**
+     * @zh 在原生引擎的模块宏配置，如果在原生端有原生实现，在此处补充对应字段，后续根据项目设置的配置情况，会将选择值设置到 `cmake` 配置内。
+     * @en The macro configuration of the native module in the native engine. If there is a native implementation in the native engine, please fill in the corresponding fields here. The value will be set to `cmake` configuration according to the project settings.
+     */
+    cmakeConfig?: string;
+}
+
+declare type IFlags = Record<string, boolean | number>;
+
+declare type IFlags_2 = Record<string, boolean | number>;
+
+declare interface IInitEngineInfo {
+    importBase: string;
+    nativeBase: string;
+    writablePath: string;
+    serverURL?: string;
+}
+
 /** 图片资源的 userData  */
 declare interface ImageAssetUserData {
     /** 图片类型 */
@@ -940,6 +1223,27 @@ declare interface ImageMeta {
     remap?: string;
 }
 
+declare interface IModuleConfig {
+    moduleTreeDump: {
+        default: IModules;
+        categories: Record<string, CategoryDetail>;
+    },
+    nativeCodeModules: string[];
+    moduleCmakeConfig: Record<string, { native?: string; }>;
+    moduleDependMap: Record<string, string[]>;
+    moduleDependedMap: Record<string, string[]>;
+    features: IModules,
+    ignoreModules: string[],
+    envLimitModule: Record<string, {
+        envList: string[];
+        fallback?: string;
+    }>;
+}
+
+declare type IModuleItem = IFeatureItem | IFeatureGroup;
+
+declare type IModules = Record<string, IModuleItem>;
+
 /**
  * Import Asset // 导入资源
  */
@@ -957,10 +1261,111 @@ declare function init_5(projectPath: string): Promise<void>;
 
 declare function init_6(projectPath: string): Promise<void>;
 
+declare function initEngine(enginePath: string, projectPath: string, serverURL?: string): Promise<void>;
+
+declare interface IPhysicsConfig {
+    gravity: IVec3Like; // （0，-10， 0）
+    allowSleep: boolean; // true
+    sleepThreshold: number; // 0.1，最小 0
+    autoSimulation: boolean; // true
+    fixedTimeStep: number; // 1 / 60 ，最小 0
+    maxSubSteps: number; // 1，最小 0
+    defaultMaterial?: string; // 物理材质 uuid
+    useNodeChains: boolean; // true
+    collisionMatrix: ICollisionMatrix;
+    physicsEngine: string;
+    physX?: {
+        notPackPhysXLibs: boolean;
+        multiThread: boolean;
+        subThreadCount: number;
+        epsilon: number;
+    };
+}
+
+declare interface IPhysicsMaterial {
+    friction: number; // 0.5
+    rollingFriction: number; // 0.1
+    spinningFriction: number; // 0.1
+    restitution: number; // 0.1
+}
+
 declare interface IPluginScriptInfo extends PluginScriptInfo {
     url: string;
 }
 
+declare interface IProject {
+    /**
+     * Gets the project directory path
+     *
+     * @returns {string} The project directory path
+     */
+    get path(): string;
+    /**
+     * Gets the project type (2d or 3d)
+     *
+     * @returns {'2d' | '3d'} The project type
+     */
+    get type(): '2d' | '3d';
+    /**
+     * Gets the package.json file path
+     *
+     * @returns {string} The path to package.json file
+     */
+    get pkgPath(): string;
+    /**
+     * Gets the temp directory path
+     *
+     * @returns {string} The path to the temporary directory
+     */
+    get tmpDir(): string;
+    /**
+     * Gets the library directory path
+     *
+     * @returns {string} The path to the library directory
+     */
+    get libraryDir(): string;
+    /**
+     * Opens the project and loads project information
+     *
+     * @returns {Promise<boolean>} Returns true if the project was opened successfully, false otherwise
+     */
+    open(projectPath: string): Promise<boolean>;
+    /**
+     * Closes the project and saves current project information
+     *
+     * @returns {Promise<boolean>} Returns true if the project was closed successfully, false otherwise
+     */
+    close(): Promise<boolean>;
+    /**
+     * Gets the complete project information
+     *
+     * @returns {ProjectInfo} The complete project information object
+     */
+    getInfo(): ProjectInfo;
+    /**
+     * Gets specific project information by key path
+     *
+     * @param {string} key - The key path to access nested properties (e.g., 'creator.version')
+     * @returns {any} The value at the specified key path, or null if not found
+     */
+    getInfo(key: string): any;
+    /**
+     * Gets project information with optional key path
+     *
+     * @param {string} [key] - Optional key path to access nested properties
+     * @returns {ProjectInfo | any} Project information or specific value
+     */
+    getInfo(key?: string): ProjectInfo | any;
+    /**
+     * Updates specific project information by key path or complete info
+     *
+     * @param {string | ProjectInfo} keyOrValue - Either a key path string or complete ProjectInfo object
+     * @param {ProjectInfo} [value] - The value to set when using key path (required if keyOrValue is string)
+     * @returns {Promise<boolean>} Returns true if update was successful, false otherwise
+     */
+    updateInfo<T>(keyOrValue: string | ProjectInfo, value?: T): Promise<boolean>;
+}
+
 declare interface IRedirectInfo {
     // 跳转资源的类型
     type: string;
@@ -968,6 +1373,32 @@ declare interface IRedirectInfo {
     uuid: string;
 }
 
+declare interface ISplashBackgroundColor {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+}
+
+declare interface ISplashSetting {
+    displayRatio: number;
+    totalTime: number;
+    watermarkLocation: 'default' | 'topLeft' | 'topRight' | 'topCenter' | 'bottomLeft' | 'bottomCenter' | 'bottomRight';
+    autoFit: boolean;
+
+    logo?: {
+        type: 'default' | 'none' | 'custom';
+        image?: string;
+        base64?: string;
+    }
+    background?: {
+        type: 'default' | 'color' | 'custom';
+        color?: ISplashBackgroundColor;
+        image?: string;
+        base64?: string;
+    }
+}
+
 declare type ISupportCreateCCType =
 | 'cc.AnimationClip'        // 动画剪辑
 | 'cc.Script'               // 脚本（TypeScript/JavaScript）
@@ -1010,6 +1441,12 @@ declare interface IUerDataConfigItem {
     };
 }
 
+declare interface IVec3Like {
+    x: number;
+    y: number;
+    z: number;
+}
+
 /** glTF 虚拟子资源的通用 userData */
 declare interface IVirtualAssetUserData {
     /** 在 glTF 文件中的索引 */
@@ -1064,6 +1501,13 @@ declare const enum LogLevel {
     DEBUG = 4
 }
 
+declare type MacroItem = {
+    key: string;
+    value: boolean;
+}
+
+declare type MakeRequired<T, K extends keyof T> = T & Required<Pick<T, K>>;
+
 declare interface MeshClusterOptions {
     enable: boolean;
     coneCluster?: boolean;
@@ -1105,6 +1549,32 @@ declare function migrate(): Promise<void>;
 
 declare function migrateFromProject(): Promise<IConfiguration>;
 
+declare interface Migration {
+    version: string;
+    migrate(moduleCache: Record<string, boolean>): Record<string, boolean>;
+}
+
+declare interface ModuleRenderConfig {
+    $schema?: string;
+
+    /**
+     * The modules info
+     */
+    features: Features;
+
+    /**
+     * The categories info
+     */
+    categories: { [category: string]: CategoryInfo };
+
+    version: string;
+
+    /**
+     * The script to migrate, this script should export a const migrations: Migration[]`.
+     */
+    migrationScript?: string;
+}
+
 /**
  * Move Asset // 移动资源
  */
@@ -1306,10 +1776,123 @@ export declare namespace Project {
     export {
         init_5 as init,
         open_2 as open,
-        close_2 as close
+        close_2 as close,
+        getInfo_2 as getInfo,
+        get_2 as get
     };
 }
 
+declare class Project_2 implements IProject {
+    /**
+     * The version of the Project
+     */
+    static readonly version = '4.0.0';
+    private _projectPath;
+    private _type;
+    private _pkgPath;
+    private _tmpDir;
+    private _libraryDir;
+    private _info;
+    get path(): string;
+    get type(): '2d' | '3d';
+    static getPackageJsonPath(projectPath: string): string;
+    get pkgPath(): string;
+    get tmpDir(): string;
+    get libraryDir(): string;
+    static create(projectPath: string, type?: ProjectType): Promise<boolean>;
+    getInfo(): ProjectInfo;
+    getInfo(key: string): any;
+    updateInfo<T>(keyOrValue: string | ProjectInfo, value?: T): Promise<boolean>;
+    open(projectPath: string): Promise<boolean>;
+    close(): Promise<boolean>;
+    /**
+     * Generates project information object
+     *
+     * @param {string} projectPath - The project directory path
+     * @param {ProjectType} type - The project type (2d or 3d)
+     * @returns {ProjectInfo} Generated project information
+     */
+    private static generateProjectInfo;
+    /**
+     * Validates if the project information is valid
+     *
+     * @param {ProjectInfo} info - The project information to validate
+     * @returns {boolean} Returns true if the project info is valid, false otherwise
+     */
+    private isValid;
+}
+
+/**
+ * Project creator information
+ */
+declare interface ProjectCreatorInfo {
+    /**
+     * Version of the tool or engine used to create the project
+     */
+    version: string;
+
+    /**
+     * Dependencies of the project
+     * - key: package name
+     * - value: version number
+     */
+    dependencies?: {
+        [name: string]: string,
+    };
+
+    /**
+     * Registry configuration for package management
+     */
+    registry?: {
+        /**
+         * Remote repository configuration (e.g., npm, private registry)
+         */
+        remote?: {};
+    };
+}
+
+/**
+ * Project information
+ */
+declare interface ProjectInfo {
+    /**
+     * Project name
+     */
+    name: string;
+
+    /**
+     * Project type ('2d' or '3d')
+     */
+    type: ProjectType;
+
+    /**
+     * Project version
+     */
+    version: string;
+
+    /**
+     * Unique identifier (UUID) of the project
+     */
+    uuid: string;
+
+    /**
+     * Information about the creator of the project
+     */
+    creator: ProjectCreatorInfo;
+
+    /**
+     * Other additional properties (flexible extension)
+     */
+    [key: string]: any;
+}
+
+/**
+ * Project type
+ * - '2d': 2D Project
+ * - '3d': 3D Project
+ */
+declare type ProjectType = '2d' | '3d';
+
 /**
  * Query Asset Config Map // 查询资源配置映射表
  */
@@ -1437,7 +2020,10 @@ declare function saveAsset(pathOrUrlOrUUID: string, data: string | Buffer): Prom
 
 export declare namespace Scripting {
     export {
-        init_6 as init
+        init_6 as init,
+        SharedSettings,
+        IPluginScriptInfo,
+        FilterPluginOptions
     };
 }
 
@@ -1457,6 +2043,22 @@ declare interface SerializedAssetFinder {
 
 declare function set<T>(key: string, value: T, scope?: ConfigurationScope): Promise<boolean>;
 
+declare interface SharedSettings {
+    useDefineForClassFields: boolean;
+    allowDeclareFields: boolean;
+    loose: boolean;
+    guessCommonJsExports: boolean;
+    exportsConditions: string[];
+    preserveSymlinks: boolean;
+    importMap?: {
+        json: {
+            imports?: Record<string, string>;
+            scopes?: Record<string, Record<string, string>>;
+        };
+        url: string;
+    };
+}
+
 declare interface SimplifyOptions {
     // 压缩比例
     targetRatio?: number;