Xmath Usage

Using xmath for Zero-Allocation Math in Defold

Prerequisite: Verify xmath Dependency

Before applying any guidance from this skill, you MUST confirm that the project uses xmath. Check the game.project file for a dependency URL containing thejustinwalsh/defold-xmath (e.g. dependencies#N = https://github.com/thejustinwalsh/defold-xmath/archive/...). Alternatively, check for the presence of xmath/ in the .deps/ directory.

If neither an xmath dependency in game.project nor a local xmath module is found, do NOT apply this skill. Inform the user that the project does not use xmath and suggest adding the dependency:

Copy code
[project]
dependencies#N = https://github.com/thejustinwalsh/defold-xmath/archive/refs/heads/main.zip

Core Concept: In-Place Mutation to Eliminate Heap Allocations

Standard vmath creates a new Lua object on every operation, causing constant GC pressure in hot loops:

luaCopy code
-- BAD: vmath allocates 3 new objects every frame
function update(self, dt)
    local v = self.dir * 5 * dt    -- alloc #1
    local pos = go.get_position()  -- alloc #2
    local result = pos + v         -- alloc #3
    go.set_position(result)
end

xmath mutates an existing variable in place — the result is written into the first argument. You allocate once, reuse forever:

luaCopy code
-- GOOD: xmath reuses pre-allocated variables, zero allocations per frame
go.property("dir", vmath.vector3(0, 1, 0))

local v = vmath.vector3()  -- allocate ONCE at module scope

function update(self, dt)
    local pos = go.get_position()
    xmath.mul(v, self.dir, 5 * dt)  -- writes into v
    xmath.add(v, pos, v)            -- writes into v
    go.set_position(v)
end

Key Rules

1. Pre-allocate scratch variables at module scope or in init() — never inside update() or on_message().
2. The output variable is always the first argument — this is the fundamental calling convention difference from vmath.
3. Functions return nothing — you cannot chain calls. Use a scratch variable at each step.
4. Use vmath to create initial objects — vmath.vector3(), vmath.vector4(), vmath.quat(), vmath.matrix4() to allocate scratch buffers, then use xmath to operate on them.
5. Type polymorphism — functions like xmath.lerp work for vector3, vector4, and quaternion based on the output argument type.

Optimization Pattern

luaCopy code
-- Scratch variables — allocated once
local temp_v = vmath.vector3()
local temp_q = vmath.quat()

function update(self, dt)
    -- Instead of: local dir = vmath.normalize(target - pos)
    xmath.sub(temp_v, self.target, self.pos)
    xmath.normalize(temp_v, temp_v)  -- can use same variable as both input and output

    -- Instead of: local rot = vmath.quat_rotation_z(angle)
    xmath.quat_rotation_z(temp_q, self.angle)

    -- Instead of: local rotated = vmath.rotate(rot, dir)
    xmath.rotate(temp_v, temp_q, temp_v)
end

Full API Reference

All functions write the result into the first argument. No return values.

Vector Operations (vector3 / vector4)

Interpolation (vector3 / vector4 / quaternion)

Quaternion Operations

Matrix Operations (matrix4)