hump Helper Utilities for More Productivity

function new()^top

Deprecated: Use the table constructor instead (see example)

Declare a new gamestate (just an empty table). A gamestate can define several callbacks.

menu = {}
-- deprecated method:
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.

a = vector.new(10,10)

-- as a shortcut, you can call the module like a function:
vector = require "hump.vector"
a = vector(10,10)

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 div(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{init = constructor, __includes = parents, ...}^top

Declare a new class.

init() will receive the new object instance as first argument. Any other arguments will also be forwarded (see examples), i.e. init() has the following signature:

function init(self, ...)

If you do not specify a constructor, an empty constructor will be used instead.

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 a class class
Feline = Class{
    init = function(self, size, weight)
        self.size = size
        self.weight = weight
    end;
    -- define a method
    stats = function(self)
        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'

-- same as above, but with 'external' function definitions
Feline = Class{}

function Feline:init(size, weight)
    self.size = size
    self.weight = weight
end

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

garfield = Feline(.7, 45)
print(Feline, garfield)

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

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

-- single inheritance
C = Class{__includes = A}
instance = C()
instance:foo() -- prints 'foo'
instance:bar() -- error: function not defined

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

-- class attributes are shared across instances
A = Class{ foo = 'foo' } -- foo is a class attribute/static member

one, two, three = A(), A(), A()
print(one.foo, two.foo, three.foo) --> prints 'foo    foo    foo'

one.foo = 'bar' -- overwrite/specify for instance `one' only
print(one.foo, two.foo, three.foo) --> prints 'bar    foo    foo'

A.foo = 'baz' -- overwrite for all instances without specification
print(one.foo, two.foo, three.foo) --> prints 'bar    baz    baz'

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

Calls class constructor of a class on an object.

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

Class = require 'hump.class'

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

Rectangle = Class{__includes = Shape,
    init = function(self, width, height)
        Shape.init(self, width * height)
        self.width  = width
        self.height = height
    end;
    __tostring = function(self)
        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'

function class:include(other)^top

Inherit functions and variables of another class, but if they are not already defined. This is done by (deeply) copying the functions and variables over to the subclass.

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

Note 2: You can use Class.include(a, b) to copy any fields from table a to table b (see second example).

Class = require 'hump.class'

Entity = Class{
    init = 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{
    init = function(self)
        self.type = "Spaceship"
        -- ...
    end
}

-- make Spaceship collidable
Spaceship:include(Collidable)

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

-- using Class.include()
Class = require 'hump.class'
a = {
    foo = 'bar',
    bar = {one = 1, two = 2, three = 3},
    baz = function() print('baz') end,
}
b = {
    foo = 'nothing to see here...'
}

Class.include(b, a) -- copy values from a to b
                    -- note that neither a nor b are hump classes!

print(a.foo, b.foo) -- prints 'bar    nothing to see here...'

b.baz() -- prints 'baz'

b.bar.one = 10 -- changes only values in b
print(a.bar.one, b.bar.one) -- prints '1    10'

function class:clone()^top

Create a clone/deep copy of the class.

Note: You can use Class.clone(a) to create a deep copy of any table (see second example).

Class = require 'hump.class'

point = Class{ x = 0, y = 0 }

a = point:clone()
a.x, a.y = 10, 10
print(a.x, a.y) --> prints '10    10'

b = point:clone()
print(b.x, b.y) --> prints '10    10'

-- using Class.clone() to copy tables
Class = require 'hump.class'
a = {
    foo = 'bar',
    bar = {one = 1, two = 2, three = 3},
    baz = function() print('baz') end,
}
b = Class.clone(a)

b.baz() -- prints 'baz'
b.bar.one = 10
print(a.bar.one, b.bar.one) -- prints '1    10'

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.scale 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: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: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:rotateTo(angle)^top

Set rotation: camera.rot = angle.

camera:rotateTo(math.pi/2)

function camera:zoom(mul)^top

Multiply zoom: camera.scale = camera.scale * mul.

camera:zoom(2)   -- make everything twice as big

camera:zoom(0.5) -- ... and back to normal

camera:zoom(-1)  -- flip everything

function camera:zoomTo(zoom)^top

Set zoom: camera.scale = zoom.

camera:zoomTo(1)

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)