[break] feat(terrain): add default layer creation and paint falloff

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

@@ -5707,7 +5707,8 @@ export { }
 `;
 
 exports[`DTS API compatibility cli.d.ts should match snapshot 1`] = `
-"import type { Component } from 'cc';
+"import type { Camera } from 'cc';
+import type { Component } from 'cc';
 import type { Node as Node_2 } from 'cc';
 import type { Scene } from 'cc';
 import type { Terrain } from 'cc';
@@ -6494,6 +6495,7 @@ export declare interface ICameraService {
     setGridColor(color: number[], persist?: boolean): void;
     setOriginAxes2D(config: IOriginAxesConfig): void;
     setOriginAxes3D(config: IOriginAxesConfig): void;
+    getCamera(): Camera | undefined;
     onUpdate(deltaTime: number): void;
 }
 export declare interface IChangeNodeLockParams {
@@ -7421,11 +7423,17 @@ export declare interface ITerrainManageState {
     lightMapSize: number;
     blockCount: [number, number];
 }
+export declare interface ITerrainPaintBrushPatch extends ITerrainBrushPatch {
+    falloff?: number;
+}
+export declare interface ITerrainPaintBrushState extends ITerrainBrushState {
+    falloff: number;
+}
 export declare interface ITerrainPaintSessionPatch {
-    brush?: ITerrainBrushPatch;
+    brush?: ITerrainPaintBrushPatch;
 }
 export declare interface ITerrainPaintState {
-    brush: ITerrainBrushState;
+    brush: ITerrainPaintBrushState;
 }
 export declare interface ITerrainSculptSessionPatch {
     tool?: TerrainSculptTool;
@@ -7456,7 +7464,7 @@ export declare interface ITerrainService {
     setPaintBrushAsset(target: ITerrainTarget, assetUuid: string | null): Promise<TerrainReadResult>;
     setPaintSession(target: ITerrainTarget, patch: ITerrainPaintSessionPatch): TerrainReadResult;
     saveManage(target: ITerrainTarget, manage: ITerrainManageState): Promise<TerrainReadResult>;
-    addLayer(target: ITerrainTarget, layer: ITerrainLayerState): Promise<TerrainReadResult>;
+    addLayer(target: ITerrainTarget, layer?: ITerrainLayerState): Promise<TerrainReadResult>;
     removeLayer(target: ITerrainTarget, index: number): Promise<TerrainReadResult>;
     updateLayer(target: ITerrainTarget, index: number, patch: ITerrainLayerPatch): Promise<TerrainReadResult>;
     readBlock(target: ITerrainTarget): TerrainBlockReadResult;

src/core/scene/common/camera.ts

@@ -1,4 +1,4 @@
-import type { Vec3 } from 'cc';
+import type { Camera, Vec3 } from 'cc';
 import type { ICameraConfig, IOriginAxesConfig } from '../scene-configs';
 
 export type { ICameraConfig, IOriginAxesConfig };
@@ -26,6 +26,8 @@ export interface ICameraService {
     setGridColor(color: number[], persist?: boolean): void;
     setOriginAxes2D(config: IOriginAxesConfig): void;
     setOriginAxes3D(config: IOriginAxesConfig): void;
+    /** Returns the editor camera when it has been created for the active Scene. */
+    getCamera(): Camera | undefined;
     onUpdate(deltaTime: number): void;
 }
 

src/core/scene/common/terrain.ts

@@ -1,5 +1,13 @@
 import type { Terrain } from 'cc';
 
+/** Runtime fields installed by the Scene Terrain service on engine Terrain components. */
+declare module 'cc' {
+    interface Terrain {
+        manager?: ITerrainService | null;
+        isTerrainChange?: boolean;
+    }
+}
+
 /** Identifies one Terrain component without relying on the active gizmo selection. */
 export interface ITerrainTarget {
     nodeUuid: string;
@@ -49,6 +57,11 @@ export interface ITerrainBrushState {
     setHeight: number;
 }
 
+/** JSON-safe Paint brush state. Falloff belongs to the Paint circle brush only. */
+export interface ITerrainPaintBrushState extends ITerrainBrushState {
+    falloff: number;
+}
+
 /** Canonical Sculpt session state for a valid Terrain target. */
 export interface ITerrainSculptState {
     tool: TerrainSculptTool;
@@ -57,7 +70,7 @@ export interface ITerrainSculptState {
 
 /** Canonical Paint session state for a valid Terrain target. */
 export interface ITerrainPaintState {
-    brush: ITerrainBrushState;
+    brush: ITerrainPaintBrushState;
 }
 
 /** The canonical editor-session state for one valid Terrain target. */
@@ -87,6 +100,21 @@ export interface ITerrainInvalidSnapshot {
 /** Discriminated read result. Callers must replace cached state when `valid` is `false`. */
 export type TerrainReadResult = ITerrainSnapshot | ITerrainInvalidSnapshot;
 
+/** Stable codes for internal Terrain layer authoring failures. */
+export type TerrainLayerErrorCode = 'DEFAULT_DETAIL_MAP_UNAVAILABLE';
+
+/** Reports an internal Terrain layer authoring failure without mutating the selected target. */
+export class TerrainLayerError extends Error {
+    constructor(
+        readonly code: TerrainLayerErrorCode,
+        message: string,
+        options?: ErrorOptions,
+    ) {
+        super(message, options);
+        this.name = 'TerrainLayerError';
+    }
+}
+
 /** A partial, non-asset numeric brush-session update. Brush image selection is controlled by dedicated asset commands. */
 export interface ITerrainBrushPatch {
     radius?: number;
@@ -95,6 +123,11 @@ export interface ITerrainBrushPatch {
     setHeight?: number;
 }
 
+/** A partial Paint brush update. Falloff is constrained to the inclusive [0, 1] range by TerrainService. */
+export interface ITerrainPaintBrushPatch extends ITerrainBrushPatch {
+    falloff?: number;
+}
+
 /** A partial Sculpt session update that does not assign brush assets or create Scene Undo entries. */
 export interface ITerrainSculptSessionPatch {
     tool?: TerrainSculptTool;
@@ -103,7 +136,7 @@ export interface ITerrainSculptSessionPatch {
 
 /** A partial Paint session update that does not assign brush assets or create Scene Undo entries. */
 export interface ITerrainPaintSessionPatch {
-    brush?: ITerrainBrushPatch;
+    brush?: ITerrainPaintBrushPatch;
 }
 
 /** One Terrain layer assigned to an RGBA channel in a selected Terrain block. */
@@ -180,8 +213,8 @@ export interface ITerrainService {
     setPaintSession(target: ITerrainTarget, patch: ITerrainPaintSessionPatch): TerrainReadResult;
     /** Commits a complete Manage draft as one TerrainInfo/Undo mutation. */
     saveManage(target: ITerrainTarget, manage: ITerrainManageState): Promise<TerrainReadResult>;
-    /** Adds a fully specified Terrain layer; `detailMapUuid` must identify a compatible Texture2D. */
-    addLayer(target: ITerrainTarget, layer: ITerrainLayerState): Promise<TerrainReadResult>;
+    /** Adds a complete layer, or uses the CLI-owned built-in texture and material defaults when omitted. */
+    addLayer(target: ITerrainTarget, layer?: ITerrainLayerState): Promise<TerrainReadResult>;
     /** Removes one Terrain layer slot and returns the authoritative state. */
     removeLayer(target: ITerrainTarget, index: number): Promise<TerrainReadResult>;
     /** Applies one explicit layer patch and returns the authoritative state. */

src/core/scene/scene-process/service/camera.ts

@@ -19,7 +19,7 @@ export class CameraService extends BaseService<ICameraEvents> implements ICamera
     private _controller2D!: CameraController2D;
     private _controller3D!: CameraController3D;
     private _controller!: CameraControllerBase;
-    private _camera!: EditorCameraComponent;
+    private _camera?: EditorCameraComponent;
     private _controllerFirstChange = false;
     private _currentUuid = '';
     private _cameraInfos: Record<string, any> = {};
@@ -361,22 +361,23 @@ export class CameraService extends BaseService<ICameraEvents> implements ICamera
     }
 
     setCameraProperty(options: any, persist = true): void {
-        if (typeof options !== 'object' || !this._camera) return;
+        const camera = this._camera;
+        if (typeof options !== 'object' || !camera) return;
         Object.keys(options).forEach((key) => {
             if (options[key] == null) return;
             if (key === 'clearColor') {
-                this._camera[key] = cc.color(
+                camera[key] = cc.color(
                     options[key][0], options[key][1],
                     options[key][2], options[key][3],
                 );
             } else if (key === 'near' || key === 'far') {
                 (this._controller as any)[key] = options[key];
-                (this._camera as any)[key] = options[key];
+                (camera as any)[key] = options[key];
             } else if (key === 'fov') {
                 this.emit('camera:fov-changed', options[key]);
-                (this._camera as any)[key] = options[key];
+                (camera as any)[key] = options[key];
             } else {
-                (this._camera as any)[key] = options[key];
+                (camera as any)[key] = options[key];
             }
         });
         Service.Engine.repaintInEditMode();
@@ -465,7 +466,7 @@ export class CameraService extends BaseService<ICameraEvents> implements ICamera
         this._controller?.refresh();
     }
 
-    getCamera() {
+    getCamera(): Camera | undefined {
         return this._camera;
     }
 

src/core/scene/scene-process/service/gizmo/components/terrain/gizmo-persistent.ts

@@ -10,7 +10,7 @@ import type TerrainGizmo from './gizmo-select';
 export default class TerrainPersistentGizmo extends GizmoBase<Terrain> {
     private _controller!: TerrainController;
     private get selectGizmo(): TerrainGizmo | null {
-        return this.target ? Service.Gizmo.getComponentGizmo(this.target) as TerrainGizmo | null : null;
+        return this.target ? (Service.Gizmo.getComponentGizmo(this.target) as TerrainGizmo | null) : null;
     }
     protected init() {
         this._controller = new TerrainController(this.getGizmoRoot());
@@ -22,23 +22,43 @@ export default class TerrainPersistentGizmo extends GizmoBase<Terrain> {
     }
     private updateController() {
         if (!this._controller) return;
-        if (!this.target) { this._controller.hide(); return; }
+        if (!this.target) {
+            this._controller.hide();
+            return;
+        }
         this._controller.updateWorldPosition(this.target.node.getWorldPosition());
         const info = this.target.info;
         this._controller.updateSize(info.size.width, info.size.height);
-        this._controller.show(); Service.Engine.repaintInEditMode();
+        this._controller.show();
+        Service.Engine.repaintInEditMode();
+    }
+    public onTargetUpdate() {
+        this.updateController();
+    }
+    public onNodeChanged() {
+        this.updateController();
     }
-    public onTargetUpdate() { this.updateController(); }
-    public onNodeChanged() { this.updateController(); }
     onControllerMouseDown(event: GizmoMouseEvent) {
         if (!this.target) return;
         const path = getEditorNodePath(this.target.node);
         if (Service.Selection.query()[0] !== path) {
-            event.propagationStopped = true; Service.Selection.select(path); return;
+            event.propagationStopped = true;
+            Service.Selection.select(path);
+            return;
         }
-        const gizmo = this.selectGizmo; if (gizmo?.visible()) gizmo.onControllerMouseDown(event);
+        const gizmo = this.selectGizmo;
+        if (gizmo?.visible()) gizmo.onControllerMouseDown(event);
+    }
+    onControllerMouseMove(event: GizmoMouseEvent) {
+        const gizmo = this.selectGizmo;
+        if (gizmo?.visible()) gizmo.onControllerMouseMove(event);
+    }
+    onControllerMouseUp(event: GizmoMouseEvent) {
+        const gizmo = this.selectGizmo;
+        if (gizmo?.visible()) gizmo.onControllerMouseUp(event);
+    }
+    onControllerHoverOut() {
+        const gizmo = this.selectGizmo;
+        if (gizmo?.visible()) gizmo.onControllerHoverOut();
     }
-    onControllerMouseMove(event: GizmoMouseEvent) { const gizmo = this.selectGizmo; if (gizmo?.visible()) gizmo.onControllerMouseMove(event); }
-    onControllerMouseUp(event: GizmoMouseEvent) { const gizmo = this.selectGizmo; if (gizmo?.visible()) gizmo.onControllerMouseUp(event); }
-    onControllerHoverOut() { const gizmo = this.selectGizmo; if (gizmo?.visible()) gizmo.onControllerHoverOut(); }
 }