Hardon Collider Collision detection for LÖVE

function init(cell_size, callback_collide, callback_stop)^ top

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

function love.load()
    hardoncollider.init(150)
end

function setCallbacks(collide, stop)^ top

function setCallbacks{collide = collide, 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.

The callbacks have the following function prototype:

function callback(dt, shape_one, shape_two, mtv_x, mtv_y)

function collide_one(dt, shape_one, shape_two, mtv_x, mtv_y)
    print('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 collide_two(dt, shape_one, shape_two, mtv_x, mtv_y)
    print('colliding:', shape_one, shape_two)
    -- move only shape_one to resolve the collision
    shape_one:move(mtv_x, mtv_y)
end

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

function love.load()
    hardoncollider.init(100)
    -- set initial callbacks
    hardoncollider.setCallbacks(collide_one, stop)
    -- change persist callback
    hardoncollider.setCallbacks{collide = collide_two}
end

function update(dt)^ top

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

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

function love.update(dt)
    hardoncollider.update(dt, .02)
end

function setAutoUpdate(max_step, times)^ top

Automatically call hardoncollider.update(dt) after each love.update(dt).

Basically overwrites love.update(dt) with the following function:

function love.update(dt)
    _old_love_update(dt)
    hardoncollider.update(dt)
end

You can define a maximum time step. If dt is bigger than this step, the new update function will be called up to times times with a dt smaller or equal to the maximum time step:

local i = 1
    while dt > max_step do
    update(max_step)
    dt = dt - max_step
    i = i + 1
    if i > times then return end
end
update(dt)

If max_step is bigger than 1, it is assumed to declare a minimum frame rate.

If times is omitted, it is set to 1 and the code is equivalent to update(math.min(dt, max_step))

Once set, you can disable the auto update with setNoAutoUpdate(), but beware that this might break other libs that hook into love.update, e.g. hump.gamestate. To prevent unexpected side effects, it's best practice to call setAutoUpdate() after any other library hooked itself into love.update()

function love.load()
    HC.init(100, collision_start, collision_persist, collision_stop)
    game_init()
    HC.setAutoUpdate(30)
end

function setNoAutoUpdate()^ top

Resets love.update() to the state before calling setAutoUpdate().

if game_over then
    hardoncollider.setNoAutoUpdate()
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.

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.

rect = hardoncollider.addRectangle(100,120, 200,40)

function addCircle(cx, cy, radius)^ top

Add a circle shape to the collision detection system.

circle = hardoncollider.addCircle(400,300, 100)

function addPoint(x, y)^ top

Add a point shape to the collision detection system.

Point shapes are most useful for bullets or suchs, 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] = hardoncollider.addPoint(player.pos.x,player.pos.y)

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.

hardoncollider.remove(circle)

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

Add shapes to a group. Shapes in the same group will not collide with each other.

hardoncollider.addToGroup("platforms", platform1, platform2, platform3)

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

Remove shapes from a group.

hardoncollider.removeFromGroup("platforms", not_a_platform)

function 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 function exists purely for performance optimisation. Use it wisely. Good candidates for passive shapes are traps and terrain.

Note: Shapes are active by default

hardoncollider.setPassive(ground, bridge, spikes)

function setActive(shape, ...)^ top

Makes shapes active again.

Note: Shapes are active by default

hardoncollider.setActive(collapsing_bridge)

function setGhost(shape, ...)^ top

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

if cheat.set_ghost then
    hardoncollider.setGhost(player)
end

function setSolid(shape, ...)^ top

Makes a shape opaque. Shapes that were ghosts before will be subject to collision again.

if cheat.set_no_ghost then
    hardoncollider.setSolid(player_recording)
end

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

class 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.

shape = shapes.PolygonShape(100,100, 200,200, 300,100)

class CircleShape(cx,cy, radius)^ top

Construct a circular shape.

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

class PointShape(x,y)^ top

Construct a point shape.

shape = shapes.PointShape(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 -- laser pointer hits player
    local intersectionPoint = vector(x,y) + t * vector(dx,dy)
    player:addMark(intersectionPoint)
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.

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

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 center of the shape.

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 circumscribing circle.

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

function shape:draw(mode)^ top

Draw the shape either filled or as outline.

circle:draw('fill')

function shape:collidesWith(other)^ top

Test if two shapes collide.

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

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

Construct a polygon.

At least three points that are not collinear (being 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.

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

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:getBBox()^ top

Get axis aligned bounding box.

x1,y1,x2,y2 = poly:getBBox()
-- 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

function polygon:move(direction)

Move a polygon in a direction. You can either use coordinates x,y or a hump vector.

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

function polygon:rotate(angle)^ top

function polygon:rotate(angle, cx, cy)

function polygon:rotate(angle, center)

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

For defining a rotation center, you can either use coordinate form cx,cy or a hump vector.

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 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

Spatialhash(cell_size)^ top

Create a new spatial hash given a 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 one cell only.

hash = spatialhash.Spatialhash(150)

hash = spatialhash(150)

function hash:cellCoords(v)^ top

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

coords = hash:cellCoords(vector(love.mouse.getPosition()))

function hash:cell(v)^ top

Get the cell a given vector would be placed in. This is an actual cell, not the index.

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

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

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

cell = hash:cell(vector(love.mouse.getPosition()))

function hash:insert(obj, ul, lr)^ top

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

hash:insert(shape, vector(-100,-100), vector(0,-30))

function hash:remove(obj, ul, lr)^ top

function hash:remove(obj)

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, vector(-100,-100), vector(0,-30))

hash:remove(object_with_unknown_position)

function hash:update(obj, ul_old, lr_old, ul_new, lr_new)^ top

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

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

function hash:getNeighbors(obj, ul, lr)^ top

Query for neighbors of an object given it's bounding box.

local others = hash:getNeighbors(obj, vector(-100,-70), vector(0,0))
for _,other in pairs(others) do
    obj:pushAway(other)
end