melonjs-math
Use this skill for vector and matrix maths in melonJS — Vector2d, Vector3d, their observable variants, Matrix2d, Matrix3d, and the math utility functions. Covers which methods mutate and which allocate, the vector pool and when clone() is the wrong tool, interpolation with lerp, slerp, damp and moveTowards, and the argument defaults that silently drop a component. Triggers on: Vector2d, Vector3d, ObservableVector2d, ObservableVector3d, Matrix2d, Matrix3d, vector, vector maths, dot, cross, normalize, length, distance, angle, lerp, slerp, damp, moveTowards, project, clamp, degToRad, radToDeg, clone, vector pool, vector3dPool, setMuted, setCallback, my vector is wrong, z is zero, scale ignores z., moveTowards ignores z, projectN, currentTransform, setTransform, matrix, transform matrix, column-major, val, Float32Array, basis matrix, orientation matrix, Noise, getNoise1d, flicker, wobble.
melonjs · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add melonjs/melonJS --skill melonjs-math技能说明
name: melonjs-math description: "Use this skill for vector and matrix maths in melonJS — Vector2d, Vector3d, their observable variants, Matrix2d, Matrix3d, and the math utility functions. Covers which methods mutate and which allocate, the vector pool and when clone() is the wrong tool, interpolation with lerp, slerp, damp and moveTowards, and the argument defaults that silently drop a component. Triggers on: Vector2d, Vector3d, ObservableVector2d, ObservableVector3d, Matrix2d, Matrix3d, vector, vector maths, dot, cross, normalize, length, distance, angle, lerp, slerp, damp, moveTowards, project, clamp, degToRad, radToDeg, clone, vector pool, vector3dPool, setMuted, setCallback, my vector is wrong, z is zero, scale ignores z., moveTowards ignores z, projectN, currentTransform, setTransform, matrix, transform matrix, column-major, val, Float32Array, basis matrix, orientation matrix, Noise, getNoise1d, flicker, wobble." license: MIT
Vectors, matrices and maths
The one rule that explains most surprises
Methods mutate this and return it. They do not return a new vector.
const a = new Vector3d(1, 0, 0);
const b = new Vector3d(0, 1, 0);
a.cross(b); // a IS NOW the cross product; the original a is gone
a.add(b).normalize().scale(3, 3, 3); // chains, all in place
That is what makes the API allocation-free, and it is the opposite of what a functional style expects. If you need to keep the original, copy into something you own first:
out.copy(a).cross(b); // a untouched, nothing allocated
The exceptions are named. A handful of methods return a NEW vector, and
each has a *Self sibling that does not:
| allocates a new vector | mutates in place |
|---|---|
negate() | negateSelf() |
floor() | floorSelf() |
ceil() | ceilSelf() |
clamp(low, high) | clampSelf(low, high) |
clone() | copy(v) |
So v.negate() in a per-frame loop allocates every frame and v.negateSelf()
does not. The names are the only clue; nothing in the call site shows it.
clone() comes from a pool, and only pays off if you give it back
clone() is vector3dPool.get(...). A pool is fast when instances come back:
get() takes a free one and resets it. Nothing comes back on its own, so a
clone that is simply dropped makes get() miss, construct, and write two
registry entries.
Measured, 3M operations:
out.copy(a).cross(b) | 39ms |
new Vector3d(ax, ay, az).cross(b) | 37ms |
a.clone().cross(b) | 2919ms |
So:
- Transient value inside a function? Use a module-level scratch vector, or
new Vector3d(). Notclone(). - Keeping it, then done with it?
clone()andvector3dPool.release(v)when finished. Releasing is what makes the pool a pool. - Writing a helper that returns a vector? Take an optional
out:
const cross = (a, b, out = new Vector3d()) => out.copy(a).cross(b);
That is the engine's own convention, and it lets a hot caller supply scratch while a casual one ignores it.
A returned value can never be shared scratch. The next call overwrites something the caller is still holding, and nothing fails loudly:
const _t = new Vector3d();
const bad = (v) => _t.copy(v).normalize(); // WRONG: two calls alias
Argument defaults that drop a component
Three signatures quietly discard what you did not pass. All three are reachable by writing the obvious thing.
scale(x, y = x, z = 1) — z defaults to 1, not to x. A uniform
scale has to say so three times:
v.scale(2); // (1,2,3) -> (2,4,3) z UNTOUCHED
v.scale(2, 2, 2); // (1,2,3) -> (2,4,6) what you meant
set(x, y, z = 0) — setting two components zeroes the third:
v.set(10, 20); // z is now 0, whatever it was
Vector3d.pos on a renderable is typed Vector2d. Renderable.pos is an
ObservableVector3d at run time but is declared through Polygon as a
Vector2d, so .z, .setMuted and .setCallback need a cast from
TypeScript. See issue #1510.
cross is two different functions
v3.cross(other); // Vector3d: MUTATES v3, returns this
v2.cross(other); // Vector2d: returns a NUMBER, mutates nothing
The 2D one is the z component of the 3D cross, which is the useful scalar for "which side is this on". Same name, different shape, different return.
Interpolation: four of them, and they are not interchangeable
a.lerp(b, t); // straight line, t in 0..1
a.slerp(b, t); // along the ARC, constant angular rate
a.damp(b, lambda, dt); // frame-rate independent ease toward b
a.moveTowards(b, step); // fixed distance per call, never overshoots
moveTowards is X/Y ONLY, on Vector3d as well as Vector2d. It is the
one of the four that is not 3D: it measures the distance from dx and dy,
steps along atan2(dy, dx), and leaves z exactly where it was. The source
says so in a comment and the JSDoc says "on the x and y axis", but the name
gives no hint, and in a list like the one above it reads as the sibling of the
other three. Anything moving in three dimensions wants damp or an explicit
step; reach for moveTowards only when the motion really is planar.
lerp between two directions is uneven: it slows at the ends, runs fast
through the middle, and shortens the vector as it passes halfway. Anything
whose direction matters more than its components wants slerp — a camera
swinging to look somewhere, a turret tracking, a body moving over a sphere.
slerp carries length linearly, so two unit vectors give a unit vector and
nothing needs normalising afterwards.
damp is the one to use for "ease toward a target every frame", because
lerp(current, target, 0.1) per frame is frame-rate dependent: it converges
twice as fast at 120fps as at 60.
project scales THIS, and projectN is the one without the divide
a.project(b) does not return the component of a along