hardoncollider^ top

The main module.

HardonCollider will automatically handle - but not resolve - collisions. It uses search data structure - a spatial hash - to quickly find colliding shapes.

A spatial hash is simply a grid that is laid over the whole scene in which a shape can occupy several cells. To find shapes that may be colliding, you simply need to look which shapes occupy the same cell. You can specify the cell size in the init function.

To get a less boring explanation on how to use this, see the tutorial (once it's there)

function init(cell_size, callback_start, callback_persist, callback_stop)^ top

Initializes the library. Call this in love.load(). All the parameters can be omitted.

Parameters:
number cell_size (100)
Cell size for internal search structure.
function callback_start (empty function)
Called when two shapes start colliding.
function callback_persist (empty function)
Called when two continue to collide, i.e. if the collision lasts more than one frame.
function callback_stop (empty function)
Called when two shapes stop colliding.
Returns:
Nothing
Example: 
function love.load()
    hardoncollider.init(150)
end
function setCallbacks(start,persist,stop)^ top
function setCallbacks{start = start,persist = persist,stop = stop}

Sets the different callbacks. The second calling style let's you specify the callbacks by name, see the example.

If nil is passed as any callback, the callback will not be changed.

Each callback has the prototype function callback(dt, shape_one, shape_two, mtv_x, mtv_y). The two shape parameters are the colliding shapes. The last two parameters, mtv_x and mtv_y define the minimum translation vector, i.e. the direction and magnitude shape_one has to be moved so that the collision will be resolved.

Parameters:
function start
Called when two shapes start colliding.
function persist
Called when two continue to collide, i.e. if the collision lasts more than one frame.
function stop
Called when two shapes stop colliding.
Returns:
Nothing
Example: 
function start(dt, shape_one, shape_two, mtv_x, mtv_y)
    print('started colliding:', shape_one, shape_two)
	print('mtv:', mtv_x, mtv_y)
end

function persist_one(dt, shape_one, shape_two, mtv_x, mtv_y)
    print('still colliding:', shape_one, shape_two)
    -- move both shape_one and shape_two to resolve the collision
    shape_one:move(mtv_x/2, mtv_y/2)
    shape_two:move(-mtv_x/2, -mtv_y/2)
end

function persist_two(dt, shape_one, shape_two, mtv_x, mtv_y)
    print('still colliding:', shape_one, shape_two)
    -- move only shape_one to resolve the collision
    shape_one:move(mtv_x, mtv_y)
end

function stop(dt, shape_one, shape_two) -- ignore the translation vector
    print('collision resolved')
end

function love.load()
    hardoncollider.init(100)
    -- set initial callbacks
    hardoncollider.setCallbacks(start, persist_one, stop)
    -- change persist callback
    hardoncollider.setCallbacks{persist = persist_two}
end
function addPolygon(x1,y1, ..., xn,yn)^ top

Add a polygon to the collision detection system. Any non-intersection polygon will work, even convex polygons.

Note that if three consecutive points lie on a line, the middle point will be discarded. This means you cannot construct polygon shapes out of lines.

Parameters:
numbers x1,y1, ..., xn,yn
The corners of the polygon. At least three corners (that do not lie on a line) are needed.
Returns:
Shape
The polygon shape added to the scene.
Example: 
shape = hardoncollider.addPolygon(10,10, 40,50, 70,10, 40,30)
function addRectangle(x, y, w, h)^ top

Add a rectangle shape to the collision detection system.

Parameters:
numbers x, y
The upper left corner of the rectangle.
numbers w, h
The width and height of the rectangle.
Returns:
Shape
The rectangle added to the scene.
Example: 
rect = hardoncollider.addRectangle(100,120, 200,40)
function addCircle(cx, cy, radius)^ top

Add a circle shape to the collision detection system.

Parameters:
numbers cx, cy
The circle center.
number radius
The circle radius.
Returns:
Shape
The circle added to the scene.
Example: 
circle = hardoncollider.addCircle(400,300, 100)
function update(dt, max_delta)^ top

Checks for collisions and call callbacks. Use this in love.update(dt).

A maximum time delta can be specified. dt will be chopped up in slices not bigger than this maximum and the scene is updated for each time slice.

Note that the delta time has no effect on the collision detection itself, but will be passed to the callback functions.

Parameters:
number dt
The time since the last update.
number max_delta
Maximum time delta (see description).
Returns:
Nothing
Example: 
function love.update(dt)
    hardoncollider.update(dt, .02)
end
function remove(shape)^ top

Remove a shape from the collision detection system. Note that if you remove a shape in the start or persist callback, other shapes might still have collided with it, so the shape will be argument to the other calls of start or persist. In any case, the stop callback will be called in the next call to update for each shape which the removed shape collided with.

Parameters:
Shape shape
The shape to be removed.
Returns:
Nothing
Example: 
hardoncollider.remove(circle)
hardoncollider.shape^ top

Shape classes with collision detection methods.

This defines methods to move, rotate and draw shapes created with hardoncollider.add*.

If you don't want to use the full blown module, you can still use these classes to test for colliding shapes.

They might also be useful for doing GUI stuff, e.g. when testing if the mouse hovers a button.

Some functions (getAxes, projectOn, ...) are left undocumented, as they have little value outside the scope of collision detection.

PolygonShape(x1,y1, ..., xn,yn)^ top
PolygonShape(polygon)

Construct a shape using a non-intersecting ploygon

You can either specify the coordinates as with hardoncollider.addPolygon() or use an instance of the Polygon class.

Parameters:
numbers x1,y1, ..., xn,yn
The corners of the polygon. At least three corners (that do not lie on a line) are needed.
Polygon polygon
Construct the shape from this convex polygon.
Returns:
Shape
The constructed shape.
Example: 
shape = PolygonShape( Polygon(100,100, 200,200, 300,100) )
class CompoundShape(polygon)^ top

Construct a shape using a non intersecting polygon. If the polygon is convex, using PolygonShape might be faster.

Parameters:
Polygon polygon
Construct the shape from this polygon.
Returns:
Shape
The constructed shape.
Example: 
shape = CompoundShape( Polygon(10,10, 40,50, 70,10, 40,30) )
class CircleShape(cx,cy, radius)^ top

Construct a circular shape.

Parameters:
numbers cx, cy
The circle center.
number radius
The circle radius.
Returns:
Shape
The constructed circle shape.
Example: 
shape = CircleShape(400,300, 100)
function shape:move(x, y)^ top

Move the shape.

Parameters:
numbers x, y
The direction to move the shape in.
Returns:
Nothing
Example: 
circle:move(10,15) -- move the circle 10 pixels down and 15 pixels right
function shape:rotate(angle, cx,cy)^ top

Rotate the shape. A rotation center can be specified. If no center is given, the shape's center is used.

Parameters:
number angle
Amount to rotate the shape (in radians).
numbers cx, cy
Rotation center. Defaults to the shape's center if omitted.
Returns:
Nothing
Example: 
rectangle:rotate(math.pi/4)
function shape:center()^ top

Get the center of the shape.

If the shape is a CircleShape, this is the circle center, else it's the polygon's centroid.

Parameters:
None
Returns:
numbers x, y
The center of the shape.
Example: 
print("Circle at:", circle:center())
function shape:draw(mode)^ top

Draw the shape either filled or as outline.

Parameters:
DrawMode mode
How to draw the shape. Either 'line' or 'fill'.
Returns:
Nothing
Example: 
circle:draw('fill')
function shape:collidesWith(other)^ top

Test if two shapes collide.

Parameters:
Shape other
Test for collision with this shape.
Returns:
boolean collide
true if the two shapes collide, false otherwise.
vector mtv
The minimum translation vector, or nil if the two shapes don't collide.
Example: 
if circle:collidesWith(rectangle) then
    print("collision detected!")
end
hardoncollider.polygon^ top

To be documented later

hardoncollider.spatialhash^ top

To be documented later