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/theme/tokens.ts
* @brief ThemeTokens — semantic design tokens for the widget layer.
*
* Widgets read their defaults from the active theme via {@link getTheme} instead
* of hard-coding values ("去裸色"): one place defines the palette + type scale, and
* an app re-themes every widget it constructs afterwards by calling {@link setTheme}
* first. Semantic roles (surface/control/primary/text/…) decouple widgets from
* literal values, so the same widget code renders correctly under {@link DARK_TOKENS}
* or {@link LIGHT_TOKENS}. `DARK_TOKENS` is the built-in default.
*/
import type { Color } from '../../types';
/**
* Semantic colour roles widgets read, so a project restyles by naming roles
* rather than by reaching into each widget.
*
* @beta
*/
export interface ThemeColors {
/** Dialog / panel background. */
surface: Color;
/** Raised surface — popup / dropdown list background. */
surfaceElevated: Color;
/** Interactive control resting fill (button/option). */
control: Color;
controlHover: Color;
controlActive: Color;
/**
* Keyboard focus. A ROLE of its own rather than a reuse of `controlHover`,
* because the two answer different questions — "the pointer is here" and "the
* keyboard is here" — and a user tabbing through a form has nothing but this to
* tell them where they are. Only ever shown for focus that arrived by keyboard
* (see FocusManagerState.focusVisible).
*/
controlFocus: Color;
/** Slider / progress track. */
track: Color;
/** Accent — slider fill, progress fill, selected option. */
primary: Color;
primaryHover: Color;
primaryActive: Color;
/** Content/handle drawn on top of `primary`. */
onPrimary: Color;
/** Default foreground (label text / icon) drawn on `surface`/`control`. */
text: Color;
/** Modal scrim. */
backdrop: Color;
}
/** Every color role, in display order — THE list a theme editor or a project
* format validator iterates (keyof ThemeColors, as a runtime value). */
export const THEME_COLOR_ROLES: readonly (keyof ThemeColors)[] = [
'surface', 'surfaceElevated', 'control', 'controlHover', 'controlActive', 'controlFocus',
'track', 'primary', 'primaryHover', 'primaryActive', 'onPrimary', 'text', 'backdrop',
];
/** Typographic scale (font sizes in px) consumed by widget text. */
export interface ThemeType {
/** Control / label text (buttons, options). */
label: number;
/** Body / default text. */
body: number;
/** Headings (dialog titles). */
title: number;
}
export interface ThemeTokens {
colors: ThemeColors;
type: ThemeType;
}
/** Shared type scale (the same across light/dark). */
const TYPE_SCALE: ThemeType = { label: 14, body: 15, title: 20 };
/** Built-in dark palette (mirrors the values the widgets used to hard-code). */
export const DARK_TOKENS: ThemeTokens = {
colors: {
surface: { r: 0.16, g: 0.16, b: 0.18, a: 1 },
surfaceElevated:{ r: 0.14, g: 0.14, b: 0.16, a: 1 },
control: { r: 0.22, g: 0.22, b: 0.26, a: 1 },
controlHover: { r: 0.28, g: 0.28, b: 0.32, a: 1 },
controlActive: { r: 0.18, g: 0.18, b: 0.22, a: 1 },
// Cooler than hover rather than merely lighter, so the two stay apart for a
// reader who cannot rely on a small brightness step.
controlFocus: { r: 0.30, g: 0.34, b: 0.44, a: 1 },
track: { r: 0.15, g: 0.15, b: 0.15, a: 1 },
primary: { r: 0.25, g: 0.56, b: 0.96, a: 1 },
primaryHover: { r: 0.30, g: 0.50, b: 0.90, a: 1 },
primaryActive: { r: 0.20, g: 0.40, b: 0.75, a: 1 },
onPrimary: { r: 1, g: 1, b: 1, a: 1 },
text: { r: 0.92, g: 0.92, b: 0.94, a: 1 },
backdrop: { r: 0, g: 0, b: 0, a: 0.5 },
},
type: TYPE_SCALE,
};
/** Built-in light palette — the same roles on light surfaces with dark text. */
export const LIGHT_TOKENS: ThemeTokens = {
colors: {
surface: { r: 0.96, g: 0.96, b: 0.97, a: 1 },
surfaceElevated:{ r: 1, g: 1, b: 1, a: 1 },
control: { r: 0.90, g: 0.90, b: 0.92, a: 1 },
controlHover: { r: 0.84, g: 0.84, b: 0.87, a: 1 },
controlActive: { r: 0.78, g: 0.78, b: 0.82, a: 1 },
controlFocus: { r: 0.80, g: 0.85, b: 0.95, a: 1 },
track: { r: 0.86, g: 0.86, b: 0.88, a: 1 },
primary: { r: 0.20, g: 0.52, b: 0.92, a: 1 },
primaryHover: { r: 0.26, g: 0.58, b: 0.96, a: 1 },
primaryActive: { r: 0.16, g: 0.42, b: 0.80, a: 1 },
onPrimary: { r: 1, g: 1, b: 1, a: 1 },
text: { r: 0.12, g: 0.12, b: 0.14, a: 1 },
backdrop: { r: 0, g: 0, b: 0, a: 0.35 },
},
type: TYPE_SCALE,
};
/** A project's partial re-skin over a base theme: any subset of color roles
* and type-scale steps. Absent keys inherit from the base. */
export interface ThemeOverrides {
colors?: Partial<ThemeColors>;
type?: Partial<ThemeType>;
}
/**
* Parse a JSON-transportable color override map (role → `#rrggbb[aa]` hex — the
* shape project manifests and shipped game configs carry) into {@link ThemeOverrides}.
* Unknown roles and malformed hex are dropped; undefined when nothing valid remains.
* The ONE config→overrides converter shared by the editor and every shipped host.
*/
export function parseThemeOverrides(colors?: Record<string, string>): ThemeOverrides | undefined {
if (!colors) return undefined;
const out: Partial<ThemeColors> = {};
let any = false;
for (const role of THEME_COLOR_ROLES) {
const hex = colors[role];
const m = typeof hex === 'string' ? /^#([0-9a-f]{6})([0-9a-f]{2})?$/i.exec(hex.trim()) : null;
if (!m) continue;
const n = parseInt(m[1]!, 16);
out[role] = {
r: ((n >> 16) & 255) / 255,
g: ((n >> 8) & 255) / 255,
b: (n & 255) / 255,
a: m[2] ? parseInt(m[2], 16) / 255 : 1,
};
any = true;
}
return any ? { colors: out } : undefined;
}
/**
* The effective tokens for a base theme name plus a project's partial overrides —
* the ONE merge every runtime and the editor resolve through, so a project that
* overrides `primary` alone re-tints the accent while inheriting the rest.
*/
export function resolveThemeTokens(base: 'dark' | 'light', overrides?: ThemeOverrides): ThemeTokens {
const baseTokens = base === 'light' ? LIGHT_TOKENS : DARK_TOKENS;
if (!overrides || (!overrides.colors && !overrides.type)) return baseTokens;
return {
colors: { ...baseTokens.colors, ...overrides.colors },
type: { ...baseTokens.type, ...overrides.type },
};
}
let activeTheme: ThemeTokens = DARK_TOKENS;
/** The active design tokens widgets resolve their defaults from. */
export function getTheme(): ThemeTokens {
return activeTheme;
}
/** Replace the active design tokens (affects widgets constructed afterwards). */
export function setTheme(tokens: ThemeTokens): void {
activeTheme = tokens;
}
/** The active colour palette — what a widget reads at build time, so a theme
* swap after that needs a rebuild rather than a repaint.
* @beta */
export function themeColors(): ThemeColors {
return activeTheme.colors;
}
/** Convenience: the active type scale. */
export function themeType(): ThemeType {
return activeTheme.type;
}