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(math): color helpers (col) — lerp, hex parse/format, tint (T4)

yhhebb7496ff28c
diff --git a/sdk/src/core-sys.ts b/sdk/src/core-sys.ts
index 0ab4a9c45..50f9c8af4 100644
--- a/sdk/src/core-sys.ts
+++ b/sdk/src/core-sys.ts
@@ -16,7 +16,7 @@
// Math (scalar / Vec2 / Vec3 helpers on the canonical types)
// =============================================================================
-export { scalar, v2, v3 } from './math';
+export { scalar, v2, v3, col } from './math';
// =============================================================================
// Localization (i18n)
diff --git a/sdk/src/math/color.ts b/sdk/src/math/color.ts
new file mode 100644
index 000000000..eb7265ab3
--- /dev/null
+++ b/sdk/src/math/color.ts
@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file color.ts
+ * @brief Color helpers on the canonical `Color` ({r,g,b,a}, 0..1 floats — the
+ * engine convention, e.g. white = {1,1,1,1}). Pure. Exposed as the
+ * `col` namespace (the bare `color` name is already an SDK export).
+ */
+
+import type { Color } from '../types';
+import { scalar } from './scalar';
+
+function to2(x: number): string {
+ return Math.round(scalar.clamp01(x) * 255).toString(16).padStart(2, '0');
+}
+
+export const col = {
+ create(r = 0, g = 0, b = 0, a = 1): Color { return { r, g, b, a }; },
+ /** Opaque color from RGB (0..1). */
+ rgb(r: number, g: number, b: number): Color { return { r, g, b, a: 1 }; },
+ /** From 0..255 channels (alpha defaults opaque). */
+ from255(r: number, g: number, b: number, a = 255): Color {
+ return { r: r / 255, g: g / 255, b: b / 255, a: a / 255 };
+ },
+ clone(c: Color): Color { return { r: c.r, g: c.g, b: c.b, a: c.a }; },
+
+ /** Per-channel linear interpolate a→b by t (t not clamped). */
+ lerp(a: Color, b: Color, t: number): Color {
+ return {
+ r: a.r + (b.r - a.r) * t,
+ g: a.g + (b.g - a.g) * t,
+ b: a.b + (b.b - a.b) * t,
+ a: a.a + (b.a - a.a) * t,
+ };
+ },
+ withAlpha(c: Color, a: number): Color { return { r: c.r, g: c.g, b: c.b, a }; },
+ /** Per-channel multiply (tint). */
+ multiply(a: Color, b: Color): Color {
+ return { r: a.r * b.r, g: a.g * b.g, b: a.b * b.b, a: a.a * b.a };
+ },
+ /** Scale RGB by `s` (alpha unchanged). */
+ scaleRgb(c: Color, s: number): Color { return { r: c.r * s, g: c.g * s, b: c.b * s, a: c.a }; },
+
+ /**
+ * Parse `#rgb` / `#rgba` / `#rrggbb` / `#rrggbbaa` (with or without `#`) to a
+ * 0..1 Color (alpha defaults opaque). Throws on malformed input.
+ */
+ fromHex(hex: string): Color {
+ let h = hex.replace(/^#/, '');
+ if (h.length === 3 || h.length === 4) {
+ h = h.split('').map((c) => c + c).join('');
+ }
+ if (!/^[0-9a-fA-F]{6}([0-9a-fA-F]{2})?$/.test(h)) {
+ throw new Error(`invalid hex color: "${hex}"`);
+ }
+ const n = (i: number): number => parseInt(h.slice(i, i + 2), 16) / 255;
+ return { r: n(0), g: n(2), b: n(4), a: h.length >= 8 ? n(6) : 1 };
+ },
+
+ /** Format as `#rrggbb` (or `#rrggbbaa` when `withAlpha`). Clamps to [0,1]. */
+ toHex(c: Color, withAlpha = false): string {
+ return `#${to2(c.r)}${to2(c.g)}${to2(c.b)}${withAlpha ? to2(c.a) : ''}`;
+ },
+
+ equals(a: Color, b: Color, epsilon = 1e-6): boolean {
+ return Math.abs(a.r - b.r) <= epsilon
+ && Math.abs(a.g - b.g) <= epsilon
+ && Math.abs(a.b - b.b) <= epsilon
+ && Math.abs(a.a - b.a) <= epsilon;
+ },
+} as const;
diff --git a/sdk/src/math/index.ts b/sdk/src/math/index.ts
index dd10f72ae..7b8d3f3d8 100644
--- a/sdk/src/math/index.ts
+++ b/sdk/src/math/index.ts
@@ -9,3 +9,4 @@
export { scalar } from './scalar';
export { v2 } from './vec2';
export { v3 } from './vec3';
+export { col } from './color';
diff --git a/sdk/tests/math.test.ts b/sdk/tests/math.test.ts
index c01b72d4a..85c4b20d7 100644
--- a/sdk/tests/math.test.ts
+++ b/sdk/tests/math.test.ts
@@ -4,6 +4,7 @@ import { describe, it, expect } from 'vitest';
import { scalar } from '../src/math/scalar';
import { v2 } from '../src/math/vec2';
import { v3 } from '../src/math/vec3';
+import { col } from '../src/math/color';
const close = (a: number, b: number, eps = 1e-9) => expect(Math.abs(a - b)).toBeLessThanOrEqual(eps);
@@ -109,3 +110,35 @@ describe('v3', () => {
expect(v3.equals({ x: 1, y: 1, z: 1 }, { x: 1, y: 1, z: 1 + 1e-9 })).toBe(true);
});
});
+
+describe('col', () => {
+ it('create / rgb / from255', () => {
+ expect(col.rgb(1, 0, 0)).toEqual({ r: 1, g: 0, b: 0, a: 1 });
+ expect(col.from255(255, 128, 0, 255).r).toBe(1);
+ close(col.from255(255, 128, 0).g, 128 / 255);
+ });
+ it('fromHex (#rrggbb, #rgb, #rrggbbaa, no #)', () => {
+ expect(col.fromHex('#ff0000')).toEqual({ r: 1, g: 0, b: 0, a: 1 });
+ expect(col.fromHex('#f00')).toEqual({ r: 1, g: 0, b: 0, a: 1 });
+ expect(col.fromHex('00ff00')).toEqual({ r: 0, g: 1, b: 0, a: 1 });
+ close(col.fromHex('#ff000080').a, 128 / 255);
+ });
+ it('fromHex throws on malformed input', () => {
+ expect(() => col.fromHex('#xyz')).toThrow(/invalid hex/);
+ expect(() => col.fromHex('#ff000')).toThrow(/invalid hex/); // 5 digits: not 3/4/6/8
+ });
+ it('toHex round-trips', () => {
+ expect(col.toHex({ r: 1, g: 0, b: 0, a: 1 })).toBe('#ff0000');
+ expect(col.toHex({ r: 0, g: 1, b: 0, a: 0.5 }, true)).toBe('#00ff0080');
+ expect(col.toHex(col.fromHex('#3399cc'))).toBe('#3399cc');
+ });
+ it('lerp / withAlpha / multiply / scaleRgb / equals', () => {
+ expect(col.lerp({ r: 0, g: 0, b: 0, a: 0 }, { r: 1, g: 1, b: 1, a: 1 }, 0.5))
+ .toEqual({ r: 0.5, g: 0.5, b: 0.5, a: 0.5 });
+ expect(col.withAlpha({ r: 1, g: 1, b: 1, a: 1 }, 0.25).a).toBe(0.25);
+ expect(col.multiply({ r: 1, g: 0.5, b: 1, a: 1 }, { r: 0.5, g: 1, b: 0, a: 1 }))
+ .toEqual({ r: 0.5, g: 0.5, b: 0, a: 1 });
+ expect(col.scaleRgb({ r: 0.4, g: 0.2, b: 0.1, a: 0.8 }, 2)).toEqual({ r: 0.8, g: 0.4, b: 0.2, a: 0.8 });
+ expect(col.equals({ r: 1, g: 1, b: 1, a: 1 }, { r: 1, g: 1, b: 1, a: 1 + 1e-9 })).toBe(true);
+ });
+});