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): SDK scalar/Vec2/Vec3 helper library on canonical types (T4)
yhh62dcab1fdf28
diff --git a/sdk/src/core-sys.ts b/sdk/src/core-sys.tsindex 4c6bd1e86..0de249d31 100644--- a/sdk/src/core-sys.ts+++ b/sdk/src/core-sys.ts@@ -12,6 +12,12 @@* Re-exported wholesale by `core.ts`.*/+// =============================================================================+// Math (scalar / Vec2 / Vec3 helpers on the canonical types)+// =============================================================================++export { scalar, v2, v3 } from './math';+// =============================================================================// Entity Utils// =============================================================================diff --git a/sdk/src/math/index.ts b/sdk/src/math/index.tsnew file mode 100644index 000000000..dd10f72ae--- /dev/null+++ b/sdk/src/math/index.ts@@ -0,0 +1,11 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file index.ts+ * @brief Math module barrel — the single TS source for scalar / Vec2 / Vec3+ * helpers, operating on the canonical types in `../types`.+ */++export { scalar } from './scalar';+export { v2 } from './vec2';+export { v3 } from './vec3';diff --git a/sdk/src/math/scalar.ts b/sdk/src/math/scalar.tsnew file mode 100644index 000000000..93945408f--- /dev/null+++ b/sdk/src/math/scalar.ts@@ -0,0 +1,52 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file scalar.ts+ * @brief Scalar math helpers — the single TS source for the clamp/lerp/remap+ * family game code previously re-implemented inline. Exposed as the+ * `scalar` namespace (e.g. `scalar.lerp(a, b, t)`).+ */++const DEG2RAD = Math.PI / 180;+const RAD2DEG = 180 / Math.PI;++export const scalar = {+ /** Clamp `x` to [min, max]. */+ clamp(x: number, min: number, max: number): number {+ return x < min ? min : x > max ? max : x;+ },+ /** Clamp `x` to [0, 1]. */+ clamp01(x: number): number {+ return x < 0 ? 0 : x > 1 ? 1 : x;+ },+ /** Linear interpolate a→b by t (t is not clamped). */+ lerp(a: number, b: number, t: number): number {+ return a + (b - a) * t;+ },+ /** Inverse of lerp: the t for which lerp(a,b,t)===value (0 if a===b). */+ inverseLerp(a: number, b: number, value: number): number {+ return a === b ? 0 : (value - a) / (b - a);+ },+ /** Map `value` from [inMin,inMax] onto [outMin,outMax]. */+ remap(value: number, inMin: number, inMax: number, outMin: number, outMax: number): number {+ return outMin + (outMax - outMin) * (inMin === inMax ? 0 : (value - inMin) / (inMax - inMin));+ },+ deg2rad(deg: number): number { return deg * DEG2RAD; },+ rad2deg(rad: number): number { return rad * RAD2DEG; },+ /** Within `epsilon` (default 1e-6). */+ approximately(a: number, b: number, epsilon = 1e-6): boolean {+ return Math.abs(a - b) <= epsilon;+ },+ /** Hermite smoothstep of `x` across the [edge0, edge1] edge (clamped). */+ smoothstep(edge0: number, edge1: number, x: number): number {+ const t = scalar.clamp01(edge0 === edge1 ? 0 : (x - edge0) / (edge1 - edge0));+ return t * t * (3 - 2 * t);+ },+ /** Euclidean modulo — result has the sign of `n` (unlike JS `%`). */+ mod(x: number, n: number): number {+ return ((x % n) + n) % n;+ },+ sign(x: number): number {+ return x > 0 ? 1 : x < 0 ? -1 : 0;+ },+} as const;diff --git a/sdk/src/math/vec2.ts b/sdk/src/math/vec2.tsnew file mode 100644index 000000000..ea127478f--- /dev/null+++ b/sdk/src/math/vec2.ts@@ -0,0 +1,60 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file vec2.ts+ * @brief Vec2 helpers — the single TS source for 2D vector math, operating on+ * the canonical `Vec2` ({x,y}) type. Pure: every op returns a new Vec2.+ * Exposed as the `v2` namespace (e.g. `v2.add(a, b)`).+ */++import type { Vec2 } from '../types';++export const v2 = {+ create(x = 0, y = 0): Vec2 { return { x, y }; },+ clone(a: Vec2): Vec2 { return { x: a.x, y: a.y }; },++ add(a: Vec2, b: Vec2): Vec2 { return { x: a.x + b.x, y: a.y + b.y }; },+ sub(a: Vec2, b: Vec2): Vec2 { return { x: a.x - b.x, y: a.y - b.y }; },+ /** Multiply by a scalar. */+ scale(a: Vec2, s: number): Vec2 { return { x: a.x * s, y: a.y * s }; },+ /** Component-wise multiply. */+ mul(a: Vec2, b: Vec2): Vec2 { return { x: a.x * b.x, y: a.y * b.y }; },+ neg(a: Vec2): Vec2 { return { x: -a.x, y: -a.y }; },++ dot(a: Vec2, b: Vec2): number { return a.x * b.x + a.y * b.y; },+ /** 2D cross product (z component of the 3D cross). */+ cross(a: Vec2, b: Vec2): number { return a.x * b.y - a.y * b.x; },++ len(a: Vec2): number { return Math.hypot(a.x, a.y); },+ len2(a: Vec2): number { return a.x * a.x + a.y * a.y; },+ dist(a: Vec2, b: Vec2): number { return Math.hypot(a.x - b.x, a.y - b.y); },+ dist2(a: Vec2, b: Vec2): number { const dx = a.x - b.x, dy = a.y - b.y; return dx * dx + dy * dy; },++ /** Unit vector, or {0,0} for a zero vector. */+ normalize(a: Vec2): Vec2 {+ const l = Math.hypot(a.x, a.y);+ return l > 0 ? { x: a.x / l, y: a.y / l } : { x: 0, y: 0 };+ },+ /** Linear interpolate a→b by t (t not clamped). */+ lerp(a: Vec2, b: Vec2, t: number): Vec2 {+ return { x: a.x + (b.x - a.x) * t, y: a.y + (b.y - a.y) * t };+ },++ /** Angle in radians (atan2(y, x)). */+ angle(a: Vec2): number { return Math.atan2(a.y, a.x); },+ /** Vector from an angle (radians) and length. */+ fromAngle(radians: number, length = 1): Vec2 {+ return { x: Math.cos(radians) * length, y: Math.sin(radians) * length };+ },+ /** Rotate by `radians` about the origin. */+ rotate(a: Vec2, radians: number): Vec2 {+ const c = Math.cos(radians), s = Math.sin(radians);+ return { x: a.x * c - a.y * s, y: a.x * s + a.y * c };+ },+ /** Left perpendicular (90° CCW). */+ perp(a: Vec2): Vec2 { return { x: -a.y, y: a.x }; },++ equals(a: Vec2, b: Vec2, epsilon = 1e-6): boolean {+ return Math.abs(a.x - b.x) <= epsilon && Math.abs(a.y - b.y) <= epsilon;+ },+} as const;diff --git a/sdk/src/math/vec3.ts b/sdk/src/math/vec3.tsnew file mode 100644index 000000000..b2e9f9505--- /dev/null+++ b/sdk/src/math/vec3.ts@@ -0,0 +1,51 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file vec3.ts+ * @brief Vec3 helpers operating on the canonical `Vec3` ({x,y,z}) type. Pure:+ * every op returns a new Vec3. Exposed as the `v3` namespace.+ */++import type { Vec3 } from '../types';++export const v3 = {+ create(x = 0, y = 0, z = 0): Vec3 { return { x, y, z }; },+ clone(a: Vec3): Vec3 { return { x: a.x, y: a.y, z: a.z }; },++ add(a: Vec3, b: Vec3): Vec3 { return { x: a.x + b.x, y: a.y + b.y, z: a.z + b.z }; },+ sub(a: Vec3, b: Vec3): Vec3 { return { x: a.x - b.x, y: a.y - b.y, z: a.z - b.z }; },+ scale(a: Vec3, s: number): Vec3 { return { x: a.x * s, y: a.y * s, z: a.z * s }; },+ mul(a: Vec3, b: Vec3): Vec3 { return { x: a.x * b.x, y: a.y * b.y, z: a.z * b.z }; },+ neg(a: Vec3): Vec3 { return { x: -a.x, y: -a.y, z: -a.z }; },++ dot(a: Vec3, b: Vec3): number { return a.x * b.x + a.y * b.y + a.z * b.z; },+ cross(a: Vec3, b: Vec3): Vec3 {+ return {+ x: a.y * b.z - a.z * b.y,+ y: a.z * b.x - a.x * b.z,+ z: a.x * b.y - a.y * b.x,+ };+ },++ len(a: Vec3): number { return Math.hypot(a.x, a.y, a.z); },+ len2(a: Vec3): number { return a.x * a.x + a.y * a.y + a.z * a.z; },+ dist(a: Vec3, b: Vec3): number { return Math.hypot(a.x - b.x, a.y - b.y, a.z - b.z); },++ normalize(a: Vec3): Vec3 {+ const l = Math.hypot(a.x, a.y, a.z);+ return l > 0 ? { x: a.x / l, y: a.y / l, z: a.z / l } : { x: 0, y: 0, z: 0 };+ },+ lerp(a: Vec3, b: Vec3, t: number): Vec3 {+ return {+ x: a.x + (b.x - a.x) * t,+ y: a.y + (b.y - a.y) * t,+ z: a.z + (b.z - a.z) * t,+ };+ },++ equals(a: Vec3, b: Vec3, epsilon = 1e-6): boolean {+ return Math.abs(a.x - b.x) <= epsilon+ && Math.abs(a.y - b.y) <= epsilon+ && Math.abs(a.z - b.z) <= epsilon;+ },+} as const;diff --git a/sdk/tests/math.test.ts b/sdk/tests/math.test.tsnew file mode 100644index 000000000..c01b72d4a--- /dev/null+++ b/sdk/tests/math.test.ts@@ -0,0 +1,111 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { describe, it, expect } from 'vitest';+import { scalar } from '../src/math/scalar';+import { v2 } from '../src/math/vec2';+import { v3 } from '../src/math/vec3';++const close = (a: number, b: number, eps = 1e-9) => expect(Math.abs(a - b)).toBeLessThanOrEqual(eps);++describe('scalar', () => {+ it('clamp / clamp01', () => {+ expect(scalar.clamp(5, 0, 3)).toBe(3);+ expect(scalar.clamp(-1, 0, 3)).toBe(0);+ expect(scalar.clamp(2, 0, 3)).toBe(2);+ expect(scalar.clamp01(2)).toBe(1);+ expect(scalar.clamp01(-2)).toBe(0);+ });+ it('lerp / inverseLerp / remap', () => {+ expect(scalar.lerp(0, 10, 0.5)).toBe(5);+ expect(scalar.inverseLerp(0, 10, 5)).toBe(0.5);+ expect(scalar.inverseLerp(2, 2, 5)).toBe(0); // degenerate+ expect(scalar.remap(5, 0, 10, 0, 100)).toBe(50);+ expect(scalar.remap(5, 2, 2, 0, 100)).toBe(0); // degenerate in-range+ });+ it('deg/rad round-trip', () => {+ close(scalar.rad2deg(scalar.deg2rad(90)), 90);+ close(scalar.deg2rad(180), Math.PI);+ });+ it('approximately', () => {+ expect(scalar.approximately(1, 1 + 1e-9)).toBe(true);+ expect(scalar.approximately(1, 1.1)).toBe(false);+ });+ it('smoothstep clamps and eases', () => {+ expect(scalar.smoothstep(0, 1, -1)).toBe(0);+ expect(scalar.smoothstep(0, 1, 2)).toBe(1);+ expect(scalar.smoothstep(0, 1, 0.5)).toBe(0.5);+ });+ it('mod is euclidean (sign of divisor)', () => {+ expect(scalar.mod(-1, 4)).toBe(3);+ expect(scalar.mod(5, 4)).toBe(1);+ });+ it('sign', () => {+ expect(scalar.sign(-3)).toBe(-1);+ expect(scalar.sign(0)).toBe(0);+ expect(scalar.sign(3)).toBe(1);+ });+});++describe('v2', () => {+ it('add / sub / scale / mul / neg', () => {+ expect(v2.add({ x: 1, y: 2 }, { x: 3, y: 4 })).toEqual({ x: 4, y: 6 });+ expect(v2.sub({ x: 3, y: 4 }, { x: 1, y: 2 })).toEqual({ x: 2, y: 2 });+ expect(v2.scale({ x: 2, y: 3 }, 2)).toEqual({ x: 4, y: 6 });+ expect(v2.mul({ x: 2, y: 3 }, { x: 4, y: 5 })).toEqual({ x: 8, y: 15 });+ expect(v2.neg({ x: 1, y: -2 })).toEqual({ x: -1, y: 2 });+ });+ it('dot / cross', () => {+ expect(v2.dot({ x: 1, y: 0 }, { x: 0, y: 1 })).toBe(0);+ expect(v2.dot({ x: 2, y: 3 }, { x: 4, y: 5 })).toBe(23);+ expect(v2.cross({ x: 1, y: 0 }, { x: 0, y: 1 })).toBe(1);+ });+ it('len / len2 / dist / dist2', () => {+ expect(v2.len({ x: 3, y: 4 })).toBe(5);+ expect(v2.len2({ x: 3, y: 4 })).toBe(25);+ expect(v2.dist({ x: 0, y: 0 }, { x: 3, y: 4 })).toBe(5);+ expect(v2.dist2({ x: 0, y: 0 }, { x: 3, y: 4 })).toBe(25);+ });+ it('normalize (and zero vector → zero)', () => {+ expect(v2.normalize({ x: 3, y: 4 })).toEqual({ x: 0.6, y: 0.8 });+ expect(v2.normalize({ x: 0, y: 0 })).toEqual({ x: 0, y: 0 });+ });+ it('lerp', () => {+ expect(v2.lerp({ x: 0, y: 0 }, { x: 10, y: 20 }, 0.5)).toEqual({ x: 5, y: 10 });+ });+ it('angle / fromAngle round-trip', () => {+ const a = v2.fromAngle(Math.PI / 2, 2);+ close(a.x, 0); close(a.y, 2);+ close(v2.angle({ x: 0, y: 1 }), Math.PI / 2);+ });+ it('rotate 90deg', () => {+ const r = v2.rotate({ x: 1, y: 0 }, Math.PI / 2);+ close(r.x, 0); close(r.y, 1);+ });+ it('perp / equals', () => {+ expect(v2.perp({ x: 2, y: 3 })).toEqual({ x: -3, y: 2 });+ // left perpendicular of +X is +Y (equals tolerates the -0 component)+ expect(v2.equals(v2.perp({ x: 1, y: 0 }), { x: 0, y: 1 })).toBe(true);+ expect(v2.equals({ x: 1, y: 1 }, { x: 1 + 1e-9, y: 1 })).toBe(true);+ expect(v2.equals({ x: 1, y: 1 }, { x: 1.1, y: 1 })).toBe(false);+ });+});++describe('v3', () => {+ it('add / sub / scale / dot', () => {+ expect(v3.add({ x: 1, y: 2, z: 3 }, { x: 1, y: 1, z: 1 })).toEqual({ x: 2, y: 3, z: 4 });+ expect(v3.sub({ x: 1, y: 2, z: 3 }, { x: 1, y: 1, z: 1 })).toEqual({ x: 0, y: 1, z: 2 });+ expect(v3.scale({ x: 1, y: 2, z: 3 }, 2)).toEqual({ x: 2, y: 4, z: 6 });+ expect(v3.dot({ x: 1, y: 2, z: 3 }, { x: 4, y: 5, z: 6 })).toBe(32);+ });+ it('cross (right-handed)', () => {+ expect(v3.cross({ x: 1, y: 0, z: 0 }, { x: 0, y: 1, z: 0 })).toEqual({ x: 0, y: 0, z: 1 });+ });+ it('len / normalize', () => {+ expect(v3.len({ x: 2, y: 3, z: 6 })).toBe(7);+ expect(v3.normalize({ x: 0, y: 0, z: 0 })).toEqual({ x: 0, y: 0, z: 0 });+ });+ it('lerp / equals', () => {+ expect(v3.lerp({ x: 0, y: 0, z: 0 }, { x: 2, y: 4, z: 6 }, 0.5)).toEqual({ x: 1, y: 2, z: 3 });+ expect(v3.equals({ x: 1, y: 1, z: 1 }, { x: 1, y: 1, z: 1 + 1e-9 })).toBe(true);+ });+});