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 update(...)^ top

function draw(...)^ top

function focus(...)^ top

function keypressed(...)^ top

function keyreleased(...)^ top

function mousepressed(...)^ top

function mousereleased(...)^ top

function joystickpressed(...)^ top

function joystickreleased(...)^ top

function quit(...)^ top

Calls the corresponding function on the current gamestate (see callbacks).

Only needed when not using registerEvents().

function love.update(dt)
    Gamestate.update(dt)
end

function love.draw()
    local mx,my = love.mouse.getPosition()
    Gamestate.draw(mx, my)
end

function love.keypressed(key, code)
    Gamestate.keypressed(key, code)
end

function registerEvents(callbacks)^ top

Register love callbacks to call Gamestate.update(), Gamestate.draw(), etc. automatically.

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

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

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

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

function love.load()
    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 the timer instance.

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

function instance: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 that 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.

It is an error to schedule a function again if it is not yet finished or canceled.

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 addPeriodic.
Timer.add(1, function(func) print("foo") Timer.add(1, func) end)

menuTimer:add(1, finishAnimation)

function addPeriodic(delay, func, count)^ top

function instance:addPeriodic(delay, func, count)^ 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 clear() is called.

Timer.addPeriodic(1, function() lamp:toggleLight() end)

mothership_timer:addPeriodic(0.3, function() self:spawnFighter() end, 5)

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

function cancel(func)^ top

function instance:cancel(func)^ top

Prevent a timer from being executed in the future.

Always use the function handle returned by add()/addPeriodic() to cancel a timer.

Never use this inside a scheduled function.

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

function clear()^ top

function instance:clear()^ top

Remove all timed and periodic functions. Functions that have not yet been executed will discarded. Never use this inside a scheduled function.

Timer.clear()

function update(dt)^ top

function instance: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

function Interpolator(length, func)^ top

Create a wrapper for an interpolating function, i.e. a function that acts depending on how much time has passed.

The wrapper will have the prototype:

function wrapper(dt, ...)

The prototype of the interpolating function is:

function interpolator(fraction, ...)

fader = Timer.Interpolator(5, function(frac, r,g,b)
    love.graphics.setBackgroundColor(frac*r,frac*g,frac*b)
end)

function love.update(dt)
    fader(dt, 255,255,255)
end

function Oscillator(length, func)^ top

Create a wrapper for an oscillating function, which is basically a looping interpolating function.

The function prototypes are the same as with Interpolator():

function wrapper(dt, ...)

function oscillator(fraction, ...)

As with Interpolator, the wrapper will return whatever oscillator() returns.

mover = Timer.Oscillator(10, function(frac)
   return 400 + 300 * math.sin(2*math.pi*frac)
end)

local xpos = 100
function love.update(dt)
    xpos = mover(dt)
end

function love.draw()
    love.graphics.circle('fill', xpos, 300, 80, 36)
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(phi)^ 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

Sketch:

function vector:rotate_inplace(phi)^ 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()

Sketch:

function vector:projectOn(v)^ top

Project vector onto another vector (see sketch).

velocity_component = velocity:projectOn(axis)

Sketch:

function vector:mirrorOn(v)^ top

Mirrors vector on the axis defined by the other vector.

deflected_velocity = ball.velocity:mirrorOn(surface_normal)

Sketch:

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)

Sketch:

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

function div(s, x,y)^ top

Computes x*s,y*s and x/s,y/s respectively. 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))

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

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

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

Computes the sum/difference of vectors. Same as x1+x2,y1+y2 and x1-x2,y1-y2 respectively. Meant to be used in conjunction with other functions.

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

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

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

Multiplies vectors coordinate wise, 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 det(x1,y1, x2,y2)^ top

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

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

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

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

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

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

Compares two vectors according to

vector.eq(x1,y1, x2,y2)

x1 == x2 and y1 == y2

vector.le(x1,y1, x2,y2)

x1 <= x2 and y1 <= y2

vector.lt(x1,y1, x2,y2)

x1 < x2 or (x1 == x2) and y1 <= y2

...

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

function instance: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

function instance:emit(s, ...)^ top

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

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

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

function on_collide(dt, a,b, dx,dy)
    a.signals:emit('collide', b,  dx, dy)
    b.signals:emit('collide', a, -dx,-dy)
end

function remove(s, ...)^ top

function instance:remove(s, ...)^ top

Unbinds (removes) functions from signal s.

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

function clear(s)^ top

function instance:clear(s)^ top

Removes all functions from signal s.

Signal.clear('key-left')

function emit_pattern(p, ...)^ top

function instance:emit_pattern(p, ...)^ top

Emits all signals matching a string pattern.

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

function remove_pattern(p, ...)^ top

function instance: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

function instance:clear_pattern(p)^ top

Removes all functions from all signals matching a string pattern.

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

Signal.clear_pattern('.*') -- clear all signals

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

Creates a new camera object. 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:move(dx,dy)^ top

Move the camera by some vector. To set the position, use camera.x,camera.y = new_x,new_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):rotate(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

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.

These two functions convert a point between these two coordinate systems.

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

x,y = cam:toCameraCoords(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(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'