hump - LÖVE Helper Utilities for More Productivity

hump.gamestate^ top

Gamestate = require "hump.gamestate"

A gamestate encapsulates independent data an behaviour into a single entity.

A typical game could consist of a menu-state, a level-state and a game-over-state.

Module overview

callbacks: Gamestate Callbacks
new(): Create a new gamestate.
switch(): Switch to gamestate.
update(): Update current gamestate.
draw(): Draw the current gamestate.
focus(): Inform current gamestate of a focus event.
keypressed(): Inform current gamestate of a keypressed event.
keyreleased(): Inform current gamestate of a keyreleased event.
mousepressed(): Inform current gamestate of a mousepressed event.
mousereleased(): Inform current gamestate of a mousereleased event.
joystickpressed(): Inform current gamestate of a joystickpressed event.
joystickreleased(): Inform current gamestate of a joystickreleased event.
quit(): Inform current gamestate of a quit event.
registerEvents(): Automatically do all of the above when needed.

Gamestate Callbacks^ top

A gamestate can define (nearly) all callbacks that LÖVE defines. In addition, there are callbacks for entering and leaving a state.:

init(): Called once before entering the state. See switch().
enter(previous, ...): Called when entering the state. See switch().
leave(): Called when leaving a state. See switch().
update(): Update the game state. Called every frame.
draw(): Draw on the screen. Called every frame.
focus(): Called if the window gets or looses focus.
keypressed(): Triggered when a key is pressed.
keyreleased(): Triggered when a key is released.
mousepressed(): Triggered when a mouse button is pressed.
mousereleased(): Triggered when a mouse button is released.
joystickpressed(): Triggered when a joystick button is pressed.
joystickreleased(): Triggered when a joystick button is released.
quit(): Called on quitting the game. Only called on the active gamestate.

When using registerEvents(), all these callbacks will receive the same arguments as the LÖVE callbacks do.

Example:

menu = Gamestate.new()
function menu:init() -- run only once
    self.background = love.graphics.newImage('bg.jpg')
    Buttons.initialize()
end

function menu:enter(previous) -- run every time the state is entered
    Buttons.setActive(Buttons.start)
end

function menu:update(dt)
    Buttons.update(dt)
end

function menu:draw()
    love.graphics.draw(self.background, 0, 0)
    Buttons.draw()
end

function menu:keyreleased(key)
    if key == 'up' then
        Buttons.selectPrevious()
    elseif key == 'down' then
        Buttons.selectNext()
    elseif
        Buttons.active:onClick()
    end
end

function menu:mousereleased(x,y, mouse_btn)
    local button = Buttons.hovered(x,y)
    if button then
        Button.select(button)
        if mouse_btn == 'l' then
            button:onClick()
        end
    end
end

function new()^ top

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

Parameters:

None

Returns:

Gamestate: The new gamestate.

Example:

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.

Parameters:

Gamestate to: Target gamestate.
mixed ...: Additional arguments to pass to to:enter().

Returns:

mixed: The results of to:enter()

Example:

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().

Parameters:

mixed ...: Arguments to pass to the corresponding callback.

Returns:

mixed: The results of the callback function.

Example:

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

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.

Parameters:

table callbacks (optional): Names of the callbacks to register. If omitted, register all callbacks.

Returns:

Nothing

Example:

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

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

hump.timer^ top

Timer = require "hump.timer"

hump.timer provides a simple interface to use delayed functions, i.e. functions that will be executed after some amount time has passed. For example, you can use a timer to set the player invincible for a short amount of time.

In addition, the module offers facilities to create functions that interpolate or oscillate over time. An interpolator could fade the color or a text message, whereas an oscillator could be used for the movement of foes in a shmup.

Module overview

new(): Create new timer instance.
add(): Schedule a function.
addPeriodic(): Add a periodic function.
do_for(): Run a function for the next few seconds.
cancel(): Cancel a scheduled function.
clear(): Remove all timed and periodic functions.
update(): Update scheduled functions.

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)).

Parameters:

None

Returns:

Timer: A timer instance

Example:

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).

Parameters:

number delay: Number of seconds the function will be delayed.
function func: The function to be delayed.

Returns:

table: The timer handle.

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.

Parameters:

number delay: Number of seconds between two consecutive function calls.
function func: The function to be called periodically.
number count (optional): Number of times the function is to be called.

Returns:

table: The timer handle.

Example:

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 do_for(delta, func, after)^ top

function instance:do_for(delta, func, after)^ top

Run a 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.

The same constraints as with add() apply.

Parameters:

number delta: Number of seconds the func will be called.
function func: The function to be called upon update(dt).
function after (optional): A function to be called after delta seconds.

Returns:

table: The timer handle.

Example:

Timer.do_for(3, function() screen:shake() 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()
	player.visible = true -- make sure the player is visible after three seconds
	player.isInvincible = false
end)

function cancel(handle)^ top

function instance:cancel(handle)^ 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.

Parameters:

table handle: The function to be canceled.

Returns:

Nothing

Example:

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.

Parameters:

None

Returns:

Nothing

Example:

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).

Parameters:

number dt: Time that has passed since the last update().

Returns:

Nothing

Example:

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

hump.vector^ top

vector = require "hump.vector"

A handy 2D vector class providing most of the things you do with vectors.

You can access the individual coordinates by using vec.x and vec.y.

Module overview

operators: Arithmetics and relations
new(): Create a new vector.
isvector(): Test if value is a vector.
vector:clone(): Copy a vector.
vector:unpack(): Extract coordinates.
vector:permul(): Per element multiplication.
vector:len(): Get length.
vector:len2(): Get squared length.
vector:dist(): Distance to other vector.
vector:normalized(): Get normalized vector.
vector:normalize_inplace(): Normalize vector in-place.
vector:rotated(): Get rotated vector.
vector:rotate_inplace(): Rotate vector in-place.
vector:perpendicular(): Get perpendicular vector.
vector:projectOn(): Get projection onto another vector.
vector:mirrorOn(): Mirrors vector on other vector
vector:cross(): Cross product of two vectors.

Arithmetics and relations^ top

Vector arithmetic is implemented by using __add, __mul and other metamethods:

vector + vector = vector: Component wise sum.
vector - vector = vector: Component wise difference.
vector * vector = number: Dot product.
number * vector = vector: Scalar multiplication (scaling).
vector * number = vector: Scalar multiplication.
vector / number = vector: Scalar multiplication.

Relational operators are defined, too:

a == b: true, if a.x == b.x and a.y == b.y.
a <= b: true, if a.x <= b.x and a.y <= b.y.
a < b: Lexical sort: true, if a.x < b.x or a.x == b.x and a.y < b.y.

Example:

-- acceleration, player.velocity and player.position are vectors
acceleration = vector(0,-9)
player.velocity = player.velocity + acceleration * dt
player.position = player.position + player.velocity * dt

function new(x,y)^ top

Create a new vector.

Parameters:

numbers x,y: Coordinates.

Returns:

vector: The vector.

Example:

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.

Parameters:

mixed v: The variable to test.

Returns:

boolean: true if v is a vector, false otherwise

Example:

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)'

Parameters:

None

Returns:

vector: Copy of the vector

Example:

copy = original:clone

function vector:unpack()^ top

Extract coordinates.

Parameters:

None

Returns:

numbers: The coordinates

Example:

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.

Parameters:

vector other: The other vector

Returns:

vector: The new vector as described above

Example:

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).

Parameters:

None

Returns:

number: Length of the vector.

Example:

distance = (a - b):len()

function vector:len2()^ top

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

Parameters:

None

Returns:

number: Squared length of the vector.

Example:

-- 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().

Parameters:

vector other: Other vector to measure the distance to.

Returns:

number: The distance of the vectors.

Example:

-- 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.

Parameters:

None

Returns:

vector: Vector with same direction as the input vector, but length 1.

Example:

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().

Parameters:

None

Returns:

vector: Itself - the normalized vector

Example:

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.

Parameters:

number phi: Rotation angle in radians.

Returns:

vector: The rotated vector

Example:

-- 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()

Parameters:

number phi: Rotation angle in radians.

Returns:

vector: Itself - the rotated vector

Example:

-- 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)

Parameters:

None

Returns:

vector: A vector perpendicular to the input vector

Example:

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

Sketch:

function vector:projectOn(v)^ top

Project vector onto another vector (see sketch).

Parameters:

vector v: The vector to project on.

Returns:

vector: The projected vector.

Example:

velocity_component = velocity:projectOn(axis)

Sketch:

function vector:mirrorOn(v)^ top

Mirrors vector on the axis defined by the other vector.

Parameters:

vector v: The vector to mirror on.

Returns:

vector: The mirrored vector.

Example:

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.

Parameters:

vector other: Vector to compute the cross product with.

Returns:

number: Cross product of both vectors.

Example:

parallelogram_area = a:cross(b)

Sketch:

hump.vector-light^ top

vector = require "hump.vector-light"

An table-free version of hump.vector. Instead of a vector class, hump.vector-light provides functions that operate on numbers.

Using this module instead of vector might result in faster code, but does so at the expense of readability. Unless you are sure that it causes a significant performance penalty, I recommend to use hump.vector.

Module overview

str(): String representation.
mul(): Product of a vector and a scalar.
div(): Product of a vector and the inverse of a scalar.
add(): Sum of two vectors.
sub(): Difference of two vectors.
permul(): Per element multiplication.
dot(): [^http://en.wikipedia.org/wiki/Dot_product Dot product]
det(): Cross product
cross(): Cross product
eq(): Equality.
le(): Partial lexical order.
lt(): Strict lexical order.
len(): Get length.
len2(): Get squared length.
dist(): Distance of two points.
normalize(): Normalize vector.
rotate(): Rotate vector.
perpendicular(): Get perpendicular vector.
project(): Project projection onto another vector.
mirror(): Mirrors vector on other vector.

function str(x,y)^ top

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

Parameters:

numbers x,y: The vector

Returns:

string: The string representation

Example:

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).

Parameters:

number s: The scalar.
numbers x,y: The vector.

Returns:

numbers: The result of the operation.

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.

Parameters:

numbers x1,y1: First vector.
numbers x2,y2: Second vector.

Returns:

numbers: The result of the operation.

Example:

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.

Parameters:

numbers x1,y1: First vector.
numbers x2,y2: Second vector.

Returns:

numbers: The result of the operation.

Example:

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.

Parameters:

numbers x1,y1: First vector.
numbers x2,y2: Second vector.

Returns:

number: The dot product.

Example:

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.

Parameters:

numbers x1,y1: First vector.
numbers x2,y2: Second vector.

Returns:

number: The cross product.

Example:

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

Parameters:

numbers x1,y1: First vector.
numbers x2,y2: Second vector.

Returns:

boolean: The result of the operation.

Example:

...

function len(x,y)^ top

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

Parameters:

numbers x,y: The vector.

Returns:

number: Length of the vector.

Example:

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

function len2(x,y)^ top

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

Parameters:

numbers x,y: The vector.

Returns:

number: Squared length of the vector.

Example:

-- 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).

Parameters:

numbers x1,y1: First vector.
numbers x2,y2: Second vector.

Returns:

number: The distance of the points.

Example:

-- 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.

Parameters:

numbers x,y: The vector.

Returns:

numbers: Vector with same direction as the input vector, but length 1.

Example:

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

function rotate(phi, x,y)^ top

Get a rotated vector.

Parameters:

number phi: Rotation angle in radians.
numbers x,y: The vector.

Returns:

numbers: The rotated vector

Example:

-- 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)

Parameters:

numbers x,y: The vector.

Returns:

numbers: A vector perpendicular to the input vector

Example:

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

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

Project vector onto another vector.

Parameters:

numbers x,y: The vector to project.
numbers u,v: The vector to project onto.

Returns:

numbers: The projected vector.

Example:

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.

Parameters:

numbers x,y: The vector to mirror.
numbers u,v: The vector defining the axis.

Returns:

numbers: The mirrored vector.

Example:

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

hump.class^ top

Class = require "hump.class"

A small, fast class implementation with multiple inheritance support

Module overview

new(): Declare a new class.
class.construct(): Call class constructor.
class:inherit(): Explicit class inheritance/mixin support.
object:is_a(): Test object's type.
caveats: Caveats

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).

Parameters:

function constructor (optional): Class constructor. Can be accessed with theclass.construct(object, ...)
string the_name (optional): Class name (used only to make the class compliant to tostring().
class or table of classes super (optional): Classes to inherit from. Can either be a single class or a table of classes

Returns:

class: The class

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.

Parameters:

Object object: The object. Usually self.
mixed ...: Arguments to pass to the constructor

Returns:

mixed: Whatever the parent class constructor returns

Example:

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.

Parameters:

tables ...: Parent classes to inherit from

Returns:

Nothing

Example:

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.

Parameters:

class cls: Class to test. Note: this is the class itself, not the name of the class.

Returns:

Boolean: true if the object is an instance of the class, false otherwise

Example:

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

Caveats^ top

Be careful when using metamethods like __add or __mul: If subclass inherits those methods from a superclass, but does not overwrite them, the result of the operation may be of the type superclass. Consider the following:

Class = require 'hump.class'

A = Class{function(self, x) self.x = x end}
function A:__add(other) return A(self.x + other.x) end
function A:show() print("A:", self.x) end

B = Class{inherits = A, function(self, x, y) A.construct(self, x) self.y = y end}
function B:show() print("B:", self.x, self.y) end
function B:foo() print("foo") end

one, two = B(1,2), B(3,4)
result = one + two
result:show()   -- prints "A:    4"
result:foo()    -- error: method does not exist

Note that while you can define the __index metamethod of the class, this is not a good idea: It will break the class. To add a custom __index metamethod without breaking the class system, you have to use rawget(). But beware that this won't affect subclasses:

Class = require 'hump.class'

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

function A:__index(key)
    print(key)
    return rawget(A, key)
end

instance = A()
instance:foo() -- prints foo  bar

B = Class{inherits = A}
instance = B()
instance:foo() -- prints only foo

hump.signal^ top

Signal = require "hump.signal"

A simple yet effective implementation of Signals and Slots, also known as Observer pattern: Functions can be dynamically bound to signals. When a signal is emitted, all registered functions will be invoked. Simple as that.

hump.signal makes things more interesing by allowing to emit all signals that match a Lua string pattern.

Module overview

new(): Create new signal registry.
register(): Register function with a signal.
emit(): Call all functions bound to a signal.
remove(): Remove functions from registry.
clear(): Clears a signal registry.
emit_pattern(): Emits signals matching a pattern.
remove_pattern(): Remove functions from signals matching a pattern.
clear_pattern(): Clears signal registry matching a pattern.

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")).

Parameters:

None

Returns:

Registry: A new signal registry.

Example:

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.

Parameters:

string s: The signal identifier.
function f: The function to register.

Returns:

function: A function handle to use in remove.

Example:

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.

Parameters:

string s: The signal identifier.
mixed ... (optional): Arguments to pass to the bound functions.

Returns:

Nothing

Example:

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.

Parameters:

string s: The signal identifier.
functions ...: Functions to unbind from the signal.

Returns:

Nothing

Example:

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

function clear(s)^ top

function instance:clear(s)^ top

Removes all functions from signal s.

Parameters:

string s: The signal identifier.

Returns:

Nothing

Example:

Signal.clear('key-left')

function emit_pattern(p, ...)^ top

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

Emits all signals matching a string pattern.

Parameters:

string p: The signal identifier pattern.
mixed ... (optional): Arguments to pass to the bound functions.

Returns:

Nothing

Example:

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.

Parameters:

string p: The signal identifier pattern.
functions ...: Functions to unbind from the signals.

Returns:

Nothing

Example:

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.

Parameters:

string p: The signal identifier pattern.

Returns:

Nothing

Example:

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

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

hump.camera^ top

Camera = require "hump.camera"

A camera utility for LÖVE. A camera can "look" at a position. It can zoom in and out and it can rotate it's view. In the background, this is done by actually moving, scaling and rotating everything in the game world. But don't worry about that.

Module overview

new(): Create a new camera object.
camera:rotate(): Rotate camera object.
camera:rotation(): Get camera rotation.
camera:move(): Move camera object.
camera:pos(): Get camera position..
camera:attach(): Attach camera object.
camera:detach(): Detach camera object.
camera:draw(): Attach, draw and detach.
camera:worldCoords(): Convert point to world coordinates.
camera:cameraCoords(): Convert point to camera coordinates.
camera:mousepos(): Get mouse position in world coordinates.

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().

Parameters:

numbers x,y: Point for the camera to look at.
number zoom: Camera zoom.
number rot: Camera rotation in radians.

Returns:

camera: A new camera object.

Example:

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.

Parameters:

number angle: Rotation angle in radians

Returns:

camera: The camera object.

Example:

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

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

function camera:rotation()^ top

Returns camera.rot.

Parameters:

None

Returns:

number: Rotation angle in radians.

Example:

love.graphics.print(camera:rotation(), 10, 10)

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.

Parameters:

numbers dx,dy: Direction to move the camera.

Returns:

camera: The camera object.

Example:

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:pos()^ top

Returns camera.x, camera.y.

Parameters:

None

Returns:

numbers: Camera position.

Example:

-- 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.

Parameters:

None

Returns:

Nothing

Example:

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

    draw_hud()
end

function camera:detach()^ top

Stop looking through the camera.

Parameters:

None

Returns:

Nothing

Example:

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()

Parameters:

function func: Drawing function to be wrapped.

Returns:

Nothing

Example:

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.

Parameters:

numbers x, y: Point to transform.

Returns:

numbers: Transformed point.

Example:

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

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()).

Parameters:

None

Returns:

numbers: Mouse position in world coordinates.

Example:

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

hump Helper Utilities for More Productivity

Introduction^ top

Documentation^ top

hump.gamestate^ top

Module overview

Gamestate Callbacks^ top

function new()^ top

function switch(to, ...)^ top

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

function registerEvents(callbacks)^ top

hump.timer^ top

Module overview

function new()^ top

function add(delay, func)^ top

function instance:add(delay, func)^ top

function addPeriodic(delay, func, count)^ top

function instance:addPeriodic(delay, func, count)^ top

function do_for(delta, func, after)^ top

function instance:do_for(delta, func, after)^ top

function cancel(handle)^ top

function instance:cancel(handle)^ top

function clear()^ top

function instance:clear()^ top

function update(dt)^ top

function instance:update(dt)^ top

hump.vector^ top

Module overview

Arithmetics and relations^ top

function new(x,y)^ top

function isvector(v)^ top

function vector:clone()^ top

function vector:unpack()^ top

function vector:permul(other)^ top

function vector:len()^ top

function vector:len2()^ top

function vector:dist(other)^ top

function vector:normalized()^ top

function vector:normalize_inplace()^ top

function vector:rotated(phi)^ top

function vector:rotate_inplace(phi)^ top

function vector:perpendicular()^ top

function vector:projectOn(v)^ top

function vector:mirrorOn(v)^ top

function vector:cross(other)^ top

hump.vector-light^ top

Module overview

function str(x,y)^ top

function mul(s, x,y)^ top

function div(s, x,y)^ top

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

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

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

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

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

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

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

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

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

function len(x,y)^ top

function len2(x,y)^ top

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

function normalize(x,y)^ top

function rotate(phi, x,y)^ top

function perpendicular(x,y)^ top

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

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

hump.class^ top

Module overview

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

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

function class:inherit(...)^ top