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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
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.tsnew file mode 100644index 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.tsnew file mode 100644index 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);+ });+});