Hardon Collider Collision detectionction for LÖVE

function new(cell_size, callback_collide, callback_stop)^top

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

Note: The cell size does not determine the granularity of the collision detection, but is an optimization parameter. Values that are too small or too big will have a negative impact on the detection speed. The meaning of too small and too big depends on the size of the shapes in the collision detection.

Collider = require 'hardoncollider'
function love.load()
    HC = Collider.new(150)
    -- or: HC = Collider(150)
end

function HC:clear()^top

Remove all shapes from the collider instance.

function game:leave()
    HC:clear()
end

function HC:setCallbacks(collide, stop)^top

Sets the collision callbacks.

If nil is passed for either argument, the corresponding callback will not be changed.

The callbacks must have the following function prototype:

function callback(dt, shape_one, shape_two, dx, dy)

shape_one and shape_two are the colliding shapes and dx and dy define the separating vector, i.e. the direction and magnitude shape_one has to be moved so that the collision will be resolved. Note that if one of the shapes is a point shape, the translation vector will be invalid.

Collider = require 'hardoncollider'

function collide(dt, shape_one, shape_two, dx, dy)
    print('colliding:', shape_one, shape_two)
    print('mtv:', dx, dy)
    -- move both shape_one and shape_two to resolve the collision
    shape_one:move(dx/2, dy/2)
    shape_two:move(-dx/2, -dy/2)
end

function colliding_two(dt, shape_one, shape_two, dx, dy)
    print('colliding:', shape_one, shape_two)
    -- move only shape_one to resolve the collision
    shape_one:move(dx, dy)
end

-- ignore the translation vector

function stop(dt, shape_one, shape_two)
    print('collision resolved')
end

function love.load()
    HC = Collider()
    -- set initial callbacks
    HC:setCallbacks(collide)
    -- add stop callback
    HC:setCallbacks(nil, stop)
    -- change collide callback
    HC:setCallbacks(collide_two)
end

function HC:update(dt)^top

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

Note: dt has no effect on the collision detection itself, but will be passed to the callback functions.

function love.update(dt)
    HC:update(dt)
end

function HC:addPolygon(x1,y1, ..., xn,yn)^top

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

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

shape = HC:addPolygon(10,10, 40,50, 70,10, 40,30)

function HC:addRectangle(x, y, w, h)^top

Add a rectangle shape to the collision detection system.

Note: Shape transformations, e.g. shape:moveTo() and shape:rotate(), will be with respect to the rectangle center, not to the upper left corner.

rect = HC:addRectangle(100,120, 200,40)

function HC:addCircle(cx, cy, radius)^top

Add a circle shape to the collision detection system.

circle = HC:addCircle(400,300, 100)

function HC:addPoint(x, y)^top

Add a point shape to the collision detection system.

Point shapes are most useful for bullets and such, because detecting collisions between a point and any other shape is a little faster than detecting collision between two non-point shapes. In case of a collision, the callback will not receive a valid minimum translation vector.

bullets[#bulltes+1] = HC:addPoint(player.pos.x,player.pos.y)

function HC:addShape(shape)^top

Add a custom shape to the collision detection system.

The shape must implement two functions for this to work:

function shape:bbox()
    return corners-of-axis-aligned-bounding-box
end

and

function shape:collidesWith(other)
    local colliding = ...
    local sx,sy = separating-vector(self, other)
    return colliding, sx,sy
end

The shape will be augmented with the function shape:neighbors().

AABB = {x = ..., y = ..., width = ..., height = ...}

function AABB:bbox()
    return self.x, self.y, self.x+self.width, self.y+self.height
end

function AABB:collidesWith(other)
    return magic
end

AABB = HC:addShape(AABB)

function HC:remove(shape, ...)^top

Remove a shape from the collision detection system. Note that if you remove a shape in the collide() callback, it will still be an argument to the stop() callback in the next frame.

HC:remove(circle)
HC:remove(enemy1, enemy2)

function HC:addToGroup(group, shape, ...)^top

Add shapes to a group. Shapes in the same group will not emit collision callbacks when colliding with each other.

HC:addToGroup("platforms", platform1, platform2, platform3)
HC:removeFromGroup("platforms", platform1)

function HC:removeFromGroup(group, shape, ...)^top

Remove shapes from a group.

HC:addToGroup("platforms", platform1, platform2, platform3)
HC:removeFromGroup("platforms", platform1)

function HC:setPassive(shape, ...)^top

Sets shape to be passive. Passive shapes will be subject to collision detection, but will not actively search for collision candidates. This means that if two passive shapes collide, no collision callback will be invoked (in fact, the collision won't even be detected).

This enables you to significantly speed up the collision detection. Typical candidates for passive shapes are those which are numerous, but don't act in themselves, e.g. the level geometry.

Note: Added shapes are active by default.

HC:setPassive(ground, bridge, spikes)

function HC:setActive(shape, ...)^top

Flags a shape active.

Note: Added shapes are active by default.

HC:setActive(collapsing_bridge)

function HC:activeShapes()^top

Iterator over all active shapes. Mostly for internal use.

-- rotate all active shapes
for shape in HC:activeShapes() do
    shape:rotate(dt)
end

function HC:setGhost(shape, ...)^top

Makes a shape permeable: Ghost shapes will not collide with any other shape.

-- make player invincible for 5 seconds
HC:setGhost(player)
Timer.add(5, function() HC:setSolid(player) end)

function HC:setSolid(shape, ...)^top

Makes a permeable shape solid again.

-- make player invincible for 5 seconds
HC:setGhost(player)
Timer.add(5, function() HC:setSolid(player) end)

function HC:shapesAt(x,y)^top

Retrieve a list of shapes covering the point (x,y), i.e. all shapes that contain (x,y). This includes active, passive, solid and ghost shapes.

-- select the units under the mouse cursor
function love.mousereleased(x,y,btn)
    for _, shape in ipairs(HC:shapesAt(x,y)) do
        shape.object:select()
    end
end

function HC:shapesInRange(x1,y1, x2,y2)^top

Returns all shapes contained in the rectangle (x1,y1)-(x2,y2). Useful for RTS-style unit selection to select shapes to draw (see example).

-- draw only visible shapes
local width = love.graphics.getWidth()
local height = love.graphics.getHeight()
for shape in pairs(HC:shapesInRange(0,0, width,height) do
    shape.object:draw()
end

function newPolygonShape(x1,y1, ..., xn,yn)^top

Construct a shape using a non-self-intersecting ploygon.

The corresponding classes are available as shapes.ConvexPolygonShape and shapes.ConcavePolygonShape.

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

shape = shapes.newPolygonShape(100,100, 200,200, 300,100)
shape2 = shapes.newPolygonShape(shape)

function newCircleShape(cx,cy, radius)^top

Construct a circular shape.

The corresponding class is available as shapes.CircleShape.

shape = shapes.newCircleShape(400,300, 100)

function newPointShape(x,y)^top

Construct a point shape.

The corresponding class is available as shapes.PointShape.

shape = shapes.newPointShape(400,300)

function shape:contains(x, y)^top

Test if the shape contains a given point.

if unit.shape:contains(love.mouse.getPosition) then
    unit:setHovered(true)
end

function shape:intersectsRay(x, y, dx, dy)^top

Test if the shape intersects a ray.

local intersecting, t = player:intersectsRay(x,y, dx,dy)
if intersecting then
    -- find point of intersection
    local vx,vy = vector.add(x, y, vector.mul(t, dx, dy))
    player:addMark(vx,vy)
end

function shape:move(x, y)^top

Move the shape.

circle:move(10,15) -- move the circle 10 units right and 15 units down

function shape:moveTo(x, y)^top

Set the shape's position.

Important: This function moves the shape's center to (x,y). It is equivalent to:

local cx,cy = shape:center()
shape:move(x-cx, y-cy)

circle:moveTo(400,300) -- move circle to screen center

function shape:scale(s)^top

Scale the shape relative to it's center.

circle:scale(2) -- double the circle's size

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.

rectangle:rotate(math.pi/4)

function shape:setRotation(angle, cx,cy)^top

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

Equivalent to:

shape:rotate(angle - shape.rotation, cx,cy)

rectangle:setRotation(math.pi, 100,100)

function shape:center()^top

Get the shape's center.

If the shape is a CircleShape, returns the circle center. In case of a point shape, returns the position. Else returns the polygon's centroid.

print("Circle at:", circle:center())

function shape:rotation()^top

Get the shape's rotation angle in radians.

print("Box rotation:", box:rotation())

function shape:outcircle()^top

Get circle that fully contains the shape.

if player:hasShield() then
    -- draw shield
    love.graphics.circle('line', player:outcircle())
end

function shape:bbox()^top

Get axis aligned bounding box.

-- draw bounding box
local x1,y1, x2,y2 = shape:bbox()
love.graphics.rectangle('line', x1,y1, x2-x1,y2-y1)

function shape:draw(mode)^top

Draw the shape either filled or as outline.

circle:draw('fill')

function shape:support(dx,dy)^top

Get furthest vertex of the shape with respect to the direction dx, dy.

Used in the collision detection algorithm, but may be useful for other things - e.g. lighting - too.

-- get vertices that produce a shadow volume
local x1,y1 = circle:support(lx, ly)
local x2,y2 = circle:support(-lx, -ly)

function shape:collidesWith(other)^top

Test if two shapes collide.

if circle:collidesWith(rectangle) then
    print("collision detected!")
end

function shape:neighbors()^top

Only available in shapes created with main module (i.e. HC:addRectangle(), ...).

Iterator over neighboring shapes.

-- check for collisions with neighboring shapes
for other in shape:neighbors() do
    if shape:collidesWith(other) then
        print("collision detected!")
    end
end

class Polygon(x1,y1, ..., xn,yn)^top

Syntax depends on used class system. Shown syntax works for bundled hump.class and slither.

Construct a polygon.

At least three points that are not collinear (i.e. lying on a straight line) are needed to construct the polygon. If there are collinear points, these points will be removed so that the overall shape of the polygon is not changed.

Polygon = require 'hardoncollider.polygon'
poly = Polygon(10,10, 40,50, 70,10, 40,30)

function polygon:unpack()^top

Get the polygon's vertices. Useful for drawing with love.graphics.polygon().

love.graphics.draw('line', poly:unpack())

function polygon:clone()^top

Get a copy of the polygon.

Since Lua uses references when simply assigning an existing polygon to a variable, unexpected things can happen when operating on the variable. Consider this code:

p1 = Polygon(10,10, 40,50, 70,10, 40,30)
p2 = p1
p3 = p1:clone()
p2:rotate(math.pi) -- p1 will be rotated, too!
p3:rotate(-math.pi) -- only p3 will be rotated

copy = poly:clone()
copy:move(10,20)

function polygon:bbox()^top

Get axis aligned bounding box.

x1,y1,x2,y2 = poly:bbox()
-- draw bounding box
love.graphics.rectangle('line', x1,y2, x2-x1, y2-y1)

function polygon:isConvex()^top

Test if a polygon is convex, i.e. a line line between any two points inside the polygon will lie in the interior of the polygon.

-- split into convex sub polygons
if not poly:isConvex() then
    list = poly:splitConvex()
else
    list = {poly:clone()}
end

function polygon:move(x,y)^top

Move a polygon in a direction..

poly:move(10,-5) -- move 10 units right and 5 units up

function polygon:rotate(angle, cx, cy)^top

Rotate the polygon. You can define a rotation center. If it is omitted, the polygon will be rotated around it's centroid.

p1:rotate(math.pi/2)          -- rotate p1 by 90° around it's center
p2:rotate(math.pi/4, 100,100) -- rotate p2 by 45° around the point 100,100

function polygon:triangulate()^top

Split the polygon into triangles.

triangles = poly:triangulate()
for i,triangle in ipairs(triangles) do 
    triangles.move(math.random(5,10), math.random(5,10))
end 

function polygon:splitConvex()^top

Split the polygon into convex sub polygons.

convex = concave_polygon:splitConvex()
function love.draw()
    for i,poly in ipairs(convex) do
        love.graphics.polygon('fill', poly:unpack())
    end
end

function polygon:mergedWith(other)^top

Create a merged polygon of two polygons if, and only if the two polygons share one complete edge. If the polygons share more than one edge, the result may be erroneous.

This function does not change either polygon, but rather create a new one.

merged = p1:mergedWith(p2)

function polygon:contains(x, y)^top

Test if the polygon contains a given point.

if button:contains(love.mouse.getPosition()) then
    button:setHovered(true)
end

function polygon:intersectsRay(x, y, dx, dy)^top

Test if the polygon intersects a ray.

if poly:intersectsRay(400,300, dx,dy) then
    love.graphics.setLine(2) -- highlight polygon
end

class Spatialhash(cellsize)^top

Syntax depends on used class system. Shown syntax works for bundled hump.class and slither.

Create a new spatial hash with a given cell size.

Choosing a good cell size depends on your application. To get a decent speedup, the average cell should not contain too many objects, nor should a single object occupy too many cells. A good rule of thumb is to choose the cell size so that the average object will occupy only one cell.

Spatialhash = require 'hardoncollider.spatialhash'
hash = Spatialhash(150)

function hash:cellCoords(x,y)^top

Get coordinates of a given value, i.e. the cell index in which a given point would be placed.

local mx,my = love.mouse.getPosition()
cx, cy = hash:cellCoords(mx, my)

function hash:cell(i,k)^top

Get the cell with given coordinates.

A cell is a table which's keys and value are the objects stored in the cell, i.e.:

cell = {
    [obj1] = obj1,
    [obj2] = obj2,
    ...
}

You can iterate over the objects in a cell using pairs():

for object in pairs(cell) do stuff(object) end

local mx,my = love.mouse.getPosition()
cx, cy = hash:cellCoords(mx, my)
cell = hash:cell(cx, cy)

function hash:cellAt(x,y)^top

Get the cell that contains point x,y.

Same as hash:cell(hash:cellCoords(x,y))

local mx,my = love.mouse.getPosition()
cell = hash:cellAt(mx, my)

function hash:insert(obj, x1,y1, x2,y2)^top

Insert an object into the hash using a given bounding box.

hash:insert(shape, shape:bbox())

function hash:remove(obj, x1,y1, x2,y2)^top

Remove an object from the hash using a bounding box.

If no bounding box is given, search the whole hash to delete the object.

hash:remove(shape, shape:bbox())
hash:remove(object_with_unknown_position)

function hash:update(obj, x1,y1, x2,y2, x3,y3, x4,y4)^top

Update an objects position given the old bounding box and the new bounding box.

hash:update(shape, -100,-30, 0,60, -100,-70, 0,20)

function hash:inRange(x1,y1, x2,y2)^top

Query objects in the rectangle (x1,y1) - (x2,y2).

local objects = hash:inRange(0,0, 800,600)
for obj in pairs(objects) do
    obj:draw()
end

function hash:rangeIter(x1,y1, x2,y2)^top

Iterator to objects in the rectangle (x1,y1) - (x2,y2).

Alias to pairs(hash:inRange(x1,y1, x2,y2)).

for obj in hash:rangeIter(0,0, 800,600) do
    obj:draw()
end

function hash:draw(draw_mode, show_empty, print_key)^top

Draw hash cells on the screen, mostly for debug purposes

love.graphics.setColor(160,140,100,100)
hash:draw('line', true, true)
hash:draw('fill', false)