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.

docs: add Math Helpers guide (v2/v3/col/scalar)

yhhfa3179a6cf36
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index 63863f42d..93257684e 100644
--- a/docs/astro/astro.config.mjs
+++ b/docs/astro/astro.config.mjs
@@ -82,6 +82,13 @@ export default defineConfig({
{ label: 'Networking', translations: { 'zh-CN': '联网' }, slug: 'guides/networking' },
],
},
+ {
+ label: 'Utilities',
+ translations: { 'zh-CN': '工具' },
+ items: [
+ { label: 'Math Helpers', translations: { 'zh-CN': '数学辅助' }, slug: 'guides/math' },
+ ],
+ },
{
label: 'Reference',
translations: { 'zh-CN': '参考' },
diff --git a/docs/astro/src/content/docs/guides/math.mdx b/docs/astro/src/content/docs/guides/math.mdx
new file mode 100644
index 000000000..e8873bce0
--- /dev/null
+++ b/docs/astro/src/content/docs/guides/math.mdx
@@ -0,0 +1,80 @@
+---
+title: Math Helpers
+description: Vector, color, and scalar math on the engine's canonical types.
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+The SDK ships small math namespaces — `v2` / `v3` (vectors), `col` (colors), and
+`scalar` (numbers) — that operate on the same canonical types your components use
+(`{x, y}` vectors, `{r, g, b, a}` colors in 0..1). Every helper is **pure**: it
+returns a new value and never mutates its inputs.
+
+## Vectors
+
+`v2` covers 2D vector math; `v3` mirrors the core operations for 3D.
+
+```typescript
+import { v2 } from 'esengine';
+
+// Move a point by a velocity over dt.
+const next = v2.add(pos, v2.scale(vel, dt));
+
+// Aim: unit direction from pos to target, then a step of length speed*dt.
+const dir = v2.normalize(v2.sub(target, pos));
+const step = v2.scale(dir, speed * dt);
+
+v2.dist(pos, target); // distance (for a range check)
+v2.fromAngle(Math.PI / 2, 10); // { x: 0, y: 10 }
+v2.rotate({ x: 1, y: 0 }, Math.PI); // { x: -1, y: 0 }
+```
+
+- Arithmetic: `add` / `sub` / `scale` / `mul` (component-wise) / `neg`.
+- Products & length: `dot`, `cross`, `len` / `len2`, `dist` / `dist2`.
+- Direction: `normalize`, `angle`, `fromAngle`, `rotate`, `perp` (90° CCW).
+- Also: `create`, `clone`, `lerp`, `equals` (epsilon compare).
+
+## Colors
+
+`col` builds and blends colors on the `{r, g, b, a}` (0..1) convention — white is
+`{1, 1, 1, 1}`. The namespace is `col` because the bare `color` name is already an
+SDK export.
+
+```typescript
+import { col } from 'esengine';
+
+col.rgb(1, 0, 0); // opaque red (0..1 channels)
+col.from255(255, 128, 0); // from 0..255 channels
+col.fromHex('#ff8800'); // #rgb / #rgba / #rrggbb / #rrggbbaa
+
+col.lerp(red, blue, 0.5); // blend halfway (e.g. a damage flash)
+col.withAlpha(white, 0.3); // fade
+col.multiply(base, tint); // per-channel tint
+```
+
+- Build: `create`, `rgb`, `from255`, `fromHex` (throws on malformed input), `clone`.
+- Blend: `lerp`, `withAlpha`, `multiply`, `scaleRgb`; serialize with `toHex`.
+
+## Scalars
+
+`scalar` collects the common number helpers for gameplay and tuning:
+
+```typescript
+import { scalar } from 'esengine';
+
+scalar.clamp01(hp / maxHp); // 0..1
+scalar.lerp(a, b, 0.25); // interpolate
+scalar.remap(x, 0, 100, 0, 1); // rescale one range onto another
+scalar.smoothstep(0, 1, t); // eased 0..1 ramp
+scalar.deg2rad(90); // degrees -> radians
+```
+
+Also: `clamp`, `inverseLerp`, `rad2deg`, `approximately`, `mod`, `sign`.
+
+<Aside type="tip">
+ Results use the same canonical types as components, so they drop straight in —
+ e.g. `transform.position = v2.add(transform.position, step)` or
+ `sprite.color = col.withAlpha(sprite.color, a)` — no conversion needed. Because
+ the helpers allocate a new object per call, hoist them out of hot inner loops
+ where you're counting allocations.
+</Aside>
diff --git a/docs/astro/src/content/docs/zh-cn/guides/math.mdx b/docs/astro/src/content/docs/zh-cn/guides/math.mdx
new file mode 100644
index 000000000..ceaf9301f
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/guides/math.mdx
@@ -0,0 +1,77 @@
+---
+title: 数学辅助
+description: 在引擎的规范类型上做向量、颜色与标量运算。
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+SDK 附带了几个小的数学命名空间——`v2` / `v3`(向量)、`col`(颜色)、`scalar`(数值)
+——它们操作的正是你组件里用的那套规范类型(`{x, y}` 向量、0..1 的 `{r, g, b, a}` 颜色)。
+每个辅助函数都是**纯函数**:返回新值,绝不修改入参。
+
+## 向量
+
+`v2` 覆盖 2D 向量运算;`v3` 为 3D 提供同样的核心运算。
+
+```typescript
+import { v2 } from 'esengine';
+
+// Move a point by a velocity over dt.
+const next = v2.add(pos, v2.scale(vel, dt));
+
+// Aim: unit direction from pos to target, then a step of length speed*dt.
+const dir = v2.normalize(v2.sub(target, pos));
+const step = v2.scale(dir, speed * dt);
+
+v2.dist(pos, target); // distance (for a range check)
+v2.fromAngle(Math.PI / 2, 10); // { x: 0, y: 10 }
+v2.rotate({ x: 1, y: 0 }, Math.PI); // { x: -1, y: 0 }
+```
+
+- 四则:`add` / `sub` / `scale` / `mul`(逐分量)/ `neg`。
+- 点积/长度:`dot`、`cross`、`len` / `len2`、`dist` / `dist2`。
+- 方向:`normalize`、`angle`、`fromAngle`、`rotate`、`perp`(逆时针 90°)。
+- 还有:`create`、`clone`、`lerp`、`equals`(带 epsilon 的比较)。
+
+## 颜色
+
+`col` 在 `{r, g, b, a}`(0..1)约定上构造与混合颜色——白色是 `{1, 1, 1, 1}`。命名空间
+叫 `col` 是因为裸的 `color` 名字已经是一个 SDK 导出。
+
+```typescript
+import { col } from 'esengine';
+
+col.rgb(1, 0, 0); // opaque red (0..1 channels)
+col.from255(255, 128, 0); // from 0..255 channels
+col.fromHex('#ff8800'); // #rgb / #rgba / #rrggbb / #rrggbbaa
+
+col.lerp(red, blue, 0.5); // blend halfway (e.g. a damage flash)
+col.withAlpha(white, 0.3); // fade
+col.multiply(base, tint); // per-channel tint
+```
+
+- 构造:`create`、`rgb`、`from255`、`fromHex`(格式非法时抛错)、`clone`。
+- 混合:`lerp`、`withAlpha`、`multiply`、`scaleRgb`;用 `toHex` 序列化。
+
+## 标量
+
+`scalar` 汇集了玩法与数值调校常用的数值辅助:
+
+```typescript
+import { scalar } from 'esengine';
+
+scalar.clamp01(hp / maxHp); // 0..1
+scalar.lerp(a, b, 0.25); // interpolate
+scalar.remap(x, 0, 100, 0, 1); // rescale one range onto another
+scalar.smoothstep(0, 1, t); // eased 0..1 ramp
+scalar.deg2rad(90); // degrees -> radians
+```
+
+还有:`clamp`、`inverseLerp`、`rad2deg`、`approximately`、`mod`、`sign`。
+
+<Aside type="tip">
+ 返回值用的是和组件一样的规范类型,可以直接落回去——例如
+ `transform.position = v2.add(transform.position, step)` 或
+ `sprite.color = col.withAlpha(sprite.color, a)`,无需转换。因为每次调用都会分配一个
+ 新对象,在计较分配次数的热点内循环里请把它们提到循环外。
+</Aside>