HC.spatialhash

spatialhash = require 'HC.spatialhash'

A spatial hash implementation that supports scenes of arbitrary size. The hash is sparse, which means that cells will only be created when needed.

class Spatialhash([cellsize = 100])
Arguments:
  • cellsize (number) – Width and height of a cell (optional).

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.

Note

The syntax depends on used class system. The shown syntax works when using the bundled hump.class or slither.

Example:

Spatialhash = require 'hardoncollider.spatialhash'
hash = Spatialhash(150)
Spatialhash:cellCoords(x, y)
Arguments:
  • x, y (numbers) – The position to query.
Returns:

Coordinates of the cell which would contain x,y.

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

Example:

local mx,my = love.mouse.getPosition()
cx, cy = hash:cellCoords(mx, my)
Spatialhash:cell(i, k)
Arguments:
  • i, k (numbers) – The cell index.
Returns:

Set of objects contained in the cell.

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

Example:

local mx,my = love.mouse.getPosition()
cx, cy = hash:cellCoords(mx, my)
cell = hash:cell(cx, cy)
Spatialhash:cellAt(x, y)
Arguments:
  • x, y (numbers) – The position to query.
Returns:

Set of objects contained in the cell.

Get the cell that contains point x,y.

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

Example:

local mx,my = love.mouse.getPosition()
cell = hash:cellAt(mx, my)
Spatialhash:shapes()
Returns:Set of all shapes in the hash.

Get all shapes that are recorded in the hash.

Spatialhash:inSameCells(x1, y1, x2, y2)
Arguments:
  • x1,y1 (numbers) – Upper left corner of the query bounding box.
  • x2,y2 (numbers) – Lower right corner of the query bounding box.
Returns:

Set of all shapes in the same cell as the bbox.

Get the shapes that are in the same cell as the defined bounding box.

Spatialhash:register(obj, x1, y1, x2, y2)
Arguments:
  • obj (mixed) – Object to place in the hash. It can be of any type except nil.
  • x1,y1 (numbers) – Upper left corner of the bounding box.
  • x2,y2 (numbers) – Lower right corner of the bounding box.

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

Example:

hash:register(shape, shape:bbox())
Spatialhash:remove(obj[, x1, y1[, x2, y2]])
Arguments:
  • obj (mixed) – The object to delete
  • x1,y1 (numbers) – Upper left corner of the bounding box (optional).
  • x2,y2 (numbers) – Lower right corner of the bounding box (optional).

Remove an object from the hash using a bounding box.

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

Example:

hash:remove(shape, shape:bbox())
hash:remove(object_with_unknown_position)
Spatialhash:update(obj, x1, y1, x2, y2, x3, y3, x4, y4)
Arguments:
  • obj (mixed) – The object to be updated.
  • x1,y1 (numbers) – Upper left corner of the bounding box before the object was moved.
  • x2,y2 (numbers) – Lower right corner of the bounding box before the object was moved.
  • x3,y3 (numbers) – Upper left corner of the bounding box after the object was moved.
  • x4,y4 (numbers) – Lower right corner of the bounding box after the object was moved.

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

Example:

hash:update(shape, -100,-30, 0,60, -100,-70, 0,20)
Spatialhash:draw(draw_mode[, show_empty = true[, print_key = false]])
Arguments:
  • draw_mode (string) – Either ‘fill’ or ‘line’. See the LÖVE wiki.
  • show_empty (boolean) – Wether to draw empty cells (optional).
  • print_key (boolean) – Wether to print cell coordinates (optional).

Draw hash cells on the screen, mostly for debug purposes

Example:

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