Wiki

Back to Beyond the Codea in-app reference

Codea's user-defined types

Lua has eight basic types: nil, boolean, number, string, function, userdata, thread, and table. Codea extends Lua with the following user-defined types:

Key for metatable in Lua's registery	Type constructor(s)	Use
body	`physics.body(shapeType, ...)`	Represents a dynamic rigid body.
codeaimage	`image(width, height)`; `image(data)`	Represents a raster image.
codeasoundbuffer	`soundbuffer(data, format, freq)`	Represents a sound buffer containing arbitrary audio data.
color	`color(r, g, b, a)`	Represents a colour.
contact	None	Represents a collision between two bodies. Such a value is passed to the global function `collide(physics.contact)`.
joint	`physics.joint(type, ...)`	Represents a joint that constrains two rigid bodies together.
matrix	`matrix(a11, a21, a31, ..., a24, a34, a44)`	Represents a 4 x 4 matrix.
mesh	`mesh()`	Represents a triangle mesh.
shader	`shader()`	Represents a shader.
touch	None	Represents a touch. Global variable `CurrentTouch` refers to such a value.
vec2	`vec2(x, y)`	Represents a two-dimensional vector.
vec3	`vec3(x, y, z)`	Represents a three-dimensional vector.
vec4	`vec4(x, y, z, w)`	Represents a four-dimensional vector.

Extending Codea's user-defined types

With some exceptions in previous versions of Codea, you can extend Codea's user-defined types by adding keys and values to the metatable of the userdata. For example:

do
    local mt = getmetatable(vec4())
    mt["unpack"] = function (self) return self.x, self.y, self.z, self.w end
end

v1 = vec4(1, 2, 3, 4)
print(v1:unpack()) -- generates output: 1   2   3   4

By default, indexing the userdata returns the value of the corresponding key in the userdata's metatable.

Exceptions prior to Codea version 1.4.5 are the userdata returned by the color() function or referred to by the CurrentTouch global variable. In those cases, by default, indexing the userdata returns nil. For example:

do
    local mt = getmetatable(color())
    mt["unpack"] = function (self) return self.r, self.g, self.b, self.a end
end

c1 = color(255, 255, 0, 255)
print(type(c1["unpack"]) -- generates output: nil
print(c1:unpack()) -- generates an error

This can be overcome by enhancing the function referenced by the __index key in the userdata's metatable. For example:

-- Enhance the function referenced by __index
do
    local mt = getmetatable(color())
    local oldLget = mt["__index"]    -- preserve old Lget
    mt["__index"] = function (t, k)
        local v = oldLget(t, k)      -- try the old Lget
        if v then return v end       -- if it works, then return the result
        return mt[k]                 -- otherwise, look in the metatable
    end
end

Note this isn't required from Codea version 1.4.5.

Once __index is enhanced, other extensions should then work. For example:

do
    local mt = getmetatable(color())
    mt["unpack"] = function(self) return self.r, self.g, self.b, self.a end
end

c1 = color(255, 255, 0, 255)
print(c1:unpack())            -- generates output: 255   255   0   255