[break] feat(scene): add Light Probe and Lightmap baking support

package.json

@@ -184,6 +184,7 @@
         "sharp": "0.32.6",
         "socket.io": "^4.8.1",
         "socket.io-client": "^4.8.1",
+        "socket.io-v2": "npm:socket.io@2.3.0",
         "strip-ansi": "^6.0.1",
         "tga-js": "^1.1.1",
         "tmp": "^0.0.33",

packages/cocos-cli-types/__tests__/__snapshots__/dts-snapshot.test.ts.snap

@@ -6704,8 +6704,8 @@ export declare interface IGizmoService {
     selectAllLightProbes(): void;
     unselectAllLightProbes(): void;
     queryLightProbeSelectedCount(): number;
-    deleteSelectedLightProbes(): number;
-    duplicateSelectedLightProbes(): number;
+    deleteSelectedLightProbes(): Promise<number>;
+    duplicateSelectedLightProbes(): Promise<number>;
     generateLightProbes(): number;
     regionSelectLightProbes(left: number, right: number, top: number, bottom: number, additive: boolean): number;
 }
@@ -6718,6 +6718,132 @@ export declare interface IInsertLODOptions {
 export declare interface IIsPrefabInstanceParams {
     nodePath: string;
 }
+export declare interface ILightFXCancelResult {
+    cancelled: boolean;
+    target: 'light-probe' | 'lightmap' | null;
+}
+export declare interface ILightFXDiagnostics {
+    operationId?: string;
+    version: 1;
+    stage: string;
+    logs: string[];
+    progress?: string;
+    rate?: number;
+}
+export declare interface ILightmapBakeCapabilities {
+    outputDirectory?: true;
+    diagnostics?: ILightFXDiagnostics;
+    version: 1;
+    resultLifecycleVersion: 1;
+    sceneTransactionVersion: 1;
+    assetVersion: 1;
+    assetCleanupVersion?: 1;
+    cancelVersion?: 1;
+    cancellable?: boolean;
+    busy: boolean;
+}
+export declare interface ILightmapBakeInfo {
+    sceneUrl: string;
+    baked: boolean;
+    meshCount: number;
+    terrainCount: number;
+    highp: boolean;
+    stationaryMainLight: boolean;
+    textures: ILightmapTextureInfo[];
+    missingTextureUuids: string[];
+}
+export declare interface ILightmapBakeOptions {
+    outputUrl?: string;
+    msaa?: 1 | 2 | 4 | 8;
+    resolution?: 128 | 256 | 512 | 1024 | 2048;
+    filter?: boolean;
+    highp?: boolean;
+    giScale?: number;
+    giSamples?: number;
+    giPathLength?: 1 | 2 | 3 | 4;
+    aoLevel?: 0 | 1 | 2;
+    aoStrength?: number;
+    aoRadius?: number;
+    aoColor?: [number, number, number, number?];
+    threads?: number;
+    saveScene?: boolean;
+    timeoutMs?: number;
+}
+export declare interface ILightmapBakeResult {
+    diagnostics?: ILightFXDiagnostics;
+    sceneUrl: string;
+    textureUrls: string[];
+    meshCount: number;
+    terrainCount: number;
+    durationMs: number;
+}
+export declare interface ILightmapBakeService extends IServiceEvents {
+    queryCapabilities(): Promise<ILightmapBakeCapabilities>;
+    bake(options: ILightmapBakeOptions): Promise<ILightmapBakeResult>;
+    queryBakeInfo(): Promise<ILightmapBakeInfo>;
+    clearBake(options?: {
+        saveScene?: boolean;
+        deleteAssets?: boolean;
+    }): Promise<ILightmapClearResult>;
+    cancel(): Promise<ILightFXCancelResult>;
+}
+export declare interface ILightmapClearResult {
+    clearedCount: number;
+    deletedAssetCount: number;
+    retainedAssetCount: number;
+    failedAssetCount: number;
+}
+export declare interface ILightmapTextureInfo {
+    uuid: string;
+    url: string;
+    filename: string;
+    size: number;
+    createdAt: number;
+    modifiedAt: number;
+}
+export declare interface ILightProbeBakeCapabilities {
+    diagnostics?: ILightFXDiagnostics;
+    version: 1;
+    cancelVersion?: 1;
+    cancellable?: boolean;
+    resultLifecycleVersion: 1;
+    sceneTransactionVersion: 1;
+    busy: boolean;
+}
+export declare interface ILightProbeBakeOptions {
+    giScale?: number;
+    giSamples?: number;
+    bounces?: number;
+    reduceRinging?: number;
+    showWireframe?: boolean;
+    showConvex?: boolean;
+    lightProbeSphereVolume?: number;
+    saveScene?: boolean;
+    timeoutMs?: number;
+}
+export declare interface ILightProbeBakeResult {
+    diagnostics?: ILightFXDiagnostics;
+    sceneUrl: string;
+    probeCount: number;
+    giScale: number;
+    giSamples: number;
+    bounces: number;
+    reduceRinging: number;
+    showWireframe: boolean;
+    showConvex: boolean;
+    lightProbeSphereVolume: number;
+    durationMs: number;
+}
+export declare interface ILightProbeBakeService extends IServiceEvents {
+    queryCapabilities(): Promise<ILightProbeBakeCapabilities>;
+    bake(options: ILightProbeBakeOptions): Promise<ILightProbeBakeResult>;
+    clearBake(options?: {
+        saveScene?: boolean;
+    }): Promise<{
+        probeCount: number;
+    }>;
+    cancel(): Promise<ILightFXCancelResult>;
+}
 export declare interface ILODGroupBoundsResult {
     localBoundaryCenter: IVec3;
     objectSize: number;
@@ -7332,6 +7458,8 @@ export declare interface IServiceManager {
     UI: IUIService;
     ReflectionProbe: IReflectionProbeService;
     ReferenceImage: IReferenceImageService;
+    LightProbeBake: ILightProbeBakeService;
+    LightmapBake: ILightmapBakeService;
     Particle: IParticleService;
     Terrain: ITerrainService;
 }

src/api/scene/lightfx-bake-schema.ts

@@ -0,0 +1,87 @@
+import { z } from 'zod';
+import { MAX_LIGHTMAP_GI_SAMPLES } from '../../core/scene/common/lightfx-limits';
+
+const SaveAndTimeout = {
+    saveScene: z.boolean().optional().describe('Save the current scene after applying the bake result; defaults to true'),
+    timeoutMs: z.number().int().min(1_000).max(3_600_000).optional().describe('Whole-operation timeout in milliseconds'),
+};
+
+export const SchemaLightProbeBakeOptions = z.object({
+    giScale: z.number().finite().min(0).max(100).optional().describe('GI multiplier; defaults to the current scene value'),
+    giSamples: z.number().int().min(64).max(65535).optional().describe('GI probe sample count; defaults to the current scene value'),
+    bounces: z.number().int().min(1).max(4).optional().describe('Probe ray bounce count; defaults to the current scene value'),
+    reduceRinging: z.number().finite().min(0).max(0.05).optional().describe('Spherical-harmonic ringing reduction; defaults to the current scene value'),
+    showWireframe: z.boolean().optional().describe('Show light-probe connections in the scene view; defaults to the current scene value'),
+    showConvex: z.boolean().optional().describe('Show the light-probe convex hull in the scene view; defaults to the current scene value'),
+    lightProbeSphereVolume: z.number().finite().min(0).max(100).optional().describe('Light-probe sphere display size; defaults to the current scene value'),
+    ...SaveAndTimeout,
+}).describe('Light probe bake options');
+
+export const SchemaLightProbeBakeResult = z.object({
+    sceneUrl: z.string(), probeCount: z.number().int().nonnegative(),
+    giScale: z.number(), giSamples: z.number().int(), bounces: z.number().int(),
+    reduceRinging: z.number(), showWireframe: z.boolean(), showConvex: z.boolean(), lightProbeSphereVolume: z.number(),
+    durationMs: z.number().nonnegative(),
+});
+
+export const SchemaLightmapBakeOptions = z.object({
+    outputUrl: z.string().optional().describe('Existing parent directory under db://assets. Saved results publish into scene-<scene UUID>/output; omitted or db://assets uses db://assets/LightFX as parent. Use returned texture URLs.'),
+    msaa: z.union([z.literal(1), z.literal(2), z.literal(4), z.literal(8)]).optional(),
+    resolution: z.union([z.literal(128), z.literal(256), z.literal(512), z.literal(1024), z.literal(2048)]).optional(),
+    filter: z.boolean().optional(), highp: z.boolean().optional(),
+    giScale: z.number().finite().min(0).max(100).optional(),
+    giSamples: z.number().int().min(1).max(MAX_LIGHTMAP_GI_SAMPLES).optional()
+        .describe('Lightmap GI sampling factor; 1–2590. Large values have quadratic memory and time costs.'),
+    giPathLength: z.union([z.literal(1), z.literal(2), z.literal(3), z.literal(4)]).optional(),
+    aoLevel: z.union([z.literal(0), z.literal(1), z.literal(2)]).optional(),
+    aoStrength: z.number().finite().min(0).optional(),
+    aoRadius: z.number().finite().min(0).optional(),
+    aoColor: z.tuple([z.number().min(0).max(255), z.number().min(0).max(255), z.number().min(0).max(255), z.number().min(0).max(255).optional()]).optional(),
+    threads: z.number().int().min(1).max(256).optional(),
+    ...SaveAndTimeout,
+}).describe('Lightmap bake options');
+
+export const SchemaLightmapBakeResult = z.object({
+    sceneUrl: z.string(), textureUrls: z.array(z.string()), meshCount: z.number().int().nonnegative(),
+    terrainCount: z.number().int().nonnegative(), durationMs: z.number().nonnegative(),
+});
+
+export const SchemaLightmapTextureInfo = z.object({
+    uuid: z.string(),
+    url: z.string(),
+    filename: z.string(),
+    size: z.number().int().nonnegative(),
+    createdAt: z.number().finite().nonnegative(),
+    modifiedAt: z.number().finite().nonnegative(),
+});
+
+export const SchemaLightmapBakeInfo = z.object({
+    sceneUrl: z.string(),
+    baked: z.boolean(),
+    meshCount: z.number().int().nonnegative(),
+    terrainCount: z.number().int().nonnegative(),
+    highp: z.boolean(),
+    stationaryMainLight: z.boolean(),
+    textures: z.array(SchemaLightmapTextureInfo),
+    missingTextureUuids: z.array(z.string()),
+});
+
+export const SchemaLightFXCancelResult = z.object({
+    cancelled: z.boolean(), target: z.enum(['light-probe', 'lightmap']).nullable(),
+});
+
+export const SchemaLightProbeClearOptions = z.object({ saveScene: z.boolean().optional() });
+export const SchemaLightmapClearOptions = z.object({ saveScene: z.boolean().optional(), deleteAssets: z.boolean().optional() });
+export const SchemaClearCountResult = z.object({
+    probeCount: z.number().int().nonnegative().optional(),
+    clearedCount: z.number().int().nonnegative().optional(),
+    deletedAssetCount: z.number().int().nonnegative().optional(),
+    retainedAssetCount: z.number().int().nonnegative().optional(),
+    failedAssetCount: z.number().int().nonnegative().optional(),
+});
+
+export type TLightProbeBakeOptions = z.infer<typeof SchemaLightProbeBakeOptions>;
+export type TLightProbeBakeResult = z.infer<typeof SchemaLightProbeBakeResult>;
+export type TLightmapBakeOptions = z.infer<typeof SchemaLightmapBakeOptions>;
+export type TLightmapBakeResult = z.infer<typeof SchemaLightmapBakeResult>;
+export type TLightmapBakeInfo = z.infer<typeof SchemaLightmapBakeInfo>;

src/api/scene/lightfx-bake.ts

@@ -0,0 +1,72 @@
+import { COMMON_STATUS, CommonResultType } from '../base/schema-base';
+import { description, param, result, title, tool } from '../decorator/decorator';
+import { Scene } from '../../core/scene';
+import {
+    SchemaClearCountResult, SchemaLightFXCancelResult, SchemaLightmapBakeInfo,
+    SchemaLightmapBakeOptions, SchemaLightmapBakeResult,
+    SchemaLightmapClearOptions, SchemaLightProbeBakeOptions, SchemaLightProbeBakeResult, SchemaLightProbeClearOptions,
+    TLightmapBakeInfo, TLightmapBakeOptions, TLightmapBakeResult, TLightProbeBakeOptions, TLightProbeBakeResult,
+} from './lightfx-bake-schema';
+
+async function execute<T>(operation: () => Promise<T>): Promise<CommonResultType<T>> {
+    try { return { code: COMMON_STATUS.SUCCESS, data: await operation() }; }
+    catch (error) { return { code: COMMON_STATUS.FAIL, reason: error instanceof Error ? error.message : String(error) }; }
+}
+
+export class LightFXBakeApi {
+    @tool('scene-bake-light-probes')
+    @title('Bake light probes')
+    @description('Bake all light probes with the effective panel settings and write both settings and spherical-harmonic coefficients back to the current scene.')
+    @result(SchemaLightProbeBakeResult)
+    bakeLightProbes(@param(SchemaLightProbeBakeOptions) options: TLightProbeBakeOptions): Promise<CommonResultType<TLightProbeBakeResult>> {
+        return execute(() => Scene.LightProbeBake.bake(options));
+    }
+
+    @tool('scene-clear-light-probes')
+    @title('Clear baked light probes')
+    @description('Clear spherical-harmonic bake results from all light probes in the current scene.')
+    @result(SchemaClearCountResult)
+    clearLightProbes(@param(SchemaLightProbeClearOptions) options: { saveScene?: boolean }): Promise<CommonResultType<{ probeCount: number }>> {
+        return execute(() => Scene.LightProbeBake.clearBake(options));
+    }
+
+    @tool('scene-bake-lightmap')
+    @title('Bake lightmap')
+    @description('Bake the current scene lightmap with LightFX, import generated textures, bind them to renderers and save the scene.')
+    @result(SchemaLightmapBakeResult)
+    bakeLightmap(@param(SchemaLightmapBakeOptions) options: TLightmapBakeOptions): Promise<CommonResultType<TLightmapBakeResult>> {
+        return execute(() => Scene.LightmapBake.bake(options));
+    }
+
+    @tool('scene-query-lightmap-bake-info')
+    @title('Query lightmap bake information')
+    @description('Query lightmap textures and bake flags currently bound to meshes and terrains in the active scene.')
+    @result(SchemaLightmapBakeInfo)
+    queryLightmapBakeInfo(): Promise<CommonResultType<TLightmapBakeInfo>> {
+        return execute(() => Scene.LightmapBake.queryBakeInfo());
+    }
+
+    @tool('scene-clear-lightmap')
+    @title('Clear baked lightmap')
+    @description('Unbind baked lightmaps and optionally delete unreferenced generated assets. Asset deletion saves the scene and prevents Undo/Redo from restoring pre-Clear baked results; unrelated edit history is preserved.')
+    @result(SchemaClearCountResult)
+    clearLightmap(@param(SchemaLightmapClearOptions) options: { saveScene?: boolean; deleteAssets?: boolean }): Promise<CommonResultType<{
+        clearedCount: number;
+        deletedAssetCount: number;
+        retainedAssetCount: number;
+        failedAssetCount: number;
+    }>> {
+        return execute(() => Scene.LightmapBake.clearBake(options));
+    }
+
+    @tool('scene-cancel-lightfx-bake')
+    @title('Cancel LightFX bake')
+    @description('Cancel the currently running light-probe or lightmap bake.')
+    @result(SchemaLightFXCancelResult)
+    cancel(): Promise<CommonResultType<{ cancelled: boolean; target: 'light-probe' | 'lightmap' | null }>> {
+        return execute(async () => {
+            const probe = await Scene.LightProbeBake.cancel();
+            return probe.cancelled ? probe : Scene.LightmapBake.cancel();
+        });
+    }
+}

src/api/scene/scene.ts

@@ -25,6 +25,7 @@ import { NodeApi } from './node';
 import { PrefabApi } from './prefab';
 import { ReflectionProbeApi } from './reflection-probe';
 import { ReferenceImageApi } from './reference-image';
+import { LightFXBakeApi } from './lightfx-bake';
 import { ParticleApi } from './particle';
 import { options } from '../../core/builder/platforms/android/i18n/en';
 
@@ -34,6 +35,7 @@ export class SceneApi {
     public prefab: PrefabApi;
     public reflectionProbe: ReflectionProbeApi;
     public referenceImage: ReferenceImageApi;
+    public lightFXBake: LightFXBakeApi;
     public particle: ParticleApi;
 
     constructor() {
@@ -42,6 +44,7 @@ export class SceneApi {
         this.prefab = new PrefabApi();
         this.reflectionProbe = new ReflectionProbeApi();
         this.referenceImage = new ReferenceImageApi();
+        this.lightFXBake = new LightFXBakeApi();
         this.particle = new ParticleApi();
     }
 

src/core/assets/manager/filesystem.ts

@@ -143,8 +143,27 @@ export async function moveAssetSource(source: string, target: string, options?:
 
     try {
         if (!Utils.Path.contains(source, target)) {
-            await renamePath(source + '.meta', target + '.meta', { overwrite: true });
-            await renamePath(source, target, renameOptions);
+            const originalMeta = !renameOptions.overwrite ? Buffer.from(await readPath(source + '.meta')) : undefined;
+            await renamePath(source + '.meta', target + '.meta', renameOptions);
+            try {
+                await renamePath(source, target, renameOptions);
+            } catch (error) {
+                // Keep the original UUID when a non-overwriting source move fails.
+                // Propagate failure before Asset DB refresh can generate a replacement meta.
+                if (originalMeta && existsSync(source)) {
+                    try {
+                        // A competing destination PNG does not own our metadata. Restore only
+                        // the exact bytes moved by this operation, never a replacement meta.
+                        if (existsSync(source + '.meta') || !Buffer.from(await readPath(target + '.meta')).equals(originalMeta)) {
+                            throw new Error('Asset metadata changed during the failed move; manual recovery is required.');
+                        }
+                        await renamePath(target + '.meta', source + '.meta', { overwrite: false });
+                    } catch (recoveryError) {
+                        throw new AggregateError([error, recoveryError], 'Asset move failed and original metadata could not be restored safely.');
+                    }
+                }
+                throw error;
+            }
             return;
         }
 
@@ -168,5 +187,6 @@ export async function moveAssetSource(source: string, target: string, options?:
     } catch (error) {
         console.error(`asset db moveFile from ${source} -> ${target} fail!`);
         console.error(error);
+        if (!renameOptions.overwrite) throw error;
     }
 }