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.

feat(ui): the screen has a coordinate authority, and a camera is not in it

esengine46cae88497dc
diff --git a/sdk/src/ui/core/screen-layout.ts b/sdk/src/ui/core/screen-layout.ts
new file mode 100644
index 000000000..154ed4f1b
--- /dev/null
+++ b/sdk/src/ui/core/screen-layout.ts
@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file screen-layout.ts
+ * @brief The one screen-space fact every consumer of it reads.
+ *
+ * @details Screen UI is laid out in a pixel domain decided by the design
+ * resolution, the viewport, the scale mode and the device — and by
+ * nothing else. No camera position, no camera projection, no world
+ * units. A camera moving must not move a HUD, and the only way to
+ * guarantee that is for the coordinates never to have come from one.
+ *
+ * Two rects, not one. The VIEWPORT box is the whole framebuffer and is
+ * what the overlay projects; the SAFE box is the part a layout should
+ * keep its content inside. Merging them shrinks a full-screen fade into
+ * the notch-safe rect, which is not what a fade is.
+ */
+import { defineResource } from '../../ecs/resource';
+import { computeEffectiveOrthoSize, type CanvasScale } from '../../camera/uiLayoutRect';
+
+/** Insets, in layout pixels, the device asks content to stay clear of. */
+export interface ScreenInsets {
+ left: number;
+ bottom: number;
+ right: number;
+ top: number;
+}
+
+export const NO_INSETS: ScreenInsets = { left: 0, bottom: 0, right: 0, top: 0 };
+
+/**
+ * The layout-pixel domain, centred on the origin. `left`/`right` are what a
+ * screen root is placed within; `scale` is how many device pixels one layout
+ * pixel covers, which is what a text renderer needs and a camera cannot say.
+ */
+export interface ScreenLayoutData {
+ /** False before a viewport is known — nothing has a screen to lay out on. */
+ valid: boolean;
+ left: number;
+ bottom: number;
+ right: number;
+ top: number;
+ /** The same box as the safe area allows: content, not the projection. */
+ safeLeft: number;
+ safeBottom: number;
+ safeRight: number;
+ safeTop: number;
+ /** Device pixels per layout pixel. */
+ scale: number;
+ /** The framebuffer this domain projects onto. */
+ viewportW: number;
+ viewportH: number;
+}
+
+const NO_SCREEN: ScreenLayoutData = {
+ valid: false,
+ left: 0, bottom: 0, right: 0, top: 0,
+ safeLeft: 0, safeBottom: 0, safeRight: 0, safeTop: 0,
+ scale: 1, viewportW: 0, viewportH: 0,
+};
+
+export const ScreenLayout = defineResource<ScreenLayoutData>({ ...NO_SCREEN }, 'ScreenLayout');
+
+/**
+ * The layout box for a viewport. `fit` is the project's design resolution and
+ * scale mode; absent, the viewport is its own design box and one layout pixel is
+ * one device pixel.
+ *
+ * @param insets device-reported safe-area insets, in DEVICE pixels.
+ */
+export function screenLayoutRect(
+ fit: CanvasScale | null,
+ viewportW: number,
+ viewportH: number,
+ insets: ScreenInsets = NO_INSETS,
+): ScreenLayoutData {
+ if (viewportW <= 0 || viewportH <= 0) {
+ return { ...NO_SCREEN };
+ }
+ const aspect = viewportW / viewportH;
+ let halfH: number;
+ if (fit && fit.designResolution.y > 0 && fit.designResolution.x > 0) {
+ const designAspect = fit.designResolution.x / fit.designResolution.y;
+ halfH = computeEffectiveOrthoSize(
+ fit.designResolution.y / 2, designAspect, aspect, fit.scaleMode, fit.matchWidthOrHeight,
+ );
+ } else {
+ halfH = viewportH / 2;
+ }
+ const halfW = halfH * aspect;
+ // One number: the box is fitted to the viewport's aspect, so both axes carry
+ // the same ratio and a non-uniform scale cannot arise here.
+ const scale = viewportH / (halfH * 2);
+ return {
+ valid: true,
+ left: -halfW, right: halfW, bottom: -halfH, top: halfH,
+ safeLeft: -halfW + insets.left / scale,
+ safeRight: halfW - insets.right / scale,
+ safeBottom: -halfH + insets.bottom / scale,
+ safeTop: halfH - insets.top / scale,
+ scale,
+ viewportW, viewportH,
+ };
+}
diff --git a/sdk/tests/screenLayout.test.ts b/sdk/tests/screenLayout.test.ts
new file mode 100644
index 000000000..d765bbd47
--- /dev/null
+++ b/sdk/tests/screenLayout.test.ts
@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file The screen-space domain, and what it refuses to depend on.
+ *
+ * Screen UI has one coordinate authority and a camera is not part of it. These
+ * are the properties every consumer — layout, picking, dragging, text, the
+ * overlay projection — reads the same answer from.
+ */
+import { describe, it, expect } from 'vitest';
+import { screenLayoutRect, NO_INSETS } from '../src/ui/core/screen-layout';
+import { CanvasScaleMode } from '../src/wasm/wasm.generated';
+
+const FIT = {
+ designResolution: { x: 960, y: 640 },
+ scaleMode: CanvasScaleMode.FixedHeight,
+ matchWidthOrHeight: 0.5,
+};
+
+describe('the screen layout domain', () => {
+ it('is the design box, centred on the origin', () => {
+ const r = screenLayoutRect(FIT, 960, 640);
+ expect(r.valid).toBe(true);
+ expect(r.left).toBeCloseTo(-480);
+ expect(r.right).toBeCloseTo(480);
+ expect(r.bottom).toBeCloseTo(-320);
+ expect(r.top).toBeCloseTo(320);
+ // Centred means centred: a box that drifts is a box something moved.
+ expect(r.left + r.right).toBeCloseTo(0);
+ expect(r.bottom + r.top).toBeCloseTo(0);
+ });
+
+ it('keeps the fitted axis and widens the other with the viewport', () => {
+ const wide = screenLayoutRect(FIT, 1280, 640);
+ expect(wide.top - wide.bottom).toBeCloseTo(640);
+ expect(wide.right - wide.left).toBeCloseTo(1280);
+ const tall = screenLayoutRect(FIT, 480, 640);
+ expect(tall.top - tall.bottom).toBeCloseTo(640);
+ expect(tall.right - tall.left).toBeCloseTo(480);
+ });
+
+ it('says how many device pixels a layout pixel covers', () => {
+ expect(screenLayoutRect(FIT, 960, 640).scale).toBeCloseTo(1);
+ expect(screenLayoutRect(FIT, 1920, 1280).scale).toBeCloseTo(2);
+ });
+
+ it('takes safe insets off the CONTENT box and leaves the projection whole', () => {
+ const r = screenLayoutRect(FIT, 960, 640, { left: 40, right: 20, top: 60, bottom: 0 });
+ // The full box still covers the framebuffer — a fade is not notch-safe.
+ expect(r.left).toBeCloseTo(-480);
+ expect(r.right).toBeCloseTo(480);
+ expect(r.safeLeft).toBeCloseTo(-440);
+ expect(r.safeRight).toBeCloseTo(460);
+ expect(r.safeTop).toBeCloseTo(260);
+ expect(r.safeBottom).toBeCloseTo(-320);
+ });
+
+ it('reports insets in layout pixels, not device ones', () => {
+ // Same physical notch, twice the density: half the layout pixels.
+ const one = screenLayoutRect(FIT, 960, 640, { ...NO_INSETS, top: 60 });
+ const two = screenLayoutRect(FIT, 1920, 1280, { ...NO_INSETS, top: 60 });
+ expect(one.top - one.safeTop).toBeCloseTo(60);
+ expect(two.top - two.safeTop).toBeCloseTo(30);
+ });
+
+ it('has no way to be told about a camera', () => {
+ // The signature is the guarantee: design fit, viewport, insets (defaulted,
+ // so `length` counts three). Nothing a camera could arrive through, so no
+ // consumer can pass one and no later edit can quietly start reading one.
+ expect(screenLayoutRect.length).toBe(3);
+ const a = screenLayoutRect(FIT, 960, 640);
+ const b = screenLayoutRect(FIT, 960, 640);
+ expect(a).toEqual(b);
+ });
+
+ it('answers invalid for a viewport that does not exist yet', () => {
+ expect(screenLayoutRect(FIT, 0, 640).valid).toBe(false);
+ expect(screenLayoutRect(FIT, 960, 0).valid).toBe(false);
+ });
+
+ it('falls back to the viewport when a project declares no design box', () => {
+ const r = screenLayoutRect(null, 800, 600);
+ expect(r.right - r.left).toBeCloseTo(800);
+ expect(r.top - r.bottom).toBeCloseTo(600);
+ expect(r.scale).toBeCloseTo(1);
+ });
+});