hump Helper Utilities for More Productivity

function new()^top

Declare a new gamestate. A gamestate can define several callbacks.

menu = Gamestate.new()

function switch(to, ...)^top

Switch to a gamestate, with any additional arguments passed to the new state.

Switching a gamestate will call the leave() callback on the current gamestate, replace the current gamestate with to, call the init() function if the state was not yet inialized and finally call enter(old_state, ...) on the new gamestate.

Gamestate.switch(game, level_two)

function <callback>(...)^top

Calls a function on the current gamestate. Can be any function, but is intended to be one of the callbacks. Mostly useful when not using registerEvents().

function love.draw()
    Gamestate.draw() -- <callback> is `draw'
end

function love.update(dt)
    Gamestate.update(dt) -- pass dt to currentState:update(dt)
end

function love.keypressed(key, code)
    Gamestate.keypressed(key, code) -- pass multiple arguments
end

function registerEvents(callbacks)^top

Overwrite love callbacks to call Gamestate.update(), Gamestate.draw(), etc. automatically. love callbacks (e.g. love.update()) are still invoked.

This is by done by overwriting the love callbacks, e.g.:

local old_update = love.update
function love.update(dt)
    old_update(dt)
    return Gamestate.current:update(dt)
end

Note: Only works when called in love.load() or any other function that is executed after the whole file is loaded.

function love.load()
    Gamestate.registerEvents()
    Gamestate.switch(menu)
end

-- love callback will still be invoked
function love.update(dt)
    Timer.update(dt)
    -- no need for Gamestate.update(dt)
end

function love.load()
    -- only register draw, update and quit
    Gamestate.registerEvents{'draw', 'update', 'quit'}
    Gamestate.switch(menu)
end

function new()^top

If you don't need multiple independent schedulers, you can use the global/default timer (see examples).

Creates a new timer instance that is independent of the global timer: It will manage it's own list of scheduled functions and does not in any way affect the the global timer. Likewise, the global timer does not affect timer instances.

Note: Timer instances use the colon-notation (e.g. instance:update(dt)), while the global timer uses the dot-notation (e.g. Timer.update(dt)).

menuTimer = Timer.new()

function add(delay, func)^top

Schedule a function. The function will be executed after delay seconds have elapsed, given that update(dt) is called every frame.

Note: There is no guarantee that the delay will not be exceeded, it is only guaranteed that the function will not be executed before the delay has passed.

func will receive itself as only parameter. This is useful to implement periodic behavior (see the example).

-- grant the player 5 seconds of immortality
player.isInvincible = true
Timer.add(5, function() player.isInvincible = false end)

-- print "foo" every second. See also addPeriodic()
Timer.add(1, function(func) print("foo") Timer.add(1, func) end)

--Using a timer instance:
menuTimer:add(1, finishAnimation)

function addPeriodic(delay, func)^top

Add a function that will be called count times every delay seconds.

If count is omitted, the function will be called until it returns false or cancel(handle) or clear() is called.

-- toggle light on and off every second
Timer.addPeriodic(1, function() lamp:toggleLight() end)

-- launch 5 fighters in quick succession (using a timer instance)
mothership_timer:addPeriodic(0.3, function() self:launchFighter() end, 5)

-- flicker player's image as long as he is invincible
Timer.addPeriodic(0.1, function()
    player:flipImage()
    return player.isInvincible
end)

function do_for(delay, func, after)^top

Run func(dt) for the next delta seconds. The function is called every time update(dt) is called. Optionally run after() once delta seconds have passed.

after() will receive itself as only parameter.

Note: You should not add new timers in func(dt), as this can lead to random crashes.

-- play an animation for 5 seconds
Timer.do_for(5, function(dt) animation:update(dt) end)

-- shake the camera for one second
local orig_x, orig_y = camera:pos()
Timer.do_for(1, function()
    camera:lookAt(orig_x + math.random(-2,2), orig_y + math.random(-2,2))
end, function()
    -- reset camera position
    camera:lookAt(orig_x, orig_y)
end)

player.isInvincible = true
-- flash player for 3 seconds
local t = 0
player.timer:do_for(3, function(dt)
    t = t + dt
    player.visible = (t % .2) < .1
end, function()
    -- make sure the player is visible after three seconds
    player.visible = true
    player.isInvincible = false
end)

function cancel(handle)^top

Prevent a timer from being executed in the future.

function tick()
    print('tick... tock...')
end
handle = Timer.addPeriodic(1, tick)
-- later
Timer.cancel(handle) -- NOT: Timer.cancel(tick)

function clear()^top

Remove all timed and periodic functions. Functions that have not yet been executed will discarded.

Timer.clear()

menu_timer:clear()

function update(dt)^top

Update timers and execute functions if the deadline is reached. Use this in love.update(dt).

function love.update(dt)
    do_stuff()
    Timer.update(dt)
end

-- using hump.gamestate and a timer instance
function menuState:update(dt)
    self.timer:update(dt)
end

function new(x,y)^top

Create a new vector.

function isvector(v)^top

Test whether a variable is a vector.

if not vector.isvector(v) then
    v = vector(v,0)
end

function vector:clone()^top

Copy a vector. Simply assigning a vector a vector to a variable will create a reference, so when modifying the vector referenced by the new variable would also change the old one:

a = vector(1,1) -- create vector
b = a           -- b references a
c = a:clone()   -- c is a copy of a
b.x = 0         -- changes a,b and c
print(a,b,c)    -- prints '(1,0), (1,0), (1,1)'

copy = original:clone()

function vector:unpack()^top

Extract coordinates.

x,y = pos:unpack()

love.graphics.draw(self.image, self.pos:unpack())

function vector:permul(other)^top

Multiplies vectors coordinate wise, i.e. result = vector(a.x * b.x, a.y * b.y).

This does not change either argument vectors, but creates a new one.

scaled = original:permul(vector(1,1.5))

function vector:len()^top

Get length of a vector, i.e. math.sqrt(vec.x * vec.x + vec.y * vec.y).

distance = (a - b):len()

function vector:len2()^top

Get squared length of a vector, i.e. vec.x * vec.x + vec.y * vec.y.

-- get closest vertex to a given vector
closest, dsq = vertices[1], (pos - vertices[1]):len2()
for i = 2,#vertices do
    local temp = (pos - vertices[i]):len2()
    if temp < dsq then
        closest, dsq = vertices[i], temp
    end
end

function vector:dist(other)^top

Get distance of two vectors. The same as (a - b):len().

-- get closest vertex to a given vector
-- slightly slower than the example using len2()
closest, dist = vertices[1], pos:dist(vertices[1])
for i = 2,#vertices do
    local temp = pos:dist(vertices[i])
    if temp < dist then
        closest, dist = vertices[i], temp
    end
end

function vector:normalized()^top

Get normalized vector, i.e. a vector with the same direction as the input vector, but with length 1.

This does not change the input vector, but creates a new vector.

direction = velocity:normalized()

function vector:normalize_inplace()^top

Normalize a vector, i.e. make the vector unit length. Great to use on intermediate results.

This modifies the vector. If in doubt, use vector:normalized().

normal = (b - a):perpendicular():normalize_inplace()

function vector:rotated(angle)^top

Get a rotated vector.

This does not change the input vector, but creates a new vector.

-- approximate a circle
circle = {}
for i = 1,30 do
    local phi = 2 * math.pi * i / 30
    circle[#circle+1] = vector(0,1):rotated(phi)
end

function vector:rotate_inplace(angle)^top

Rotate a vector in-place. Great to use on intermediate results.

This modifies the vector. If in doubt, use vector:rotate().

-- ongoing rotation
spawner.direction:rotate_inplace(dt)

function vector:perpendicular()^top

Quick rotation by 90°. Creates a new vector. The same (but faster) as vec:rotate(math.pi/2).

normal = (b - a):perpendicular():normalize_inplace()

function vector:projectOn(v)^top

Project vector onto another vector (see sketch).

velocity_component = velocity:projectOn(axis)

function vector:mirrorOn(v)^top

Mirrors vector on the axis defined by the other vector.

deflected_velocity = ball.velocity:mirrorOn(surface_normal)

function vector:cross(other)^top

Get cross product of both vectors. Equals the area of the parallelogram spanned by both vectors.

parallelogram_area = a:cross(b)

function str(x,y)^top

Transforms a vector to a string of the form (x,y).

print(vector.str(love.mouse.getPosition()))

function mul(s, x,y)^top

Computes x*s,y*s. The order of arguments is chosen so that it's possible to chain multiple operations (see example).

velx,vely = vec.mul(dt, vec.add(velx,vely, accx,accy))

function mul(s, x,y)^top

Computes x/s,y/s. The order of arguments is chosen so that it's possible to chain multiple operations.

x,y = vec.div(self.zoom, x-w/2, y-h/2)

function add(x1,y1, x2,y2)^top

Computes the sum (x1+x2,y1+y2) of two vectors. Meant to be used in conjunction with other functions.

player.x,player.y = vector.add(player.x,player.y, vector.mul(dt, dx,dy))

function sub(x1,y1, x2,y2)^top

Computes the difference (x1-x2,y1-y2) of two vectors. Meant to be used in conjunction with other functions.

dx,dy = vector.sub(400,300, love.mouse.getPosition())

function permul(x1,y1, x2,y2)^top

Multiplies vectors coordinates, i.e.: x1*x2, y1*y2.

x,y = vector.permul(x,y, 1,1.5)

function dot(x1,y1, x2,y2)^top

Computes the dot product of two vectors: x1*x2 + y1*y2.

cosphi = vector.dot(rx,ry, vx,vy)

function cross(x1,y1, x2,y2)^top

Computes the cross product of two vectors, x1*y2 - y1*x2.

parallelogram_area = vector.cross(ax,ay, bx,by)

parallelogram_area = vector.det(ax,ay, bx,by)

function eq(x1,y1, x2,y2)^top

Test for equality.

if vector.eq(x1,y1, x2,y2) then be.happy() end

function le(x1,y1, x2,y2)^top

Test for partial lexical order, <=.

if vector.le(x1,y1, x2,y2) then be.happy() end

function lt(x1,y1, x2,y2)^top

Test for strict lexical order, <.

if vector.lt(x1,y1, x2,y2) then be.happy() end

function len(x,y)^top

Get length of a vector, i.e. math.sqrt(x*x + y*y).

distance = vector.len(love.mouse.getPosition())

function len2(x,y)^top

Get squared length of a vector, i.e. x*x + y*y.

-- get closest vertex to a given vector
closest, dsq = vertices[1], vector.len2(px-vertices[1].x, py-vertices[1].y)
for i = 2,#vertices do
    local temp = vector.len2(px-vertices[i].x, py-vertices[i].y)
    if temp < dsq then
        closest, dsq = vertices[i], temp
    end
end

function dist(x1,y1, x2,y2)^top

Get distance of two points. The same as vector.len(x1-x2, y1-y2).

-- get closest vertex to a given vector
-- slightly slower than the example using len2()
closest, dist = vertices[1], vector.dist(px,py, vertices[1].x,vertices[1].y)
for i = 2,#vertices do
    local temp = vector.dist(px,py, vertices[i].x,vertices[i].y)
    if temp < dist then
        closest, dist = vertices[i], temp
    end
end

function normalize(x,y)^top

Get normalized vector, i.e. a vector with the same direction as the input
vector, but with length 1.

dx,dy = vector.normalize(vx,vy)

function rotate(phi, x,y)^top

Get a rotated vector.

-- approximate a circle
circle = {}
for i = 1,30 do
    local phi = 2 * math.pi * i / 30
    circle[i*2-1], circle[i*2] = vector.rotate(phi, 0,1)
end

function perpendicular(x,y)^top

Quick rotation by 90°. The same (but faster) as vector.rotate(math.pi/2, x,y).

nx,ny = vector.normalize(vector.perpendicular(bx-ax, by-ay))

function project(x,y, u,v)^top

Project vector onto another vector.

vx_p,vy_p = vector.project(vx,vy, ax,ay)

function mirror(x,y, u,v)^top

Mirrors vector on the axis defined by the other vector.

vx,vy = vector.mirror(vx,vy, surface.x,surface.y)

function new{constructor, name = the_name, inherits = super}^top

Declare a new class.

The constructor will receive the newly create object as first argument.

You can check if an object is an instance of a class using object:is_a().

The name of the variable that holds the module can be used as a shortcut to new() (see example).

Class = require 'hump.class' -- `Class' is now a shortcut to new()

-- define unnamed class
Feline = Class{function(self, size, weight)
    self.size = size
    self.weight = weight
end}
print(Feline) -- prints '

-- define class method
function Feline:stats()
    return string.format("size: %.02f, weight %.02f", self.size, self.weight)
end

-- create two objects
garfield = Feline(.7, 45)
felix = Feline(.8, 12)

print("Garfield: " .. garfield:stats(), "Felix: " .. felix:stats())

Class = require 'hump.class'

-- define class with explicit name 'Feline'
Feline = Class{name = "Feline", function(self, size, weight)
    self.size = size
    self.weight = weight
end}

garfield = Feline(.7, 45)
print(Feline, garfield) -- prints ' >'

Class = require 'hump.class'
A = Class{}
function A:foo()
    print('foo')
end

B = Class{}
function B:bar()
    print('bar')
end

-- single inheritance
C = Class{inherits = A}
instance = C()
instance:foo() -- prints 'foo'

-- multiple inheritance
D = Class{inherits = {A,B}}
instance = D()
instance:foo() -- prints 'foo'
instance:bar() -- prints 'bar'

function class.construct(object, ...)^top

Calls class constructor of a class on an object.

Derived classes use this function their constructors to initialize the parent class(es) portions of the object.

Class = require 'hump.class'

Shape = Class{function(self, area)
    self.area = area
end}
function Shape:__tostring()
    return "area = " .. self.area
end

Rectangle = Class{inherits = Shape, function(self, width, height)
    Shape.construct(self, width * height)
    self.width  = width
    self.height = height
end}
function Rectangle:__tostring()
    local strs = {
        "width = " .. self.width,
        "height = " .. self.height,
        Shape.__tostring(self)
    },
    return table.concat(strs, ", ")
end

print( Rectangle(2,4) ) -- prints 'width = 2, height = 4, area = 8'

Menu = Class{function(self)
    self.entries = {}
end}
function Menu:add(title, entry)
    self.entries[#self.entries + 1] = entry
end
function Menu:display()
    -- ...
end

Entry = Class{function(self, title, command)
    self.title = title
    self.command = command
end}
function Entry:execute()
    return self.command()
end

Submenu = Class{inherits = {Menu, Entry}, function(self, title)
    Menu.construct(self)
    -- redirect self:execute() to self:display()
    Entry.construct(self, title, Menu.display)
end}

function class:inherit(...)^top

Inherit functions and variables of another class, if they are not already defined for the class. This is done by simply copying the functions and variables over to the subclass. The Lua rules for copying apply (i.e. tables are referenced, functions and primitive types are copied by value).

Be careful with changing table values in a subclass: This will change the value in the parent class too.

If more than one parent class is specified, inherit from all of these, in order of occurrence. That means that when two parent classes define the same method, the one from the first class will be inherited.

Note: class:inherit() doesn't actually care if the arguments supplied are hump classes. Just any table will work.

Class = require 'hump.class'

Entity = Class{function(self)
    GameObjects.register(self)
end}

Collidable = {
    dispatch_collision = function(self, other, dx, dy)
        if self.collision_handler[other.type])
            return collision_handler[other.type](self, other, dx, dy)
        end
        return collision_handler["*"](self, other, dx, dy)
    end,

    collision_handler = {["*"] = function() end},
}

Spaceship = Class{function(self)
    self.type = "Spaceship"
    -- ...
end}

-- make Spaceship collidable
Spaceship:inherit(Collidable)

function Spaceship:collision_handler["Spaceship"](other, dx, dy)
    -- ...
end

function object:is_a(cls)^top

Tests whether an object is an instance of a class.

Class = require 'hump.class'

A = Class{}
B = Class{inherits=A}
C = Class{inherits=B}
a, b, c = A(), B(), C()
print(a:is_a(A), a:is_a(B), a:is_a(C)) --> true   false  false
print(b:is_a(A), b:is_a(B), b:is_a(C)) --> true   true   false
print(c:is_a(A), c:is_a(B), c:is_a(C)) --> true   true   true

D = Class{}
E = Class{inherits={B,D}}
d, e = D(), E()
print(d:is_a(A), d:is_a(B), d:is_a(D)) --> false  false  true
print(e:is_a(A), e:is_a(B), e:is_a(D)) --> true   true   true

function new()^top

If you don't need multiple independent registries, you can use the global/default registry (see examples).

Creates a new signal registry that is independent of the default registry: It will manage it's own list of signals and does not in any way affect the the global registry. Likewise, the global registry does not affect the instance.

Note: Independent registries use the colon-notation (e.g. instance:emit("foo")), while the global registry uses the dot-notation (e.g. Signal.emit("foo")).

player.signals = Signals.new()

function register(s, f)^top

Registers a function f to be called when signal s is emitted.

Signal.register('level-complete', function() self.fanfare:play() end)

handle = Signal.register('level-load', function(level) level.show_help() end)

menu:register('key-left', select_previous_item)

function emit(s, ...)^top

Calls all functions bound to signal s with the supplied arguments.

function love.keypressed(key)
    -- using a signal instance
    if key == 'left' then menu:emit('key-left') end
end

if level.is_finished() then
    -- adding arguments
    Signal.emit('level-load', level.next_level)
end

function remove(s, ...)^top

Unbinds (removes) functions from signal s.

Signal.remove('level-load', handle)

function clear(s)^top

Removes all functions from signal s.

Signal.clear('key-left')

function emit_pattern(p, ...)^top

Emits all signals matching a string pattern.

Signal.emit_pattern('^update%-.*', dt)

function remove_pattern(p, ...)^top

Removes functions from all signals matching a string pattern.

Signal.remove_pattern('key%-.*', play_click_sound)

function clear_pattern(p)^top

Removes all functions from all signals matching a string pattern.

Signal.clear_pattern('sound%-.*')

player.signals:clear_pattern('.*') -- clear all signals

function new(x,y, zoom, rot)^top

Creates a new camera. You can access the camera position using camera.x, camera.y, the zoom using camera.zoom and the rotation using camera.rot.

The module variable name can be used at a shortcut to new().

camera = require 'hump.camera'
-- camera looking at (100,100) with zoom 2 and rotated by 45 degrees
cam = camera(100,100, 2, math.pi/2)

function camera:rotate(angle)^top

Rotate the camera by some angle. To set the angle use camera.rot = new_angle.

This function is shortcut to camera.rot = camera.rot + angle.

function love.update(dt)
    camera:rotate(dt)
end

function love.update(dt)
    camera:rotate(dt):move(dt,dt)
end

function camera:rotation(angle)^top

Returns camera.rot.

If given an angle, set rotation: camera.rot = angle.

love.graphics.print(camera:rotation(), 10, 10)
camera:rotation(math.pi/2)

function camera:move(dx,dy)^top

Move the camera by some vector. To set the position, use camera:lookAt(x,y).

This function is shortcut to camera.x,camera.y = camera.x+dx, camera.y+dy.

function love.update(dt)
    camera:move(dt * 5, dt * 6)
end

function love.update(dt)
    camera:move(dt * 5, dt * 6):rotate(dt)
end

function camera:lookAt(x,y)^top

Let the camera look at a point. In other words, it sets the camera position. To move the camera by some amount, use camera:move(x,y).

This function is shortcut to camera.x,camera.y = x, y.

function love.update(dt)
    camera:lookAt(player.pos:unpack())
end

function love.update(dt)
    camera:lookAt(player.pos:unpack()):rotation(player.rot)
end

function camera:pos()^top

Returns camera.x, camera.y.

-- let the camera fly!
local cam_dx, cam_dy = 0, 0

function love.mousereleased(x,y)
    local cx,cy = camera:position()
    dx, dy = x-cx, y-cy
end

function love.update(dt)
    camera:move(dx * dt, dy * dt)
end

function camera:attach()^top

Start looking through the camera.

Apply camera transformations, i.e. move, scale and rotate everything until camera:detach() as if looking through the camera.

function love.draw()
    camera:attach()
    draw_world()
    cam:detach()

    draw_hud()
end

function camera:detach()^top

Stop looking through the camera.

function love.draw()
    camera:attach()
    draw_world()
    cam:detach()

    draw_hud()
end

function camera:draw(func)^top

Wrap a function between a camera:attach()/camera:detach() pair:

cam:attach()
func()
cam:detach()

function love.draw()
    camera:draw(draw_world)
    draw_hud()
end

function camera:worldCoords(x, y)^top

Because a camera has a point it looks at, a rotation and a zoom factor, it defines a coordinate system. A point now has two sets of coordinates: One defines where the point is to be found in the game world, and the other describes the position on the computer screen. The first set of coordinates is called world coordinates, the second one camera coordinates. Sometimes it is needed to convert between the two coordinate systems, for example to get the position of a mouse click in the game world in a strategy game, or to see if an object is visible on the screen.

camera:worldCoords(x,y) and camera:cameraCoords(x,y) transform a point between these two coordinate systems.

x,y = camera:worldCoords(love.mouse.getPosition())
selectedUnit:plotPath(x,y)

function camera:cameraCoords(x, y)^top

Because a camera has a point it looks at, a rotation and a zoom factor, it defines a coordinate system. A point now has two sets of coordinates: One defines where the point is to be found in the game world, and the other describes the position on the computer screen. The first set of coordinates is called world coordinates, the second one camera coordinates. Sometimes it is needed to convert between the two coordinate systems, for example to get the position of a mouse click in the game world in a strategy game, or to see if an object is visible on the screen.

camera:worldCoords(x,y) and camera:cameraCoords(x,y) transform a point between these two coordinate systems.

x,y = cam:cameraCoords(player.pos)
love.graphics.line(x, y, love.mouse.getPosition())

function camera:mousepos()^top

Shortcut to camera:worldCoords(love.mouse.getPosition()).

x,y = camera:mousepos()
selectedUnit:plotPath(x,y)

function new(...)^top

Create new ring-buffer.

The module name is a shortcut to this function.

ringbuffer = require 'hump.ringbuffer'
rb = ringbuffer.new(1,2,3)
-- or:
rb = ringbuffer(1,2,3)

function ringbuffer:insert(...)^top

Insert items behind current element.

rb = Ringbuffer(1,5,6) -- content: 1,5,6
rb:insert(2,3,4)       -- content: 1,2,3,4,5,6

function ringbuffer:remove()^top

Remove current item, return it and select next element.

rb = Ringbuffer(1,2,3,4) -- content: 1,2,3,4
val = rb:remove()        -- content: 2,3,4
print(val)               -- prints `1'

function ringbuffer:removeAt(pos)^top

Remove the item at a position relative to the current element.

rb = Ringbuffer(1,2,3,4,5) -- content: 1,2,3,4,5
rb:removeAt(2)             -- content: 1,2,4,5
rb:removeAt(-1)            -- content: 1,2,4

function ringbuffer:next()^top

Select and return the next element.

rb = Ringbuffer(1,2,3)
rb:next()     -- content: 2,3,1
rb:next()     -- content: 3,1,2
x = rb:next() -- content: 1,2,3
print(x)      -- prints `1'

function ringbuffer:prev()^top

Select and return the previous item.

rb = Ringbuffer(1,2,3)
rb:prev())    -- content: 3,1,2
rb:prev())    -- content: 2,3,1
x = rb:prev() -- content: 1,2,3
print(x)      -- prints `1'

function ringbuffer:get()^top

Return the current element.

rb = Ringbuffer(1,2,3)
rb:next()       -- content: 2,3,1
print(rb:get()) -- prints '2'

function ringbuffer:size()^top

Get number of items in the buffer

rb = Ringbuffer(1,2,3)
print(rb:size()) -- prints '3'
rb:remove()
print(rb:size()) -- prints '2'