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): SDK scalar/Vec2/Vec3 helper library on canonical types (T4)

yhh62dcab1fdf28
diff --git a/sdk/src/core-sys.ts b/sdk/src/core-sys.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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);
+ });
+});