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 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 registerEvents()^ top
Register all 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.updatefunction 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.
Example:
function love.load()
Gamestate.registerEvents()
Gamestate.switch(menu)
-end
Timer = require "hump.timer"
hump.timer provides a simple interface to use delayed functions, i.e. functionsthat will be executed after some amount time has passed. For example, you can usea timer to set the player invincible for a short amount of time.
In addition, the module offers facilities to create functions that interpolateor 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.
function add(delay, func)^ top
Add a timed function. The function will be executed after delay seconds have elapsed, given that update() 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:
- function
The timer handle.
Example:
-- grant the player 5 seconds of immortality
+end
Timer = require "hump.timer"
hump.timer provides a simple interface to use delayed functions, i.e. functionsthat will be executed after some amount time has passed. For example, you can usea timer to set the player invincible for a short amount of time.
In addition, the module offers facilities to create functions that interpolateor 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.
function add(delay, func)^ top
Add a timed function. The function will be executed after delay seconds have elapsed, given that update() 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:
- function
- 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)
function 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 Number of times the function is to be called.
Returns:
- function
The timer handle.
Example:
Timer.addPeriodic(1, function() lamp:toggleLight() end)
Timer.addPeriodic(0.3, function() mothership:spawnFighter() end, 5)
-- flicker player's image as long as he is invincible
+Timer.add(1, function(func) print("foo") Timer.add(1, func) end)
function 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 - Number of times the function is to be called.
Returns:
- function
- The timer handle.
Example:
Timer.addPeriodic(1, function() lamp:toggleLight() end)
Timer.addPeriodic(0.3, function() mothership: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
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 in another timer.
Parameters:
- function
func The function to be canceled.
Example:
function tick()
+end)
function 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 in another timer.
Parameters:
- function
func - The function to be canceled.
Example:
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.
function 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().
Example:
function love.update(dt)
+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.
function 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().
Example:
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, ...)
where
dt is the time that has passed since the last call of the wrapper and
... are arguments passed to the interpolating function. It will return whatever the interpolating functions returns if the interpolation is not yet finished or nil if the interpolation is done.
The prototype of the interpolating function is:
function interpolator(fraction, ...)
where
fraction is a number between 0 and 1 depending on how much time has passed and
... are additional arguments supplied to the wrapper.
Parameters:
- number
length Interpolation length in seconds.
- function
func Interpolating function.
Returns:
- function
The wrapper function.
Example:
fader = Timer.Interpolator(5, function(frac, r,g,b)
+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, ...)
where
dt is the time that has passed since the last call of the wrapper and
... are arguments passed to the interpolating function. It will return whatever the interpolating functions returns if the interpolation is not yet finished or nil if the interpolation is done.
The prototype of the interpolating function is:
function interpolator(fraction, ...)
where
fraction is a number between 0 and 1 depending on how much time has passed and
... are additional arguments supplied to the wrapper.
Parameters:
- number
length - Interpolation length in seconds.
- function
func - Interpolating function.
Returns:
- function
- The wrapper function.
Example:
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.
Parameters:
- number
length Length of one interpolation period.
- function
func Oscillating function.
Returns:
- function
The wrapper function.
Example:
mover = Timer.Oscillator(10, function(frac)
+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.
Parameters:
- number
length - Length of one interpolation period.
- function
func - Oscillating function.
Returns:
- function
- The wrapper function.
Example:
mover = Timer.Oscillator(10, function(frac)
return 400 + 300 * math.sin(2*math.pi*frac)
end)
@@ -84,18 +84,18 @@ function love.draw()
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.
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- [^http://en.wikipedia.org/wiki/Dot_product Dot product].
number * vector = vector- Vector scaling ([^http://en.wikipedia.org/wiki/Scalar_multiplication scalar multiplication]).
vector * number = vector- Vector scaling.
vector / number = vector- Vector scaling.
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:
+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
+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 vectorb = a -- b references ac = a:clone() -- c is a copy of ab.x = 0 -- changes a,b and cprint(a,b,c) -- prints '(1,0), (1,0), (1,1)'
Returns:
- vector
Copy of the vector
Example:
copy = original:clone
function vector:unpack()^ top
Extract coordinates.
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).
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.
Returns:
- number
Squared length of the vector.
Example:
-- get closest vertex to a given vector
+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 vectorb = a -- b references ac = a:clone() -- c is a copy of ab.x = 0 -- changes a,b and cprint(a,b,c) -- prints '(1,0), (1,0), (1,1)'
Returns:
- vector
- Copy of the vector
Example:
copy = original:clone
function vector:unpack()^ top
Extract coordinates.
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).
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.
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
+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
@@ -103,20 +103,20 @@ for i = 2,#vertices do
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.
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()}.
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
+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.
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()}.
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 as (but faster):
vec:rotate(math.pi/2)
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.
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. The order of arguments is chosen so that you can 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 or 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 == y2vector.le(x1,y1, x2,y2)x1 <= x2 and y1 <= y2vector.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.
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
+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 as (but faster):
vec:rotate(math.pi/2)
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.
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. The order of arguments is chosen so that you can 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 or 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 == y2vector.le(x1,y1, x2,y2)x1 <= x2 and y1 <= y2vector.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.
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
+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
@@ -124,12 +124,12 @@ for i = 2,#vertices do
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
+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 as (but faster)
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)
Class = require "hump.class"
A small, fast class implementation with multiple inheritance support
function new(constructor, the_name, 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 Class constructor. Can be accessed with theclass.construct(object, ...)
- string
the_name Class name (used only to make the class compliant to tostring().
- class or table of classes
super Classes to inherit from. Can either be a single class or a table of classes
Example:
Class = require 'hump.class' -- `Class' is now a shortcut to new()
+end
function perpendicular(x,y)^ top
Quick rotation by 90°. The same as (but faster)
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)
Class = require "hump.class"
A small, fast class implementation with multiple inheritance support
function new(constructor, the_name, 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 - Class constructor. Can be accessed with
theclass.construct(object, ...) - string
the_name - Class name (used only to make the class compliant to
tostring(). - class or table of classes
super - Classes to inherit from. Can either be a single class or a table of classes
Example:
Class = require 'hump.class' -- `Class' is now a shortcut to new()
-- define class with implicit name 'Feline'
Feline = Class{function(self, size, weight)
@@ -179,7 +179,7 @@ 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'
+
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
@@ -226,7 +226,7 @@ Submenu = Class{inherits = {Menu, Entry}, function(self, title)
-- 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
Example:
Class = require 'hump.class'
+
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
Example:
Class = require 'hump.class'
Entity = Class{function(self)
GameObjects.register(self)
@@ -254,7 +254,7 @@ 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'
+
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}
@@ -269,15 +269,15 @@ 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
-
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) endfunction 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) endfunction B:foo() print("foo") end
one, two = B(1,2), B(3,4)result = one + tworesult: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.camera^ top
Camera = require "hump.camera"
Depends on hump.vector-light
A camera utility for LÖVE. A camera can "look" at a position. It can zoom in andout and it can rotate it's view. In the background, this is done by actuallymoving, scaling and rotating everything in the game world. But don't worry aboutthat.
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'
+
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) endfunction 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) endfunction B:foo() print("foo") end
one, two = B(1,2), B(3,4)result = one + tworesult: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.camera^ top
Camera = require "hump.camera"
Depends on hump.vector-light
A camera utility for LÖVE. A camera can "look" at a position. It can zoom in andout and it can rotate it's view. In the background, this is done by actuallymoving, scaling and rotating everything in the game world. But don't worry aboutthat.
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)
+
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: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)
+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.
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):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.
Example:
function love.draw()
camera:attach()
@@ -291,40 +291,40 @@ 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.
Example:
function love.draw()
+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.
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())
+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:toCameraCoords(player.pos)
love.graphics.line(x, y, love.mouse.getPosition())
-
function camera:mousepos()^ top
Shortcut to camera:worldCoords(vector(love.mouse.getPosition())).
Returns:
- numbers
Mouse position in world coordinates.
Example:
x,y = camera:mousepos()
+
function camera:mousepos()^ top
Shortcut to camera:worldCoords(vector(love.mouse.getPosition())).
Returns:
- numbers
- Mouse position in world coordinates.
Example:
x,y = camera:mousepos()
selectedUnit:plotPath(x,y)
-
hump.ringbuffer^ top
Ringbuffer = require "hump.ringbuffer"
A ring-buffer is a circular array: It does not have a first nor a last item,but it has a selected or current element.
A ring-buffer can be used to implement Tomb Raider style inventories, loopingplay-lists, recurring dialogs (like a unit's answers when selecting it multipletimes in Warcraft) and generally everything that has a circular or loopingstructure.
function new(...)^ top
Create new ring-buffer.
The module name is a shortcut to this function.
Parameters:
- mixed
... - Initial elements.
Returns:
- Ringbuffer
- The ring-buffer object.
Example:
Ringbuffer = require 'hump.ringbuffer'
rb = ringbuffer(1,2,3)
-
function ringbuffer:insert(...)^ top
Insert items behind current element.
Parameters:
- mixed
... Items to insert.
Example:
rb = RingbuffeR(1,5,6) -- content: 1,5,6
+
function ringbuffer:insert(...)^ top
Insert items behind current element.
Parameters:
- mixed
... - Items to insert.
Example:
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.
Returns:
- mixed
The removed item.
Example:
rb = Ringbuffer(1,2,3,4) -- content: 1,2,3,4
+
function ringbuffer:remove()^ top
Remove current item, return it and select next element.
Returns:
- mixed
- The removed item.
Example:
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.
Parameters:
- number
pos Position of the item to remove.
Returns:
- mixed
The removed item.
Example:
rb = Ringbuffer(1,2,3,4,5) -- content: 1,2,3,4,5
+
function ringbuffer:removeAt(pos)^ top
Remove the item at a position relative to the current element.
Parameters:
- number
pos - Position of the item to remove.
Returns:
- mixed
- The removed item.
Example:
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.
Returns:
- mixed
The next item.
Example:
rb = Ringbuffer(1,2,3)
+
function ringbuffer:next()^ top
Select and return the next element.
Returns:
- mixed
- The next item.
Example:
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.
Returns:
- mixed
The previous item.
Example:
rb = Ringbuffer(1,2,3)
+
function ringbuffer:prev()^ top
Select and return the previous item.
Returns:
- mixed
- The previous item.
Example:
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.
Returns:
- mixed
The currently selected element.
Example:
rb = Ringbuffer(1,2,3)
+
function ringbuffer:get()^ top
Return the current element.
Returns:
- mixed
- The currently selected element.
Example:
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
Returns:
- number
Number of items in the buffer.
Example:
rb = Ringbuffer(1,2,3)
+
function ringbuffer:size()^ top
Get number of items in the buffer
Returns:
- number
- Number of items in the buffer.
Example:
rb = Ringbuffer(1,2,3)
print(rb:size()) -- prints '3'
rb:remove()
print(rb:size()) -- prints '2'
diff --git a/makedoc.lua b/makedoc.lua
index dfcdb61..1e7d7f2 100644
--- a/makedoc.lua
+++ b/makedoc.lua
@@ -189,7 +189,7 @@ function Function(M)
F('Parameters:
')
if #M.params == 0 then F('- None
') end
for _,p in ipairs(M.params) do
- F('- %s
%s - %s
', p[1], p[2], markup(p[3]))
+ F('- %s
%s - %s
', p[1], p[2], markup(p[3]):sub(4,-5))
end
F('
Returns:
')
if #M.returns == 0 then F('- Nothing
') end
for _,r in ipairs(M.returns) do
- F('- %s
- %s
', r[1], markup(r[2]))
+ F('- %s
- %s
', r[1], markup(r[2]):sub(4,-5))
end
F('