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(camera): a full-frame camera that clears no colour is drawn over the main view instead of competing to be it, so a UI camera no longer hides the world camera's picture

yhh029b26ccf706
diff --git a/sdk/src/camera/CameraPlugin.ts b/sdk/src/camera/CameraPlugin.ts
index 3fac5aed9..50b3875e6 100644
--- a/sdk/src/camera/CameraPlugin.ts
+++ b/sdk/src/camera/CameraPlugin.ts
@@ -558,8 +558,7 @@ function resolveCameras(
// draws is usually what the main view is about to sample.
const offscreen = povs.filter((p) => p.renderTarget !== 0).sort((a, b) => a.priority - b.priority);
const onScreen = povs.filter((p) => p.renderTarget === 0);
- const fullFrame = onScreen.filter((p) => isFullFrame(p.viewport));
- const overlays = onScreen.filter((p) => !isFullFrame(p.viewport)).sort((a, b) => a.priority - b.priority);
+ const { fullFrame, overlays } = splitOnScreenCameras(onScreen);
// The origin follows the screen's own camera, before any view is built for it.
if (advance) {
@@ -779,6 +778,20 @@ function publishScreenOverlay(
overlay.active = true;
}
+/**
+ * Which on-screen cameras compete to be the main view and which are laid over it. A full-frame camera that does not clear colour is drawn over
+ * what another one drew (a UI camera over the world's): it is a layer on the main view, not a candidate to be it. With nothing else to lay it
+ * over, it is the main view. Sub-viewport cameras are layers too; the layers are in priority order.
+ * @internal
+ */
+export function splitOnScreenCameras(onScreen: CameraPOV[]): { fullFrame: CameraPOV[]; overlays: CameraPOV[] } {
+ const clearsColour = (p: CameraPOV): boolean => (p.clearFlags & ClearFlags.Color) !== 0;
+ const all = onScreen.filter((p) => isFullFrame(p.viewport));
+ const fullFrame = all.some(clearsColour) ? all.filter(clearsColour) : all;
+ const overlays = onScreen.filter((p) => !fullFrame.includes(p)).sort((a, b) => a.priority - b.priority);
+ return { fullFrame, overlays };
+}
+
// =============================================================================
// Camera Plugin
// =============================================================================
diff --git a/sdk/tests/camera-overlay-split.test.ts b/sdk/tests/camera-overlay-split.test.ts
new file mode 100644
index 000000000..163188a32
--- /dev/null
+++ b/sdk/tests/camera-overlay-split.test.ts
@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file A full-frame camera that clears no colour is a layer over the main view, not a candidate to be it: a world camera and a UI camera that
+ * clears depth only are both drawn, the world's first.
+ */
+import { describe, expect, it } from 'vitest';
+import { splitOnScreenCameras, type CameraPOV } from '../src/camera/CameraPlugin';
+
+const full = { x: 0, y: 0, z: 1, w: 1 };
+const pov = (entity: number, clearFlags: number, priority: number, viewport = full): CameraPOV => ({ entity, clearFlags, priority, viewport } as CameraPOV);
+
+describe('splitOnScreenCameras', () => {
+ it('keeps the camera that clears colour as the main view and lays the depth-only one over it', () => {
+ const ui = pov(1, 2, 1 << 30), world = pov(2, 3, 0);
+ const { fullFrame, overlays } = splitOnScreenCameras([ui, world]);
+ expect(fullFrame).toEqual([world]);
+ expect(overlays).toEqual([ui]);
+ });
+
+ it('leaves a lone depth-only camera as the main view, and two colour cameras as they were', () => {
+ const only = pov(1, 2, 0);
+ expect(splitOnScreenCameras([only]).fullFrame).toEqual([only]);
+ const a = pov(1, 3, 0), b = pov(2, 3, 1);
+ const { fullFrame, overlays } = splitOnScreenCameras([a, b]);
+ expect(fullFrame).toEqual([a, b]);
+ expect(overlays).toEqual([]);
+ });
+
+ it('draws sub-viewport cameras and layers over the main view in priority order', () => {
+ const world = pov(1, 3, 0), mini = pov(2, 3, 5, { x: 0, y: 0, z: 0.3, w: 0.3 }), ui = pov(3, 2, 9);
+ expect(splitOnScreenCameras([ui, mini, world]).overlays).toEqual([mini, ui]);
+ });
+});