Codea Extension Libraries



Creative Commons License


  1. Home

  2. 1. Colours

  3. 2. Vectors

    1. 2.1. General Vector Methods

    2. 2.2. vec2

    3. 2.3. vec3

    4. 2.4. vec4

    5. 2.5. quat

    6. 2.6. matrix

    7. 2.7. Native Codea Functions

    8. 2.8. math

    9. 2.9. Utilities

  4. 3. Meshes

    1. 3.1. The Solids

    2. 3.2. PseudoMesh

Over the years that I've been enjoying programming with Codea, I've written an awful lot of code. Quite a bit has ended up in libraries that I reuse a lot; so I have code that handles touches, a user interface, bézier curves, fireworks, and other things that I use more than once. Pretty much all of this is public, because why not?, but I suspect that most of it is too tied to my way of working to be easily usable by others. The bits that might be are my extension libraries. These take built-in objects in Codea and add extra functionality. Because they work with existing objects, they probably would be more readily integrated into others' code than the rest of my stuff.

There are three key extension libraries (links are to the files on github):

As much as for myself as others, I'm going to document the extensions here.

1 Colours

The following describes the extensions available for the color userdata. In this, a variable starting with a c refers to an existing color object.

2 Vectors

My vector extension library grew fairly organically. It started as a set of classes implementing vector-like objects, such as complex numbers. Once I learned about the ability to extend objects via metatables, I rebuilt the classes as extensions. This does mean that there is a bit of legacy code which exists to avoid backwards incompatibility in some of my programs.

This code provides the following extensions:

  1. vec2s are promoted to complex numbers

  2. vec4s are promoted to quaternions (this was written before the quat userdata was added to Codea)

  3. quats have extra methods added to make them more usable

  4. vec3s interact with quaternions and matrices

  5. matrix has extra methods added to interact better with other objects

  6. native Codea functions such as line are adapted to take suitable vector inputs

  7. math functions are adapted to take suitable vector inputs

  8. some utility functions are provided

2.1 General Vector Methods

All the vector types (vec2, vec3, vec4, and quat) have the following methods added:

2.2 vec2

In all these, variable v denotes an existing vec2 object.

2.3 vec3

The primary extensions to the vec3 userdata are to allow them to be transformed by various other things.

2.4 vec4

Before the quat userdata was introduced, I used vec4s as quaternions. I still have legacy code that uses vec4 instead of quat so I keep this code around for the time being.

2.5 quat

When this was first written, the quat userdata wasn't available until the setup function was started, meaning that I had to provide a wrapper around it. So the quaternion creation function is called __quat. This could now be removed and all __quat replaced by quat, I just haven't gotten round to that as yet.

2.6 matrix

The matrix userdata is extended so that multiplication and rotation can take multiple types.

2.7 Native Codea Functions

Various native Codea functions are extended to take more inputs.

2.8 math

The various math functions are extended, generally to allow more types of input.

2.9 Utilities

3 Meshes

The extensions to the mesh userdata all began life as separate functions, but once I learnt about metatables then I adapted them to methods. I still kept the original functions and made the methods wrappers around them, mainly for laziness and legacy code. With the advent of Codea Craft, I added the PseudoMesh class so that these solids could be used as models for craft entities.

The methods all work by taking in a table of configuration options. Most options have defaults. There are some options common to all solids.

3.1 The Solids

3.2 PseudoMesh

The PseudoMesh class exists to convert all the above shapes to models that can be used with Codea Craft. It can be used as a drop in for a mesh, and then provides a method p:toModel() which converts the structure to a Craft model.

Because meshes and models handle normals slightly differently, it can be that the model ends up with its normals pointing the wrong way. To correct that, use p:invertNormals() before converting to a model.

This code also defines the function extendModel() which adds the following to the craft.model object:

These can be used as, for example craft.model.cylinder(t) to get a cylindrical model.