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(math): color helpers (col) — lerp, hex parse/format, tint (T4)
yhhebb7496ff28c
diff --git a/sdk/src/core-sys.ts b/sdk/src/core-sys.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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);+ });+});