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): Dimension foundation + transient component mechanism (REARCH_GUI F2)

esengined4081723e096
diff --git a/sdk/src/component.ts b/sdk/src/component.ts
index 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?: Component
colorKeys: 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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');
+ });
+});