Skip to Content
defold-typescript
Get startedGuidesAPILibraries
Core concepts

Vector math

Defold exposes vector arithmetic through Lua metamethods on vector3, vector4, quaternion, and matrix4. In TypeScript the same operations are typed as methods, not operators: a.add(b) instead of a + b. The TypeScript-to-Lua transpiler turns these calls into the underlying metamethod invocations at build time, so the runtime cost is identical.

Vector3

const a: Vector3 = vmath.vector3(1, 2, 3);
const b: Vector3 = vmath.vector3(4, 5, 6);

const sum: Vector3 = a.add(b);       // a + b
const diff: Vector3 = a.sub(b);      // a - b
const scaled: Vector3 = a.mul(2);    // a * 2 (scalar)
const halved: Vector3 = a.div(2);    // a / 2 (scalar)
const negated: Vector3 = a.unm();    // unary minus — see the gotchas page

mul and div take a scalar number, not another Vector3. Component-wise multiplication is not built in; do it explicitly with vmath.vector3(a.x * b.x, a.y * b.y, a.z * b.z).

Vector4

The same shape as Vector3, with an extra w component:

const v: Vector4 = vmath.vector4(0, 0, 0, 1);
const w: Vector4 = vmath.vector4(1, 0, 0, 0);
const sum: Vector4 = v.add(w);

Quaternion

Quaternion.mul composes two quaternions:

const q1: Quaternion = vmath.quat_axis_angle(vmath.vector3(0, 1, 0), Math.PI / 2);
const q2: Quaternion = vmath.quat_axis_angle(vmath.vector3(1, 0, 0), Math.PI / 4);
const composed: Quaternion = q1.mul(q2);

Matrix4

Matrix4.mul is overloaded: matrix × matrix returns Matrix4, matrix × Vector4 returns Vector4. Matrix × Vector3 is intentionally a type error — promote the vector to Vector4 first.

const m: Matrix4 = vmath.matrix4_translation(vmath.vector3(1, 0, 0));
const m2: Matrix4 = m.mul(m);
const transformed: Vector4 = m.mul(vmath.vector4(0, 0, 0, 1));

A worked example: the platformer

The eight engine types (Vector3, Hash, Url, Quaternion, Matrix4, Vector, Vector4, Opaque<…>) are ambient globals — no import needed, mirroring the namespace ergonomics (vmath, go, sprite, …). The committed docs/examples/platformer/src/player.ts puts the whole pattern on one screen: the fixed_update body uses the chained method form for whole-vector arithmetic, plain +/* on number fields for component access, and a vmath.project namespace function that returns a scalar with a method-form argument. The last line comes from the handle_obstacle_contact collision helper, not the per-frame loop, so the three snippets do not all share one function body.

// docs/examples/platformer/src/player.ts — `fixed_update(self, dt)`
self.velocity.x = self.velocity.x + accel * self.input_direction * dt; // component access: plain TS arithmetic on number
self.velocity.y = self.velocity.y + gravity * dt;

const pos = go.get_position().add(self.velocity.mul(dt)).add(self.adj);
go.set_position(pos);

const proj = vmath.project(self.correction, normal.mul(distance));

Whole-vector operations read left-to-right as a chain of Vector3 methods (go.get_position().add(self.velocity.mul(dt))); per-component reads and writes (self.velocity.x = self.velocity.x + accel * …) stay plain TS because each component is a number.

Why not v3 + v3?

TypeScript's binary +, -, *, / operators require both operands to be number (or + accepts string). The type-checker rejects v3a + v3b with TS2362/TS2365 because Vector3 is not assignable to either, so writing the operator form fails to compile and you cannot ship code that would crash at runtime.

There is one exception: unary minus. TypeScript does not flag -v3a; it silently produces number. This is a TS-level gap the toolchain cannot close with types alone. The typed alternative is v.unm(). See unary minus on Vector3 silently produces number on the gotchas page for the full story.

On this page