Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

fix(cocos): a camera keeps what it clears: the UI camera clears depth only, so the world camera's picture is no longer wiped by it

yhhfe049834d199
diff --git a/pipeline/src/import/cocos/components.ts b/pipeline/src/import/cocos/components.ts
index a228a297b..4c4f3c56d 100644
--- a/pipeline/src/import/cocos/components.ts
+++ b/pipeline/src/import/cocos/components.ts
@@ -316,6 +316,14 @@ function richText(c: CocosComponent, box: UiBox | null, ctx: ComponentContext):
};
}
+/**
+ * What a Cocos camera clears, as the engine's: the engine's flags are colour (1) and depth (2). Cocos writes the graphics API's bits, so a solid
+ * colour is 7 (all three), depth only is 6 and a skybox is 14; the engine has no skybox, which a camera that would have drawn one clears as a colour.
+ */
+export function engineClearFlags(cocos: number): number {
+ return cocos === 14 ? 3 : (cocos & 1 ? 1 : 0) | (cocos & 2 ? 2 : 0);
+}
+
function camera(c: CocosComponent, ctx: ComponentContext): ComponentData {
const d = c.data;
ctx.report.component('cc.Camera', 'mapped');
@@ -329,6 +337,8 @@ function camera(c: CocosComponent, ctx: ComponentContext): ComponentData {
farPlane: num(d._far, 1000),
priority: num(d._priority, 0),
cullingMask: num(d._visibility, 0xffffffff) >>> 0,
+ // a camera drawn over another (the UI's, which clears only depth) must not wipe what the one under it drew
+ clearFlags: engineClearFlags(num(d._clearFlags, 7)),
...(isObj(d._rect) ? { viewport: { x: num(d._rect.x, 0), y: num(d._rect.y, 0), z: num(d._rect.width, 1), w: num(d._rect.height, 1) } } : {}),
isActive: c.enabled,
},
diff --git a/pipeline/src/import/cocos/importProject.ts b/pipeline/src/import/cocos/importProject.ts
index c34a1ff4a..c09b5d033 100644
--- a/pipeline/src/import/cocos/importProject.ts
+++ b/pipeline/src/import/cocos/importProject.ts
@@ -31,7 +31,7 @@ import { convertPass, isOutlinePass, type PassConversion } from './effectConvert
* importer that made less (or differently), and is brought up to date when it is opened. Raise it when the converted output changes in a
* way an existing project needs to pick up: a new generated file, a field a document or a manifest now carries.
*/
-export const COCOS_IMPORT_REVISION = 12;
+export const COCOS_IMPORT_REVISION = 13;
/** Whether the project at @p projectRoot was written by an importer of this revision. A project that was not converted has nothing to bring up. */
export function cocosImportIsCurrent(projectRoot: string): boolean {
diff --git a/pipeline/tests/cocos-camera-clear.test.ts b/pipeline/tests/cocos-camera-clear.test.ts
new file mode 100644
index 000000000..95b7c94b7
--- /dev/null
+++ b/pipeline/tests/cocos-camera-clear.test.ts
@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file A Cocos camera's `_clearFlags` become the engine's: the UI camera clears depth only, so what the world camera drew under it stays.
+ */
+import { describe, expect, it } from 'vitest';
+import { engineClearFlags } from '../src/import/cocos/components';
+
+describe('engineClearFlags', () => {
+ it('maps the graphics API bits to colour and depth', () => {
+ expect(engineClearFlags(7)).toBe(3); // solid colour: colour, depth, stencil
+ expect(engineClearFlags(6)).toBe(2); // depth only: the UI camera's
+ expect(engineClearFlags(0)).toBe(0); // does not clear
+ expect(engineClearFlags(14)).toBe(3); // a skybox the engine does not have: cleared to colour
+ });
+});
diff --git a/sdk/src/cocos/ui/camera.ts b/sdk/src/cocos/ui/camera.ts
index 0bc136b01..c5bbe1c5e 100644
--- a/sdk/src/cocos/ui/camera.ts
+++ b/sdk/src/cocos/ui/camera.ts
@@ -9,8 +9,8 @@
* UI camera — the one that draws the scene's UI and world content — so `screenToWorld(touch.getLocation())` lands where the
* finger is, which is what a script that has a camera in hand wants.
*
- * Not carried: `clearColor` and `clearFlags` are held so a script can read back what it set, but the engine's clear belongs to its
- * renderer settings, not to the camera.
+ * `clearFlags` is carried (colour and depth, as the engine has them; a camera drawn over another clears depth only). `clearColor` is held so a
+ * script can read back what it set, but the engine's clear colour belongs to its renderer settings, not to the camera.
*/
import { Camera as EngineCamera, type CameraData } from '../../ecs/component';
import type { World } from '../../ecs/world';
@@ -42,7 +42,6 @@ export class Camera extends Component {
private patch_(patch: Partial<CameraData>): void { this._world.set(this._entity, EngineCamera, { ...this.data_(), ...patch }); }
private clearColor_ = new Color(0, 0, 0, 255);
- private clearFlags_: number = ClearFlag.SOLID_COLOR;
get projection(): number { return this.data_().projectionType === ENGINE_ORTHO ? ProjectionType.ORTHO : ProjectionType.PERSPECTIVE; }
set projection(v: number) { this.patch_({ projectionType: v === ProjectionType.ORTHO ? ENGINE_ORTHO : 0 }); }
@@ -71,8 +70,11 @@ export class Camera extends Component {
get rect(): Rect { const v = this.data_().viewport; return new Rect(v.x, v.y, v.z, v.w); }
set rect(r: Rect) { this.patch_({ viewport: { x: r.x, y: r.y, z: r.width, w: r.height } }); }
- get clearFlags(): number { return this.clearFlags_; }
- set clearFlags(v: number) { this.clearFlags_ = v; }
+ get clearFlags(): number {
+ const engine = this.data_().clearFlags;
+ return engine === 3 ? ClearFlag.SOLID_COLOR : engine === 2 ? ClearFlag.DEPTH_ONLY : engine === 1 ? ClearFlag.SOLID_COLOR : ClearFlag.DONT_CLEAR;
+ }
+ set clearFlags(v: number) { this.patch_({ clearFlags: v === ClearFlag.SKYBOX ? 3 : (v & 1 ? 1 : 0) | (v & 2 ? 2 : 0) }); }
get clearColor(): Color { return this.clearColor_.clone(); }
set clearColor(v: Color) { this.clearColor_ = v.clone(); }
diff --git a/sdk/tests/cocos/camera-richtext-wasm.test.ts b/sdk/tests/cocos/camera-richtext-wasm.test.ts
index 8353e76d6..b62b22e10 100644
--- a/sdk/tests/cocos/camera-richtext-wasm.test.ts
+++ b/sdk/tests/cocos/camera-richtext-wasm.test.ts
@@ -88,6 +88,19 @@ describe.skipIf(!HAS_WASM)('Camera, RichText and touch locations', () => {
expect(cam.projection).toBe(Camera.ProjectionType.PERSPECTIVE);
});
+ it('clears what Cocos says it clears: a camera drawn over another clears depth only', () => {
+ boot();
+ const n = node('cam');
+ const cam = n.addComponent(Camera)!;
+ cam.clearFlags = Camera.ClearFlag.DEPTH_ONLY;
+ expect(app!.world.get(n._entity, EngineCamera).clearFlags).toBe(2);
+ expect(cam.clearFlags).toBe(Camera.ClearFlag.DEPTH_ONLY);
+ cam.clearFlags = Camera.ClearFlag.SOLID_COLOR;
+ expect(app!.world.get(n._entity, EngineCamera).clearFlags).toBe(3);
+ cam.clearFlags = Camera.ClearFlag.DONT_CLEAR;
+ expect(app!.world.get(n._entity, EngineCamera).clearFlags).toBe(0);
+ });
+
it('maps the viewport to rect and the active flag to enabled', () => {
boot();
const n = node('cam');