Skip to content
This repository


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

A collision detection library for Lua



Lua collision-detection library for axis-aligned boxes. Its main features are:

  • Handles axis-aligned boxes only (no circles, polygons, etc)
  • Strives to be fast and have a very small memory footprint
  • Detects collisions and collision stops
  • When a collision occurs, the lib provides a minimal displacement vector

It tries to be a minimal HardonCollider .

Bump only does axis-aligned box collisions. If you need anything more complicated than that (circles, polygons, etc.) give HardonCollider a look.

Other than that, feel free to poke around!


local bump = require 'bump'

-- The grid cell size can be specified via the initialize method
-- By default, the cell size is 32

-- bump has 4 callbacks:
-- * collision is called every time a collision occurs
-- * endCollision is called every time a collision ends
-- * getBBox must accept an item and return its bounding box: left, top, width and height
-- * shouldCollide is used to skip collisions
-- None of the callbacks is mandatory.
-- collision and stopCollision do nothing by default.
-- getBBox calls item:getBBox() by default

function bump.collision(item1, item2, dx, dy)
  print(, "collision with",, "displacement vector:", dx, dy)

function bump.endCollision(item1, item2)
  print(, "stopped colliding with",

function bump.getBBox(item)
  return item.l, item.t, item.w, item.h

function bump.shouldCollide(item1, item2)
  return true -- we could add certain conditions here - for example, make objects of the same group not collide

-- here we create two rectangles
local rect1 = {name="rect1", l=0  , t=0, w=100, h=100} -- name, left, top, width, height
local rect2 = {name="rect2", l=300, t=0, w=100, h=100}

-- insert both rectangles into the lib

-- Now every time we call bump.collide() it will call bump.collision/endCollision appropiatedly.
-- bump.collide() is usually called once per "update" cycle in a game. But you could also invoke it directly if
-- you wanted. For example:

bump.collide() -- nothing happens, there are no collisions

rect2.l = 50 -- move rect2 so it collides with rect1

bump.collide() -- prints "rect1 started colliding with rect2 displacement vector: -50 0"

rect2.l = 100 -- move rect2 so it does not collide any more with rect1

bump.collide()  -- prints "rect1 stopped colliding with rect2"


Just copy the bump.lua file wherever you want it. Then require it where you need it:

local bump = require 'bump'

If you copied bump.lua to a file not accesible from the root folder (for example a lib folder), change the code accordingly:

local bump = require 'lib.bump'

Please make sure that you read the license, too (for your convenience it’s now included at the beginning of the bump.lua file.


There is a demo in the demo branch of this repository:

You will need LÖVE in order to try it.

Something went wrong with that request. Please try again.