Lua logo

Preface

This is the reference manual of MoonCCD, which is a Lua binding library for Daniel Fiser’s libccd collision detection library. [1]

It is assumed that the reader is familiar with both libccd and the Lua programming language.

For convenience of reference, this document contains external (deep) links to the Lua Reference Manual.

Getting and installing

For installation intructions, refer to the README file in the MoonCCD official repository on GitHub.

Module organization

The MoonCCD module is loaded using Lua’s require() and returns a table containing the functions it provides (as usual with Lua modules). This manual assumes that such table is named ccd, i.e. that it is loaded with:

 ccd = require("moonccd")

but nothing forbids the use of a different name.

Examples

Complete examples can be found in the examples/ directory of the release package.

License

MoonCCD is released under the MIT/X11 license (same as Lua, and with the same only requirement to give proper credits to the original author). The copyright notice is in the LICENSE file in the base directory of the official repository on GitHub.

See also

MoonCCD is part of MoonLibs, a collection of Lua libraries for graphics and audio programming.

Introduction

MoonCCD is an almost one-to-one Lua binding library to the libccd collision detection library. This means that by and large, it is intended to be used as the underlying libccd (apart from coding in Lua, of course).

If not stated otherwise, on error all MoonCCD functions raise a Lua error. If needed, this behaviour can be overridden by wrapping function calls in the standard Lua pcall( ).

Collision detection functions

In the following, the ccdpar argument contains the parameters and support functions to be used by the collision detection functions (which are also available as methods of the ccdpar object itself). The arguments obj1 and obj2 are the user-defined geometrical representations of the two possibly-colliding convex objects, and may be of any Lua type (for example a table including the type, dimensions, position, and orientation of the object).

  • boolean = gjk_intersect(ccdpar, obj1, obj2)
    boolean = mpr_intersect(ccdpar, obj1, obj2)
    boolean = ccdpar:gjk_intersect(obj1, obj2)
    boolean = ccdpar:mpr_intersect(obj1, obj2)
    Return true if the two objects intersect, false otherwise.

  • boolean, sep = gjk_separate(ccdpar, obj1, obj2)

  • boolean, sep = ccdpar:gjk_separate(obj1, obj2)
    Return true followed by the separation vector sep if the two obiects intersect. Return false otherwise.
    sep: vec3, represents the minimal translation of obj2 to separate it from obj1.

  • boolean, depth, dir, pos = gjk_penetration(ccdpar, obj1, obj2)
    boolean, depth, dir, pos = mpr_penetration(ccdpar, obj1, obj2)
    boolean, depth, dir, pos = ccdpar:gjk_penetration(obj1, obj2)
    boolean, depth, dir, pos = ccdpar:mpr_penetration(obj1, obj2)
    Return true followed by penetration information if the two obiects intersect. Return false otherwise.
    depth (float), dir (vec3), pos (vec3): penetration depth, direction and position in global coordinates.
    (By translating obj2 in the given direction, the two object should have touching contact.)

  • ccdpar = new(par)
    Creates a new object encapsulating a ccd_t structure, initialized with the given parameters.
    The par argument is a table containing the fields below, whose meanings are the same as those of the corresponding fields of the ccd_t struct.
    All fields are optional in this constructor, but they may be required by the collision detection function the ccpar is passed to.
    par.max_iterations: integer (defaults to infinitely many).
    par.epa_tolerance: float (defaults to 10-4).
    par.mpr_tolerance: float (defaults to 10-4).
    par.dist_tolerance: float (defaults to 10-6).
    par.first_dir: function, called as dir = f(obj1, obj2).
    par.center1: function, called as center = f(obj1).
    par.center2: function, called as center = f(obj2).
    par.support1: function called as support = f(obj1, dir).
    par.support2: function called as support = f(obj2, dir).
    dir, center, support: vec3.
    obj1, obj2: any Lua type (user defined).

  • free(ccdpar)
    ccdpar:free( )
    Free the given ccdpar object.
    (The object is automatically free’d at exit, including on error.)

Float utilities

  • s = sign(a)
    boolean = is_zero(a)
    boolean = eq(a, b)
    a, b: float.
    s: -1, 0, or 1.

Vector utilities

  • v = origin( )
    {vec3} = points_on_sphere( )
    boolean = veq(v1, v2)
    float = vlen2(v)
    float = vdist2(v1, v2)
    v = vcopy(v1)
    v = vsub(v1, v2)
    v = vadd(v1, v2)
    v = vscale(v1, float)
    v = vnormalize(v)
    float = vdot(v1, v2)
    v = vcross(v1, v2)
    v = vrotate(v1, quat)
    v, v1, v2: vec3.

  • boolean, witness = point_segment_dist2(P, a, b)
    boolean, witness = point_triangle_dist2(P, a, b, c)
    P, a, b, c, witness: vec3.
    (witness is nil when the first returned value is false).

Quaternion utilities

  • float = qlen(q)
    float = qlen2(q)
    q = qcopy(q1)
    q = qnormalize(q1)
    q = qscale(q1, float)
    q = qmul(q1, q2)
    q = qinvert(q1)
    q = qset_angle_axis(angle, axis)
    q, q1, q2: quat.
    angle: float (radians).
    axis: vec3.

Data types

In this document, the float and integer types denote Lua numbers, while other types such as boolean, string, etc denote standard Lua types. Note that float here just means 'floating point' as opposed to 'integer', and does not imply single-precision (all numbers are actually represented internally using double-precision).

Angles are always expressed in radians.

Vectors and quaternions are by default represented as Lua arrays containing float elements. The meaning of the elements thus depends on their position, as detailed below, and there is no syntactic sugar such as v.x and v.y to access them (unless one enables GLMATH compatibility).

  • vec3 = {x, y, z}
    All elements are floats.
    (Rfr: ccd_vec3_t)

  • quat = {w x, y, z}
    All elements are floats (note that the w component is in the first position).
    (Rfr: ccd_quat_t)

GLMATH compatibility

As an option, it is possible to instruct MoonCCD to return vectors and quaternions as the corresponding MoonGLMATH types, instead of returning them as plain tables (which is the default). [2]

(Notice that for function arguments nothing changes, since MoonGLMATH types are compatible with the corresponding plain tables used by default, thus they can be used as function arguments in any case).

Use the following functions to control GLMATH compatibility:

  • glmath_compat(boolean)
    Enables/disables GLMATH compatibility (which by default is disabled).
    Enabling this functionality requires MoonGLMATH to be installed.

  • boolean = is_glmath_compat( )
    Returns true if GLMATH compatibility is enabled.

1. This manual is written in AsciiDoc, rendered with AsciiDoctor and a CSS from the AsciiDoctor Stylesheet Factory.
2. MoonGLMATH types are convenient because they support operators and synctatic sugar, but I chose not to impose their use because one may want to use an alternative math library, or none at all.