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
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file ui/layout/anchor.ts
* @brief Anchor presets — authoring shortcuts over a UINode's CSS box fields.
*
* The box model is CSS (position + inset + margin), so an anchor is NOT stored
* state: a preset is a derived view that maps to/from the inset/margin/position
* fields. Keeping the box fields the single source of truth (rather than a
* redundant anchor enum, as RectTransform engines store) is what makes a preset
* and the live layout impossible to desync.
*
* Each axis resolves independently to one of {@link AnchorAxis}: Start pins the
* near edge, End the far edge, Stretch pins both edges with the size set to
* `auto` so the insets drive it, and Center leaves both insets AND both margins
* `auto` — the engine reads that combination as "centre this out-of-flow node in
* the parent box", the one anchor a pivot-less CSS box can't express through
* Yoga alone (Yoga's abspos centring keys off the parent's `justifyContent`, so
* it can't differ per sibling).
*/
import { auto, isAuto, px, type Dimension } from '../core/dimension';
import { UIPositionType, type UINodeData } from '../core/ui-node';
/** Per-axis anchor mode (a preset is one of these per axis). */
export enum AnchorAxis {
/** Pin the near edge (left / top). */
Start = 0,
/** Centre via `auto` margins on both edges. */
Center = 1,
/** Pin the far edge (right / bottom). */
End = 2,
/** Pin both edges; the size becomes `auto` so the insets drive it. */
Stretch = 3,
}
/** A 2-D anchor: one {@link AnchorAxis} per axis. */
export interface AnchorPreset {
h: AnchorAxis;
v: AnchorAxis;
}
/** The four axis modes in row/column order, for building a preset grid. */
export const ANCHOR_AXES: readonly AnchorAxis[] = [
AnchorAxis.Start,
AnchorAxis.Center,
AnchorAxis.End,
AnchorAxis.Stretch,
];
/** The UINode box fields one axis of a preset writes. `size` is present only for
* Stretch — every other mode leaves the authored width/height untouched. */
interface AxisFields {
near: Dimension;
far: Dimension;
marginNear: Dimension;
marginFar: Dimension;
size?: Dimension;
}
function axisFields(mode: AnchorAxis): AxisFields {
switch (mode) {
case AnchorAxis.Start:
return { near: px(0), far: auto(), marginNear: px(0), marginFar: px(0) };
case AnchorAxis.End:
return { near: auto(), far: px(0), marginNear: px(0), marginFar: px(0) };
case AnchorAxis.Center:
return { near: auto(), far: auto(), marginNear: auto(), marginFar: auto() };
case AnchorAxis.Stretch:
return { near: px(0), far: px(0), marginNear: px(0), marginFar: px(0), size: auto() };
}
}
/** The UINode fields a preset resolves to. Always sets `position` Absolute plus
* the two inset + two margin dimensions per axis; `width`/`height` appear only
* for a Stretch axis (so a non-stretch axis preserves the authored size). */
export interface AnchorFields {
position: number;
insetLeft: Dimension;
insetRight: Dimension;
insetTop: Dimension;
insetBottom: Dimension;
marginLeft: Dimension;
marginRight: Dimension;
marginTop: Dimension;
marginBottom: Dimension;
width?: Dimension;
height?: Dimension;
}
/** Resolve a preset to the UINode box fields that express it. */
export function anchorPresetFields(preset: AnchorPreset): AnchorFields {
const h = axisFields(preset.h);
const v = axisFields(preset.v);
const fields: AnchorFields = {
position: UIPositionType.Absolute,
insetLeft: h.near,
insetRight: h.far,
insetTop: v.near,
insetBottom: v.far,
marginLeft: h.marginNear,
marginRight: h.marginFar,
marginTop: v.marginNear,
marginBottom: v.marginFar,
};
if (h.size) fields.width = h.size;
if (v.size) fields.height = v.size;
return fields;
}
/** Classify one axis back to its {@link AnchorAxis}, or null when the field
* combination isn't a clean preset (a hand-tuned / over-constrained box). */
function axisMode(near: Dimension, far: Dimension, mNear: Dimension, mFar: Dimension, size: Dimension): AnchorAxis | null {
const nearAuto = isAuto(near);
const farAuto = isAuto(far);
if (nearAuto && farAuto) {
return isAuto(mNear) && isAuto(mFar) ? AnchorAxis.Center : null;
}
if (!nearAuto && !farAuto) {
return isAuto(size) ? AnchorAxis.Stretch : null; // pinned both + definite size = over-constrained
}
if (!nearAuto && !isAuto(mNear)) return AnchorAxis.Start; // near pinned, far auto
if (!farAuto && !isAuto(mFar)) return AnchorAxis.End; // far pinned, near auto
return null;
}
/** Per-axis classification of a UINode's box: each axis resolves independently
* to its {@link AnchorAxis}, or null when that axis isn't a clean preset — so a
* box with one hand-tuned axis still reads (and can keep) the other. */
export function detectAnchorAxes(node: UINodeData): { h: AnchorAxis | null; v: AnchorAxis | null } {
if (node.position !== UIPositionType.Absolute) return { h: null, v: null };
return {
h: axisMode(node.insetLeft, node.insetRight, node.marginLeft, node.marginRight, node.width),
v: axisMode(node.insetTop, node.insetBottom, node.marginTop, node.marginBottom, node.height),
};
}
/** The preset a UINode currently matches, or null (Relative flow, or a custom
* box that isn't a clean preset). `detectAnchor(node with anchorPresetFields(p))`
* round-trips back to `p`. */
export function detectAnchor(node: UINodeData): AnchorPreset | null {
const { h, v } = detectAnchorAxes(node);
if (h === null || v === null) return null;
return { h, v };
}