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): Dimension foundation + transient component mechanism (REARCH_GUI F2)
esengined4081723e096
diff --git a/sdk/src/component.ts b/sdk/src/component.tsindex 5b6382690..77aff9754 100644--- a/sdk/src/component.ts+++ b/sdk/src/component.ts@@ -27,6 +27,13 @@ export interface ComponentMetadata {spineFields?: SpineFieldMeta;entityFields?: string[];discoverAssets?: (data: Record<string, unknown>) => AssetRef[];+ /**+ * Runtime-only state that must never persist: a transient component is+ * skipped by {@link serializeScene} (e.g. per-frame pointer/drag/hover state+ * that its driving system rebuilds each frame, REARCH_GUI F2). Systems still+ * read/write it normally; only scene save omits it.+ */+ transient?: boolean;}// =============================================================================@@ -44,6 +51,8 @@ export interface ComponentDef<T> {readonly colorKeys: readonly string[];readonly animatableFields: readonly string[];readonly discoverAssets?: (data: Record<string, unknown>) => AssetRef[];+ /** Runtime-only: omitted from scene serialization. See {@link ComponentMetadata.transient}. */+ readonly transient: boolean;create(data?: Partial<T>): T;}@@ -100,6 +109,7 @@ function createComponentDef<T extends object>(colorKeys: detectColorKeys(defaults),animatableFields: [],discoverAssets: metadata?.discoverAssets,+ transient: metadata?.transient ?? false,create(data?: Partial<T>): T {if (keyInfo) {const result = { ...defaultsRec };@@ -203,6 +213,8 @@ export interface BuiltinComponentDef<T> {readonly colorKeys: readonly string[];readonly animatableFields: readonly string[];readonly discoverAssets?: (data: Record<string, unknown>) => AssetRef[];+ /** Runtime-only: omitted from scene serialization. See {@link ComponentMetadata.transient}. */+ readonly transient: boolean;}// =============================================================================@@ -281,6 +293,10 @@ export function defineBuiltin<T>(name: string, defaults: T, metadata?: ComponentcolorKeys: meta?.colorFields ?? detectColorKeys(defaults),animatableFields: meta?.animatableFields ?? [],discoverAssets: metadata?.discoverAssets,+ // Builtins declare transience via the defineBuiltin metadata arg for now;+ // a C++-side ES_COMPONENT(transient) annotation can flow through+ // COMPONENT_META later (REARCH_GUI F6) without touching call sites.+ transient: metadata?.transient ?? false,};builtinRegistry.set(name, def);return def;diff --git a/sdk/src/scene.ts b/sdk/src/scene.tsindex e0f9f81dc..4f8abd63d 100644--- a/sdk/src/scene.ts+++ b/sdk/src/scene.ts@@ -614,6 +614,9 @@ export function serializeScene(world: World, sceneName = 'scene'): SceneData {if (STRUCTURAL_COMPONENTS.has(typeName)) continue;const comp = getComponent(typeName);if (!comp) continue;+ // Runtime-only components (per-frame pointer/drag/hover state) never+ // persist — their systems rebuild them each frame. See ComponentMetadata.transient.+ if (comp.transient) continue;const data = world.tryGet(entity, comp);if (data === null) continue;const payload = data as Record<string, unknown>;diff --git a/sdk/src/ui/core/dimension.ts b/sdk/src/ui/core/dimension.tsnew file mode 100644index 000000000..601485ccf--- /dev/null+++ b/sdk/src/ui/core/dimension.ts@@ -0,0 +1,41 @@+// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file ui/core/dimension.ts+ * @brief Dimension — a CSS-style length (value + unit) for the runtime UI box+ * model (REARCH_GUI F2, see docs/REARCH_GUI.md).+ *+ * One field can be pixels, a percentage of the parent, or content-driven (auto),+ * replacing the old size/offset/`-1`-sentinel scheme. The on-wire shape matches+ * the C++ `Dimension` struct serialized by the EHT codegen (`{ value, unit }`,+ * `unit` an integer); these helpers give it a typed, ergonomic authoring API.+ */++/** How a {@link Dimension}'s `value` is interpreted. Mirrors the C++ u8 unit. */+export const DimensionUnit = {+ /** Absolute pixels. */+ Px: 0,+ /** Percentage of the parent's corresponding axis (0..100). */+ Percent: 1,+ /** Content-/layout-driven; `value` is ignored. */+ Auto: 2,+} as const;+export type DimensionUnit = (typeof DimensionUnit)[keyof typeof DimensionUnit];++/** A CSS-style length. Matches the generated `Dimension` interface (`{ value, unit }`). */+export interface Dimension {+ value: number;+ unit: number;+}++/** `n` pixels. */+export const px = (n: number): Dimension => ({ value: n, unit: DimensionUnit.Px });++/** `n` percent of the parent axis (0..100). */+export const percent = (n: number): Dimension => ({ value: n, unit: DimensionUnit.Percent });++/** Content-/layout-driven length (Yoga `auto`). */+export const auto = (): Dimension => ({ value: 0, unit: DimensionUnit.Auto });++/** True when the dimension is the content-/layout-driven `auto` length. */+export const isAuto = (d: Dimension): boolean => d.unit === DimensionUnit.Auto;diff --git a/sdk/src/ui/index.ts b/sdk/src/ui/index.tsindex b28f1610e..29be1ffde 100644--- a/sdk/src/ui/index.ts+++ b/sdk/src/ui/index.ts@@ -66,6 +66,7 @@ export {// ─── Layer 1: Primitives ────────────────────────────────────────────────────+export { DimensionUnit, type Dimension, px, percent, auto, isAuto } from './core/dimension';export { UIRect, type UIRectData } from './core/ui-rect';export {diff --git a/sdk/tests/ui-dimension-transient.test.ts b/sdk/tests/ui-dimension-transient.test.tsnew file mode 100644index 000000000..ac564e08f--- /dev/null+++ b/sdk/tests/ui-dimension-transient.test.ts@@ -0,0 +1,56 @@+// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { describe, it, expect, beforeEach } from 'vitest';+import { World } from '../src/world';+import { createMockModule } from './mocks/wasm';+import { defineComponent } from '../src/component';+import { serializeScene } from '../src/scene';+import { DimensionUnit, px, percent, auto, isAuto } from '../src/ui/core/dimension';++describe('Dimension foundation (REARCH_GUI F2)', () => {+ it('px/percent/auto build unit-tagged lengths', () => {+ expect(px(10)).toEqual({ value: 10, unit: DimensionUnit.Px });+ expect(percent(50)).toEqual({ value: 50, unit: DimensionUnit.Percent });+ expect(auto()).toEqual({ value: 0, unit: DimensionUnit.Auto });+ });++ it('isAuto distinguishes the content-driven length', () => {+ expect(isAuto(auto())).toBe(true);+ expect(isAuto(px(5))).toBe(false);+ expect(isAuto(percent(100))).toBe(false);+ });+});++describe('transient components (REARCH_GUI F2)', () => {+ let world: World;++ // Components are registered into the active context; create the world first so+ // they land in the context serializeScene/getComponentTypes later read from.+ beforeEach(() => {+ const mod = createMockModule();+ world = new World();+ world.connectCpp(mod.getRegistry(), mod);+ });++ it('records transience on the def (false by default)', () => {+ const Persisted = defineComponent('TestPersisted', { hp: 100 });+ const Frame = defineComponent('TestFrame', { hover: false }, { transient: true });+ expect(Frame.transient).toBe(true);+ expect(Persisted.transient).toBe(false);+ });++ it('serializeScene omits transient components but keeps persisted ones', () => {+ const Persisted = defineComponent('TestPersisted', { hp: 100 });+ const Frame = defineComponent('TestFrame', { hover: false }, { transient: true });+ const e = world.spawn('E');+ world.insert(e, Persisted, { hp: 50 });+ world.insert(e, Frame, { hover: true });++ const scene = serializeScene(world);+ const rec = scene.entities.find(x => x.name === 'E')!;+ const types = rec.components.map(c => c.type);++ expect(types).toContain('TestPersisted');+ expect(types).not.toContain('TestFrame');+ });+});