<dt><ahref="#Class">hump.class</a></dt><dd>Class-based object orientated programming for Lua</dd>
<dt><ahref="#Camera">hump.camera</a></dt><dd>A camera for LÖVE</dd>
<dt><ahref="#Ringbuffer">hump.ringbuffer</a></dt><dd>A data structure that wraps around itself.</dd>
</dl></div></div>
<aname="Gamestate"></a><divclass="outer-block"><h3>hump.gamestate<aclass="top"href="#top">^ top</a></h3><divclass="preamble"><pre><codeclass="lua">hump.gamestate = require "Gamestate"</code></pre> A gamestate encapsulates independent data an behaviour into a single entity.</p><p> A typical game could consist of a <em>menu-state</em>, a <em>level-state</em> and a <em>game-over-state</em>.</div><divclass="overview"><h4>Module overview</h4><dl><dt><ahref="#Gamestate-new">new()</a></dt><dd>Create a new gamestate.</dd><dt><ahref="#Gamestate-switch">switch()</a></dt><dd>Switch to gamestate.</dd><dt><ahref="#Gamestate-update">update()</a></dt><dd>Update current gamestate.</dd><dt><ahref="#Gamestate-draw">draw()</a></dt><dd>Draw the current gamestate.</dd><dt><ahref="#Gamestate-focus">focus()</a></dt><dd>Inform current gamestate of a focus event.</dd><dt><ahref="#Gamestate-keypressed">keypressed()</a></dt><dd>Inform current gamestate of a keypressed event.</dd><dt><ahref="#Gamestate-keyreleased">keyreleased()</a></dt><dd>Inform current gamestate of a keyreleased event.</dd><dt><ahref="#Gamestate-mousepressed">mousepressed()</a></dt><dd>Inform current gamestate of a mousepressed event.</dd><dt><ahref="#Gamestate-mousereleased">mousereleased()</a></dt><dd>Inform current gamestate of a mousereleased event.</dd><dt><ahref="#Gamestate-joystickpressed">joystickpressed()</a></dt><dd>Inform current gamestate of a joystickpressed event.</dd><dt><ahref="#Gamestate-joystickreleased">joystickreleased()</a></dt><dd>Inform current gamestate of a joystickreleased event.</dd><dt><ahref="#Gamestate-quit">quit()</a></dt><dd>Inform current gamestate of a quit event.</dd><dt><ahref="#Gamestate-registerEvents">registerEvents()</a></dt><dd>Automatically do all of the above when needed.</dd></dl></div><aname="Gamestate-callbacks"></a><divclass="section-block"><h4>Gamestate Callbacks</h4><p> A gamestate can define (nearly) all callbacks that LÖVE defines. In addition,
there are callbacks for entering and leaving a state.:</p><p><dl><dt><code>init()</code></dt><dd>Called once before entering the state. See <code>switch()</code>.
</dd><dt><code>enter(previous, ...)</code></dt><dd>Called when entering the state. See <code>switch()</code>.
</dd><dt><code>leave()</code></dt><dd>Called when leaving a state. See <code>switch()</code>.
</dd><dt><code>update()</code></dt><dd>Update the game state. Called every frame.
</dd><dt><code>draw()</code></dt><dd>Draw on the screen. Called every frame.
</dd><dt><code>focus()</code></dt><dd>Called if the window gets or looses focus.
</dd><dt><code>keypressed()</code></dt><dd>Triggered when a key is pressed.
</dd><dt><code>keyreleased()</code></dt><dd>Triggered when a key is released.
</dd><dt><code>mousepressed()</code></dt><dd>Triggered when a mouse button is pressed.
</dd><dt><code>mousereleased()</code></dt><dd>Triggered when a mouse button is released.
</dd><dt><code>joystickpressed()</code></dt><dd>Triggered when a joystick button is pressed.
</dd><dt><code>joystickreleased()</code></dt><dd>Triggered when a joystick button is released.
</dd><dt><code>quit()</code></dt><dd>Called on quitting the game. Only called on the active gamestate.
</dd></dl></p><p> When using <code>registerEvents()</code>, all these callbacks will receive the same
arguments as the <ahref="http://love2d.org/wiki/love">LÖVE callbacks</a> do.</p><divclass="example">Example:<pre><codeclass="lua">menu = Gamestate.new()
end</code></pre></div></div><aname="Gamestate-new"></a><divclass="ref-block"><h4>function <spanclass="name">new</span><spanclass="arglist">()</span><aclass="top"href="#Gamestate">^ top</a></h4><p>Declare a new gamestate. A gamestate can define several <ahref="#Gamestate-callbacks">callbacks</a></p><divclass="arguments">Parameters:<dl><dt>None.</dt></dl></div><divclass="returns">Returns:<dl><dt>Gamestate</dt><dd>The new gamestate.</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">menu = Gamestate.new()</code></pre></div></div><aname="Gamestate-switch"></a><divclass="ref-block"><h4>function <spanclass="name">switch</span><spanclass="arglist">(to, ...)</span><aclass="top"href="#Gamestate">^ top</a></h4><p> Switch to a gamestate, with any additional arguments passed to the new state.</p><p> 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.</p><divclass="arguments">Parameters:<dl><dt>Gamestate <code>to</code></dt><dd>Target gamestate.</dd><dt>mixed <code>...</code></dt><dd>Additional arguments to pass to to:enter().</dd></dl></div><divclass="returns">Returns:<dl><dt>mixed</dt><dd>The results of to:enter()</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">Gamestate.switch(game, level_two)</code></pre></div></div><aname="Gamestate-update"></a><aname="Gamestate-draw"></a><aname="Gamestate-focus"></a><aname="Gamestate-keypressed"></a><aname="Gamestate-keyreleased"></a><aname="Gamestate-mousepressed"></a><aname="Gamestate-mousereleased"></a><aname="Gamestate-joystickpressed"></a><aname="Gamestate-joystickreleased"></a><aname="Gamestate-quit"></a><divclass="ref-block"><h4>function <spanclass="name">update</span><spanclass="arglist">(...)</span><aclass="top"href="#Gamestate">^ top</a></h4><h4>function <spanclass="name">draw</span><spanclass="arglist">(...)</span><aclass="top"href="#Gamestate">^ top</a></h4><h4>function <spanclass="name">focus</span><spanclass="arglist">(...)</span><aclass="top"href="#Gamestate">^ top</a></h4><h4>function <spanclass="name">keypressed</span><spanclass="arglist">(...)</span><aclass="top"href="#Gamestate">^ top</a></h4><h4>function <spanclass="name">keyreleased</span><spanclass="arglist">(...)</span><aclass="top"href="#Gamestate">^ top</a></h4><h4>function <spanclass="name">mousepressed</span><spanclass="arglist">(...)</span><aclass="top"href="#Gamestate">^ top</a></h4><h4>function <spanclass="name">mousereleased</span><spanclass="arglist">(...)</span><aclass="top"href="#Gamestate">^ top</a></h4><h4>function <spanclass="name">joystickpressed</span><spanclass="arglist">(...)</span><aclass="top"href="#Gamestate">^ top</a></h4><h4>function <spanclass="name">joystickreleased</span><spanclass="arglist">(...)</span><aclass="top"href="#Gamestate">^ top</a></h4><h4>function <spanclass="name">quit</span><spanclass="arglist">(...)</span><aclass="top"href="#Gamestate">^ top</a></h4><p> Calls the corresponding function on the current gamestate (see <ahref="#Gamestate-callbacks">callbacks</a>).</p><p> Only needed when not using registerEvents().</p><divclass="arguments">Parameters:<dl><dt>mixed <code>...</code></dt><dd>Arguments to pass to the corresponding <ahref="#Gamestate-callbacks">callback</a>.</dd></dl></div><divclass="returns">Returns:<dl><dt>mixed</dt><dd>The results of the callback function.</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">function love.update(dt)
end</code></pre></div></div><aname="Gamestate-registerEvents"></a><divclass="ref-block"><h4>function <spanclass="name">registerEvents</span><spanclass="arglist">()</span><aclass="top"href="#Gamestate">^ top</a></h4><p> Register all love callbacks to call Gamestate.update(), Gamestate.draw(), etc. automatically.</p><p> This is by done the love callbacks, e.g.:
<aname="Timer"></a><divclass="outer-block"><h3>hump.timer<aclass="top"href="#top">^ top</a></h3><divclass="preamble"><pre><codeclass="lua">hump.timer = require "Timer"</code></pre> 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.</p><p> 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.</div><divclass="overview"><h4>Module overview</h4><dl><dt><ahref="#Timer-add">add()</a></dt><dd>Add a timed function.</dd><dt><ahref="#Timer-addPeriodic">addPeriodic()</a></dt><dd>Add a periodic function.</dd><dt><ahref="#Timer-clear">clear()</a></dt><dd>Remove all timed and periodic functions.</dd><dt><ahref="#Timer-update">update()</a></dt><dd>Update timed functions.</dd><dt><ahref="#Timer-Interpolator">Interpolator()</a></dt><dd>Create a new interpolating function.</dd><dt><ahref="#Timer-Oscillator">Oscillator()</a></dt><dd>Create a new oscillating function.</dd></dl></div><aname="Timer-add"></a><divclass="ref-block"><h4>function <spanclass="name">add</span><spanclass="arglist">(delay, func)</span><aclass="top"href="#Timer">^ top</a></h4><p> Add a timed function. The function will be executed after <code>delay</code> seconds
have elapsed, given that update() is called every frame.</p><p> Note that there is no guarantee that the delay will not be exceeded, it is
only guaranteed that the function will not be executed <em>before</em> the delay
has passed.</p><p><code>func</code> will receive itself as only parameter. This is useful to implement
periodic behavior (see the example).</p><divclass="arguments">Parameters:<dl><dt>number <code>delay</code></dt><dd>Number of seconds the function will be delayed.</dd><dt>function <code>func</code></dt><dd>The function to be delayed.</dd></dl></div><divclass="returns">Returns:<dl><dt>Nothing.</dt></dl></div><divclass="example">Examples:<pre><codeclass="lua">-- grant the player 5 seconds of immortality
player.isInvincible = true
Timer.add(5, function() player.isInvincible = false end)</code></pre><pre><codeclass="lua">-- print "foo" every second. See addPeriodic.
Timer.add(1, function(func) print("foo") Timer.add(1, func) end)</code></pre></div></div><aname="Timer-addPeriodic"></a><divclass="ref-block"><h4>function <spanclass="name">addPeriodic</span><spanclass="arglist">(delay, func, count)</span><aclass="top"href="#Timer">^ top</a></h4><p> Add a function that will be called <code>count</code> times every <code>delay</code> seconds.</p><p> If <code>count</code> is omitted, the function will be called until it returns <code>false</code>
or clear() is called.</p><divclass="arguments">Parameters:<dl><dt>number <code>delay</code></dt><dd>Number of seconds between two consecutive function calls.</dd><dt>function <code>func</code></dt><dd>The function to be called periodically.</dd><dt>number <code>count</code> (optional)</dt><dd>Number of times the function is to be called.</dd></dl></div><divclass="returns">Returns:<dl><dt>Nothing.</dt></dl></div><divclass="example">Examples:<pre><codeclass="lua">Timer.addPeriodic(1, function() lamp:toggleLight() end)</code></pre><pre><codeclass="lua">Timer.addPeriodic(0.3, function() mothership:spawnFighter() end, 5)</code></pre><pre><codeclass="lua">-- flicker player's image as long as he is invincible
Timer.addPeriodic(0.1, function()
player:flipImage()
return player.isInvincible
end)</code></pre></div></div><aname="Timer-clear"></a><divclass="ref-block"><h4>function <spanclass="name">clear</span><spanclass="arglist">()</span><aclass="top"href="#Timer">^ top</a></h4><p>Remove all timed and periodic functions. Functions that have not yet been executed will discarded.</p><divclass="arguments">Parameters:<dl><dt>None.</dt></dl></div><divclass="returns">Returns:<dl><dt>Nothing.</dt></dl></div><divclass="example">Example:<pre><codeclass="lua">Timer.clear</code></pre></div></div><aname="Timer-update"></a><divclass="ref-block"><h4>function <spanclass="name">update</span><spanclass="arglist">(dt)</span><aclass="top"href="#Timer">^ top</a></h4><p>Update timers and execute functions if the deadline is reached. Use this in love.update(dt).</p><divclass="arguments">Parameters:<dl><dt>number <code>dt</code></dt><dd>Time that has passed since the last update().</dd></dl></div><divclass="returns">Returns:<dl><dt>Nothing.</dt></dl></div><divclass="example">Example:<pre><codeclass="lua">function love.update(dt)
end</code></pre></div></div><aname="Timer-Interpolator"></a><divclass="ref-block"><h4>function <spanclass="name">Interpolator</span><spanclass="arglist">(length, func)</span><aclass="top"href="#Timer">^ top</a></h4><p> Create a wrapper for an interpolating function, i.e. a function that acts
depending on how much time has passed.</p><p> The wrapper will have the prototype:
where <code>fraction</code> is a number between 0 and 1 depending on how much time has
passed and <code>...</code> are additional arguments supplied to the wrapper.</p><divclass="arguments">Parameters:<dl><dt>number <code>length</code></dt><dd>Interpolation length in seconds.</dd><dt>function <code>func</code></dt><dd>Interpolating function.</dd></dl></div><divclass="returns">Returns:<dl><dt>function</dt><dd>The wrapper function.</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">fader = Timer.Interpolator(5, function(frac, r,g,b)
end</code></pre></div></div><aname="Timer-Oscillator"></a><divclass="ref-block"><h4>function <spanclass="name">Oscillator</span><spanclass="arglist">(length, func)</span><aclass="top"href="#Timer">^ top</a></h4><p> Create a wrapper for an oscillating function, which is basically a looping
interpolating function.</p><p> The function prototypes are the same as with Interpolator():
<pre><codeclass="lua">function oscillator(fraction, ...) </code></pre></p><p> As with Interpolator, the wrapper will return whatever <code>oscillator()</code> returns.</p><divclass="arguments">Parameters:<dl><dt>number <code>length</code></dt><dd>Length of one interpolation period.</dd><dt>function <code>func</code></dt><dd>Oscillating function.</dd></dl></div><divclass="returns">Returns:<dl><dt>function</dt><dd>The wrapper function.</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">mover = Timer.Oscillator(10, function(frac)
<aname="vector"></a><divclass="outer-block"><h3>hump.vector<aclass="top"href="#top">^ top</a></h3><divclass="preamble"><pre><codeclass="lua">hump.vector = require "vector"</code></pre> A handy 2D vector class providing most of the things you do with vectors.</p><p> You can access the individual coordinates by using <code>vec.x</code> and <code>vec.y</code>.</div><divclass="overview"><h4>Module overview</h4><dl><dt><ahref="#vector-new">new()</a></dt><dd>Create a new vector.</dd><dt><ahref="#vector-isvector">isvector()</a></dt><dd>Test if value is a vector.</dd><dt><ahref="#vector-vector:clone">vector:clone()</a></dt><dd>Copy a vector.</dd><dt><ahref="#vector-vector:unpack">vector:unpack()</a></dt><dd>Extract coordinates.</dd><dt><ahref="#vector-vector:permul">vector:permul()</a></dt><dd>Per element multiplication.</dd><dt><ahref="#vector-vector:len">vector:len()</a></dt><dd>Get length.</dd><dt><ahref="#vector-vector:len2">vector:len2()</a></dt><dd>Get squared length.</dd><dt><ahref="#vector-vector:dist">vector:dist()</a></dt><dd>Distance to other vector.</dd><dt><ahref="#vector-vector:normalized">vector:normalized()</a></dt><dd>Get normalized vector.</dd><dt><ahref="#vector-vector:normalize_inplace">vector:normalize_inplace()</a></dt><dd>Normalize vector in-place.</dd><dt><ahref="#vector-vector:rotated">vector:rotated()</a></dt><dd>Get rotated vector.</dd><dt><ahref="#vector-vector:rotate_inplace">vector:rotate_inplace()</a></dt><dd>Rotate vector in-place.</dd><dt><ahref="#vector-vector:perpendicular">vector:perpendicular()</a></dt><dd>Get perpendicular vector.</dd><dt><ahref="#vector-vector:projectOn">vector:projectOn()</a></dt><dd>Get projection onto another vector.</dd><dt><ahref="#vector-vector:mirrorOn">vector:mirrorOn()</a></dt><dd>Mirrors vector on other vector</dd><dt><ahref="#vector-vector:cross">vector:cross()</a></dt><dd>Cross product of two vectors.</dd></dl></div><aname="vector-operators"></a><divclass="section-block"><h4>Arithmetics and relations</h4><p> Vector arithmetic is implemented by using <code>__add</code>, <code>__mul</code> and other metamethods:</p><p><dl><dt><code>vector + vector = vector</code></dt><dd>Component wise sum.
player.position = player.position + player.velocity * dt</code></pre></div></div><aname="vector-new"></a><divclass="ref-block"><h4>function <spanclass="name">new</span><spanclass="arglist">(x,y)</span><aclass="top"href="#vector">^ top</a></h4><p>Create a new vector.</p><divclass="arguments">Parameters:<dl><dt>numbers <code>x,y</code></dt><dd>Coordinates.</dd></dl></div><divclass="returns">Returns:<dl><dt>vector</dt><dd>The vector.</dd></dl></div><divclass="example">Examples:<pre><codeclass="lua">a = vector.new(10,10)</code></pre><pre><codeclass="lua">-- as a shortcut, you can call the module like a function:
vector = require "hump.vector"
a = vector(10,10)</code></pre></div></div><aname="vector-isvector"></a><divclass="ref-block"><h4>function <spanclass="name">isvector</span><spanclass="arglist">(v)</span><aclass="top"href="#vector">^ top</a></h4><p>Test whether a variable is a vector.</p><divclass="arguments">Parameters:<dl><dt>mixed <code>v</code></dt><dd>The variable to test.</dd></dl></div><divclass="returns">Returns:<dl><dt>boolean</dt><dd><code>true</code> if <code>v</code> is a vector, <code>false</code> otherwise</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">if not vector.isvector(v) then
end</code></pre></div></div><aname="vector-vector:clone"></a><divclass="ref-block"><h4>function <spanclass="name">vector:clone</span><spanclass="arglist">()</span><aclass="top"href="#vector">^ top</a></h4><p> 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
print(a,b,c) -- prints '(1,0), (1,0), (1,1)'</code></pre></p><divclass="arguments">Parameters:<dl><dt>None.</dt></dl></div><divclass="returns">Returns:<dl><dt>vector</dt><dd>Copy of the vector</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">copy = original:clone</code></pre></div></div><aname="vector-vector:unpack"></a><divclass="ref-block"><h4>function <spanclass="name">vector:unpack</span><spanclass="arglist">()</span><aclass="top"href="#vector">^ top</a></h4><p>Extract coordinates.</p><divclass="arguments">Parameters:<dl><dt>None.</dt></dl></div><divclass="returns">Returns:<dl><dt>numbers</dt><dd>The coordinates</dd></dl></div><divclass="example">Examples:<pre><codeclass="lua">x,y = pos:unpack</code></pre><pre><codeclass="lua">love.graphics.draw(self.image, self.pos:unpack())</code></pre></div></div><aname="vector-vector:permul"></a><divclass="ref-block"><h4>function <spanclass="name">vector:permul</span><spanclass="arglist">(other)</span><aclass="top"href="#vector">^ top</a></h4><p> Multiplies vectors coordinate wise, i.e. <code>result = vector(a.x * b.x, a.y * b.y)</code>.</p><p> This does not change either argument vectors, but creates a new one.</p><divclass="arguments">Parameters:<dl><dt>vector <code>other</code></dt><dd>The other vector</dd></dl></div><divclass="returns">Returns:<dl><dt>vector</dt><dd>The new vector as described above</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">scaled = original:permul(vector(1,1.5))</code></pre></div></div><aname="vector-vector:len"></a><divclass="ref-block"><h4>function <spanclass="name">vector:len</span><spanclass="arglist">()</span><aclass="top"href="#vector">^ top</a></h4><p>Get length of a vector, i.e. <code>math.sqrt(vec.x * vec.x + vec.y * vec.y)</code>.</p><divclass="arguments">Parameters:<dl><dt>None.</dt></dl></div><divclass="returns">Returns:<dl><dt>number</dt><dd>Length of the vector.</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">distance = (a - b):len()</code></pre></div></div><aname="vector-vector:len2"></a><divclass="ref-block"><h4>function <spanclass="name">vector:len2</span><spanclass="arglist">()</span><aclass="top"href="#vector">^ top</a></h4><p>Get squared length of a vector, i.e. <code>vec.x * vec.x + vec.y * vec.y</code>.</p><divclass="arguments">Parameters:<dl><dt>None.</dt></dl></div><divclass="returns">Returns:<dl><dt>number</dt><dd>Squared length of the vector.</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">-- get closest vertex to a given vector
end</code></pre></div></div><aname="vector-vector:dist"></a><divclass="ref-block"><h4>function <spanclass="name">vector:dist</span><spanclass="arglist">(other)</span><aclass="top"href="#vector">^ top</a></h4><p>Get distance of two vectors. The same as <code>(a - b):len()</code>.</p><divclass="arguments">Parameters:<dl><dt>vector <code>other</code></dt><dd>Other vector to measure the distance to.</dd></dl></div><divclass="returns">Returns:<dl><dt>number</dt><dd>The distance of the vectors.</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">-- get closest vertex to a given vector
end</code></pre></div></div><aname="vector-vector:normalized"></a><divclass="ref-block"><h4>function <spanclass="name">vector:normalized</span><spanclass="arglist">()</span><aclass="top"href="#vector">^ top</a></h4><p> Get normalized vector, i.e. a vector with the same direction as the input
vector, but with length 1.</p><p> This does not change the input vector, but creates a new vector.</p><divclass="arguments">Parameters:<dl><dt>None.</dt></dl></div><divclass="returns">Returns:<dl><dt>vector</dt><dd>Vector with same direction as the input vector, but length 1.</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">direction = velocity:normalized()</code></pre></div></div><aname="vector-vector:normalize_inplace"></a><divclass="ref-block"><h4>function <spanclass="name">vector:normalize_inplace</span><spanclass="arglist">()</span><aclass="top"href="#vector">^ top</a></h4><p> Normalize a vector, i.e. make the vector unit length. Great to use on
intermediate results.</p><p><spanclass="warning">This modifies the vector. If in doubt, use <code>vector:normalized()</code>.</span></p><divclass="arguments">Parameters:<dl><dt>None.</dt></dl></div><divclass="returns">Returns:<dl><dt>vector</dt><dd>Itself - the normalized vector</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">normal = (b - a):perpendicular():normalize_inplace()</code></pre></div></div><aname="vector-vector:rotated"></a><divclass="ref-block"><h4>function <spanclass="name">vector:rotated</span><spanclass="arglist">(phi)</span><aclass="top"href="#vector">^ top</a></h4><p> Get a rotated vector.</p><p> This does not change the input vector, but creates a new vector.</p><divclass="arguments">Parameters:<dl><dt>number <code>phi</code></dt><dd>Rotation angle in <ahref="http://en.wikipedia.org/wiki/Radians">radians</a>.</dd></dl></div><divclass="returns">Returns:<dl><dt>vector</dt><dd>The rotated vector</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">-- approximate a circle
end</code></pre></div><divclass="example">Sketch:<p><imgsrc="vector-rotated.png"alt="sketch of rotated vectors"width=260",height="171"/></p></div></div><aname="vector-vector:rotate_inplace"></a><divclass="ref-block"><h4>function <spanclass="name">vector:rotate_inplace</span><spanclass="arglist">(phi)</span><aclass="top"href="#vector">^ top</a></h4><p> Rotate a vector in-place. Great to use on intermediate results.</p><p><spanclass="warning">This modifies the vector. If in doubt, use <code>vector:rotate()</code></span></p><divclass="arguments">Parameters:<dl><dt>number <code>phi</code></dt><dd>Rotation angle in <ahref="http://en.wikipedia.org/wiki/Radians">radians</a>.</dd></dl></div><divclass="returns">Returns:<dl><dt>vector</dt><dd>Itself - the rotated vector</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">-- ongoing rotation
spawner.direction:rotate_inplace(dt)</code></pre></div></div><aname="vector-vector:perpendicular"></a><divclass="ref-block"><h4>function <spanclass="name">vector:perpendicular</span><spanclass="arglist">()</span><aclass="top"href="#vector">^ top</a></h4><p> Quick rotation by 90°. Creates a new vector. The same as (but faster):
<pre><codeclass="lua">vec:rotate(math.pi/2)</code></pre></p><divclass="arguments">Parameters:<dl><dt>None.</dt></dl></div><divclass="returns">Returns:<dl><dt>vector</dt><dd>A vector perpendicular to the input vector</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">normal = (b - a):perpendicular():normalize_inplace()</code></pre></div><divclass="example">Sketch:<p><imgsrc="vector-perpendicular.png"alt="sketch of perpendicular vectors"width=267",height="202"/></p></div></div><aname="vector-vector:projectOn"></a><divclass="ref-block"><h4>function <spanclass="name">vector:projectOn</span><spanclass="arglist">(v)</span><aclass="top"href="#vector">^ top</a></h4><p>Project vector onto another vector (see sketch).</p><divclass="arguments">Parameters:<dl><dt>vector <code>v</code></dt><dd>The vector to project on.</dd></dl></div><divclass="returns">Returns:<dl><dt>vector</dt><dd>The projected vector.</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">velocity_component = velocity:projectOn(axis)</code></pre></div><divclass="example">Sketch:<p><imgsrc="vector-projectOn.png"alt="sketch of vector projection"width=605",height="178"/></p></div></div><aname="vector-vector:mirrorOn"></a><divclass="ref-block"><h4>function <spanclass="name">vector:mirrorOn</span><spanclass="arglist">(v)</span><aclass="top"href="#vector">^ top</a></h4><p>Mirrors vector on the axis defined by the other axis.</p><divclass="arguments">Parameters:<dl><dt>vector <code>v</code></dt><dd>The vector to mirror on.</dd></dl></div><divclass="returns">Returns:<dl><dt>vector</dt><dd>The mirrored vector.</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">deflected_velocity = ball.velocity:mirrorOn(surface)</code></pre></div></div><aname="vector-vector:cross"></a><divclass="ref-block"><h4>function <spanclass="name">vector:cross</span><spanclass="arglist">(other)</span><aclass="top"href="#vector">^ top</a></h4><p> Get cross product of both vectors.</p><p> For the math geeks:</p><p> The cross product is usually not defined for 2D vectors. To still get a
meaningful result, we treat the vectors as being 3D vectors <em>(x,y,0)</em>. The
cross product of both vectors has just a z-component, and this is what this
function returns. It's also the determinant of both vectors <em>d = det(a,b)</em>
which is the area of the parallelogram spanned by both vectors.</p><divclass="arguments">Parameters:<dl><dt>vector <code>other</code></dt><dd>Vector to compute the cross product with.</dd></dl></div><divclass="returns">Returns:<dl><dt>number</dt><dd>Cross product of both vectors.</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">parallelogram_area = a:cross(b)</code></pre></div></div></div>
<aname="Class"></a><divclass="outer-block"><h3>hump.class<aclass="top"href="#top">^ top</a></h3><divclass="preamble"><pre><codeclass="lua">hump.class = require "Class"</code></pre>A small, fast class implementation with multiple inheritance support</div><divclass="overview"><h4>Module overview</h4><dl><dt><ahref="#Class-new">new()</a></dt><dd>Declare a new class.</dd><dt><ahref="#Class-class.construct">class.construct()</a></dt><dd>Call class constructor.</dd><dt><ahref="#Class-class:inherit">class:inherit()</a></dt><dd>Explicit class inheritance/mixin support.</dd><dt><ahref="#Class-object:is_a">object:is_a()</a></dt><dd>Test object's type.</dd></dl></div><aname="Class-new"></a><divclass="ref-block"><h4>function <spanclass="name">new</span><spanclass="arglist">{constructor, name = the_name, inherits = super}</span><aclass="top"href="#Class">^ top</a></h4><p> Declare a new class.</p><p> The constructor will receive the newly create object as first argument.</p><p> If no name is given, the module will try to guess the name based on the
variable name the class is assigned to. Note that this can only work for
global variables.</p><p> You can check if an object is an instance of a class using <code>object:is_a()</code>.</p><p> The name of the variable that holds the module can be used as a shortcut to
<code>new()</code> (see example).</p><divclass="arguments">Parameters:<dl><dt>function <code>constructor</code> (optional)</dt><dd>Class constructor. Can be accessed with <code>theclass.construct(object, ...)</code></dd><dt>string <code>the_name</code> (optional)</dt><dd>Class name (used only to make the class compliant to {# tostring()).</dd><dt>class or table of classes <code>super</code> (optional)</dt><dd>Classes to inherit from. Can either be a single class or a table of classes</dd></dl></div><divclass="returns">Returns:<dl><dt>class</dt><dd>The class</dd></dl></div><divclass="example">Examples:<pre><codeclass="lua">Class = require 'hump.class' -- `Class' is now a shortcut to new()
-- define class with implicit name 'Feline'
</code></pre></div></div><aname="Class-class.construct"></a><divclass="ref-block"><h4>function <spanclass="name">class.construct</span><spanclass="arglist">(object, ...)</span><aclass="top"href="#Class">^ top</a></h4><p> Calls class constructor of a class on an object</p><p> Derived classes use this function their constructors to initialize the
parent class(es) portions of the object.</p><divclass="arguments">Parameters:<dl><dt>Object <code>object</code></dt><dd>The object. Usually <code>self</code>.</dd><dt>mixed <code>...</code></dt><dd>Arguments to pass to the constructor</dd></dl></div><divclass="returns">Returns:<dl><dt>mixed</dt><dd>Whatever the parent class constructor returns</dd></dl></div><divclass="example">Examples:<pre><codeclass="lua">Class = require 'hump.class'
</code></pre></div></div><aname="Class-class:inherit"></a><divclass="ref-block"><h4>function <spanclass="name">class:inherit</span><spanclass="arglist">(...)</span><aclass="top"href="#Class">^ top</a></h4><p> 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).</p><p><spanclass="warning">Be careful with changing table values in a subclass: This will change the
value in the parent class too.</span></p><p> 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.</p><p> Note: <code>class:inherit()</code> doesn't actually care if the arguments supplied are
hump classes. Just any table will work.</p><divclass="arguments">Parameters:<dl><dt>tables <code>...</code></dt><dd>Parent classes to inherit from</dd></dl></div><divclass="returns">Returns:<dl><dt>Nothing.</dt></dl></div><divclass="example">Example:<pre><codeclass="lua">Class = require 'hump.class'
function Spaceship:collision_handler["Spaceship"](other, dx, dy)
-- ...
end
</code></pre></div></div><aname="Class-object:is_a"></a><divclass="ref-block"><h4>function <spanclass="name">object:is_a</span><spanclass="arglist">(cls)</span><aclass="top"href="#Class">^ top</a></h4><p>Tests whether an object is an instance of a class.</p><divclass="arguments">Parameters:<dl><dt>class <code>cls</code></dt><dd>Class to test. Note: this is the class itself, <em>not</em> the name of the class.</dd></dl></div><divclass="returns">Returns:<dl><dt>Boolean</dt><dd><code>true</code> if the object is an instance of the class, <code>false</code> otherwise</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">Class = require 'hump.class'
</code></pre></div></div><aname="Class-caveats"></a><divclass="section-block"><h4>Caveats</h4><p> Be careful when using metamethods like <code>__add</code> or <code>__mul</code>: 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:
instance:foo() -- prints only foo</code></pre></p></div></div>
<aname="Camera"></a><divclass="outer-block"><h3>hump.camera<aclass="top"href="#top">^ top</a></h3><divclass="preamble"><pre><codeclass="lua">hump.camera = require "Camera"</code></pre><spanclass="warning">Depends on hump.vector</span></p><p> 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.</div><divclass="overview"><h4>Module overview</h4><dl><dt><ahref="#Camera-new">new()</a></dt><dd>Create a new camera object.</dd><dt><ahref="#Camera-camera:rotate">camera:rotate()</a></dt><dd>Rotate camera object.</dd><dt><ahref="#Camera-camera:move">camera:move()</a></dt><dd>Move camera object.</dd><dt><ahref="#Camera-camera:attach">camera:attach()</a></dt><dd>Attach camera object.</dd><dt><ahref="#Camera-camera:detach">camera:detach()</a></dt><dd>Detach camera object.</dd><dt><ahref="#Camera-camera:draw">camera:draw()</a></dt><dd>Attach, draw and detach.</dd><dt><ahref="#Camera-camera:worldCoords">camera:worldCoords()</a></dt><dd>Convert point to world coordinates.</dd><dt><ahref="#Camera-camera:cameraCoords">camera:cameraCoords()</a></dt><dd>Convert point to camera coordinates.</dd><dt><ahref="#Camera-camera:mousepos">camera:mousepos()</a></dt><dd>Get mouse position in world coordinates.</dd></dl></div><aname="Camera-new"></a><divclass="ref-block"><h4>function <spanclass="name">new</span><spanclass="arglist">(pos, zoom, rot)</span><aclass="top"href="#Camera">^ top</a></h4><p> Creates a new camera object. You can access the camera position using
<code>camera.pos</code>, the zoom using <code>camera.zoom</code> and the rotation using
<code>camera.rot</code>.</p><p> The module variable name can be used at a shortcut to <code>new()</code>.</p><divclass="arguments">Parameters:<dl><dt>vector <code>pos</code> (screen center)</dt><dd>Point for the camera to look at.</dd><dt>number <code>zoom</code> (1)</dt><dd>Camera zoom.</dd><dt>number <code>rot</code> (0)</dt><dd>Camera rotation in radians.</dd></dl></div><divclass="returns">Returns:<dl><dt>camera</dt><dd>A new camera object.</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">camera = require 'hump.camera'
vector = require 'hump.vector'
-- camera looking at (100,100) with zoom 2 and rotated by 45 degrees
cam = camera(vector(100,100), 2, math.pi/2)
</code></pre></div></div><aname="Camera-camera:rotate"></a><divclass="ref-block"><h4>function <spanclass="name">camera:rotate</span><spanclass="arglist">(angle)</span><aclass="top"href="#Camera">^ top</a></h4><p> Rotate the camera <em>by</em> some angle. To <em>set</em> the angle use
<code>camera.rot = new_angle</code>.</p><p> This function is shortcut to <code>camera.rot = camera.rot + angle</code>.</p><divclass="arguments">Parameters:<dl><dt>number <code>angle</code></dt><dd>Rotation angle in radians</dd></dl></div><divclass="returns">Returns:<dl><dt>camera</dt><dd>The camera object.</dd></dl></div><divclass="example">Examples:<pre><codeclass="lua">function love.update(dt)
end</code></pre></div></div><aname="Camera-camera:move"></a><divclass="ref-block"><h4>function <spanclass="name">camera:move</span><spanclass="arglist">(v)</span><aclass="top"href="#Camera">^ top</a></h4><h4>function <spanclass="name">camera:move</span><spanclass="arglist">(x, y)</span><aclass="top"href="#Camera">^ top</a></h4><p><em>Move</em> the camera <em>by</em> some vector. To <em>set</em> the position, use
<code>camera.pos = some_vector</code> or <code>camera.pos.x, camera.pos.y = new_x, new_y</code>.</p><p> This function is shortcut to <code>camera.pos = camera.pos + v</code>.</p><divclass="arguments">Parameters:<dl><dt>vector <code>v</code></dt><dd>Direction to move the camera.</dd><dt>numbers <code>x, y</code></dt><dd>Direction to move the camera.</dd></dl></div><divclass="returns">Returns:<dl><dt>camera</dt><dd>The camera object.</dd></dl></div><divclass="example">Examples:<pre><codeclass="lua">function love.update(dt)
end</code></pre></div></div><aname="Camera-camera:attach"></a><divclass="ref-block"><h4>function <spanclass="name">camera:attach</span><spanclass="arglist">()</span><aclass="top"href="#Camera">^ top</a></h4><p> Start looking through the camera.</p><p> Apply camera transformations, i.e. move, scale and rotate everything until
<code>camera:detach()</code> as if looking through the camera.</p><divclass="arguments">Parameters:<dl><dt>None.</dt></dl></div><divclass="returns">Returns:<dl><dt>Nothing.</dt></dl></div><divclass="example">Example:<pre><codeclass="lua">function love.draw()
end</code></pre></div></div><aname="Camera-camera:detach"></a><divclass="ref-block"><h4>function <spanclass="name">camera:detach</span><spanclass="arglist">()</span><aclass="top"href="#Camera">^ top</a></h4><p>Stop looking through the camera.</p><divclass="arguments">Parameters:<dl><dt>None.</dt></dl></div><divclass="returns">Returns:<dl><dt>Nothing.</dt></dl></div><divclass="example">Example:<pre><codeclass="lua">function love.draw()
end</code></pre></div></div><aname="Camera-camera:draw"></a><divclass="ref-block"><h4>function <spanclass="name">camera:draw</span><spanclass="arglist">(func)</span><aclass="top"href="#Camera">^ top</a></h4><p> Wrap a function between a <code>camera:attach()</code>/<code>camera:detach()</code> pair:
cam:detach()</code></pre></p><divclass="arguments">Parameters:<dl><dt>function <code>func</code></dt><dd>Drawing function to be wrapped.</dd></dl></div><divclass="returns">Returns:<dl><dt>Nothing.</dt></dl></div><divclass="example">Example:<pre><codeclass="lua">function love.draw()
end</code></pre></div></div><aname="Camera-camera:worldCoords"></a><aname="Camera-camera:cameraCoords"></a><divclass="ref-block"><h4>function <spanclass="name">camera:worldCoords</span><spanclass="arglist">(v)</span><aclass="top"href="#Camera">^ top</a></h4><h4>function <spanclass="name">camera:worldCoords</span><spanclass="arglist">(x, y)</span><aclass="top"href="#Camera">^ top</a></h4><h4>function <spanclass="name">camera:cameraCoords</span><spanclass="arglist">(v)</span><aclass="top"href="#Camera">^ top</a></h4><h4>function <spanclass="name">camera:cameraCoords</span><spanclass="arglist">(x, y)</span><aclass="top"href="#Camera">^ top</a></h4><p> 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 <em>world coordinates</em>, the second one <em>camera coordinates</em>.
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.</p><p> These two functions convert a point between these two coordinate systems.</p><divclass="arguments">Parameters:<dl><dt>vector <code>v</code></dt><dd>Point to transform.</dd><dt>numbers <code>x, y</code></dt><dd>Point to transform.</dd></dl></div><divclass="returns">Returns:<dl><dt>vector</dt><dd>Transformed point.</dd></dl></div><divclass="example">Examples:<pre><codeclass="lua">target = camera:worldCoords( vector(love.mouse.getPosition()) )
</code></pre></div></div><aname="Camera-camera:mousepos"></a><divclass="ref-block"><h4>function <spanclass="name">camera:mousepos</span><spanclass="arglist">()</span><aclass="top"href="#Camera">^ top</a></h4><p>Shortcut to <code>camera:worldCoords(vector(love.mouse.getPosition()))</code>.</p><divclass="arguments">Parameters:<dl><dt>None.</dt></dl></div><divclass="returns">Returns:<dl><dt>vector</dt><dd>Mouse position in world coordinates.</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">target = camera:mousepos()
selectedUnit:plotPath(target)
</code></pre></div></div></div>
<aname="Ringbuffer"></a><divclass="outer-block"><h3>hump.ringbuffer<aclass="top"href="#top">^ top</a></h3><divclass="preamble"><pre><codeclass="lua">hump.ringbuffer = require "Ringbuffer"</code></pre> A ring-buffer is a circular array: It does not have a first nor a last item,
but it has a <em>selected</em> or <em>current</em> element.</p><p> A ring-buffer can be used to implement <em>Tomb Raider</em> style inventories, looping
play-lists, recurring dialogs (like a unit's answers when selecting it multiple
times in <em>Warcraft</em>) and generally everything that has a circular or looping
structure.</div><divclass="overview"><h4>Module overview</h4><dl><dt><ahref="#Ringbuffer-new">new()</a></dt><dd>Create new ring-buffer.</dd><dt><ahref="#Ringbuffer-ringbuffer:insert">ringbuffer:insert()</a></dt><dd>Insert element.</dd><dt><ahref="#Ringbuffer-ringbuffer:remove">ringbuffer:remove()</a></dt><dd>Remove currently selected item.</dd><dt><ahref="#Ringbuffer-ringbuffer:removeAt">ringbuffer:removeAt()</a></dt><dd>Remove an item.</dd><dt><ahref="#Ringbuffer-ringbuffer:next">ringbuffer:next()</a></dt><dd>Select next item.</dd><dt><ahref="#Ringbuffer-ringbuffer:prev">ringbuffer:prev()</a></dt><dd>Select previous item.</dd><dt><ahref="#Ringbuffer-ringbuffer:get">ringbuffer:get()</a></dt><dd>Get currently selected item.</dd><dt><ahref="#Ringbuffer-ringbuffer:size">ringbuffer:size()</a></dt><dd>Get ringbuffer size.</dd></dl></div><aname="Ringbuffer-new"></a><divclass="ref-block"><h4>function <spanclass="name">new</span><spanclass="arglist">(...)</span><aclass="top"href="#Ringbuffer">^ top</a></h4><p>Create new ring-buffer.</p><p>The module name is a shortcut to this function.</p><divclass="arguments">Parameters:<dl><dt>mixed <code>...</code></dt><dd>Initial elements.</dd></dl></div><divclass="returns">Returns:<dl><dt>Ringbuffer</dt><dd>The ring-buffer object.</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">Ringbuffer = require 'hump.ringbuffer'
rb = ringbuffer(1,2,3)
</code></pre></div></div><aname="Ringbuffer-ringbuffer:insert"></a><divclass="ref-block"><h4>function <spanclass="name">ringbuffer:insert</span><spanclass="arglist">(...)</span><aclass="top"href="#Ringbuffer">^ top</a></h4><p>Insert items behind current element.</p><divclass="arguments">Parameters:<dl><dt>mixed <code>...</code></dt><dd>Items to insert.</dd></dl></div><divclass="returns">Returns:<dl><dt>Nothing.</dt></dl></div><divclass="example">Example:<pre><codeclass="lua">rb = RingbuffeR(1,5,6) -- content: 1,5,6
rb:insert(2,3,4) -- content: 1,2,3,4,5,6
</code></pre></div></div><aname="Ringbuffer-ringbuffer:remove"></a><divclass="ref-block"><h4>function <spanclass="name">ringbuffer:remove</span><spanclass="arglist">()</span><aclass="top"href="#Ringbuffer">^ top</a></h4><p>Remove current item, return it and select next element.</p><divclass="arguments">Parameters:<dl><dt>None.</dt></dl></div><divclass="returns">Returns:<dl><dt>mixed</dt><dd>The removed item.</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">rb = Ringbuffer(1,2,3,4) -- content: 1,2,3,4
val = rb:remove() -- content: 2,3,4
print(val) -- prints `1'
</code></pre></div></div><aname="Ringbuffer-ringbuffer:removeAt"></a><divclass="ref-block"><h4>function <spanclass="name">ringbuffer:removeAt</span><spanclass="arglist">(pos)</span><aclass="top"href="#Ringbuffer">^ top</a></h4><p>Remove the item at a position relative to the current element.</p><divclass="arguments">Parameters:<dl><dt>number <code>pos</code></dt><dd>Position of the item to remove.</dd></dl></div><divclass="returns">Returns:<dl><dt>mixed</dt><dd>The removed item.</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">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
</code></pre></div></div><aname="Ringbuffer-ringbuffer:next"></a><divclass="ref-block"><h4>function <spanclass="name">ringbuffer:next</span><spanclass="arglist">()</span><aclass="top"href="#Ringbuffer">^ top</a></h4><p>Select and return the next element.</p><divclass="arguments">Parameters:<dl><dt>None.</dt></dl></div><divclass="returns">Returns:<dl><dt>mixed</dt><dd>The next item.</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">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'
</code></pre></div></div><aname="Ringbuffer-ringbuffer:prev"></a><divclass="ref-block"><h4>function <spanclass="name">ringbuffer:prev</span><spanclass="arglist">()</span><aclass="top"href="#Ringbuffer">^ top</a></h4><p>Select and return the previous item.</p><divclass="arguments">Parameters:<dl><dt>None.</dt></dl></div><divclass="returns">Returns:<dl><dt>mixed</dt><dd>The previous item.</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">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'
</code></pre></div></div><aname="Ringbuffer-ringbuffer:get"></a><divclass="ref-block"><h4>function <spanclass="name">ringbuffer:get</span><spanclass="arglist">()</span><aclass="top"href="#Ringbuffer">^ top</a></h4><p>Return the current element.</p><divclass="arguments">Parameters:<dl><dt>None.</dt></dl></div><divclass="returns">Returns:<dl><dt>mixed</dt><dd>The currently selected element.</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">rb = Ringbuffer(1,2,3)
rb:next() -- content: 2,3,1
print(rb:get()) -- prints '2'
</code></pre></div></div><aname="Ringbuffer-ringbuffer:size"></a><divclass="ref-block"><h4>function <spanclass="name">ringbuffer:size</span><spanclass="arglist">()</span><aclass="top"href="#Ringbuffer">^ top</a></h4><p>Get number of items in the buffer</p><divclass="arguments">Parameters:<dl><dt>None.</dt></dl></div><divclass="returns">Returns:<dl><dt>number</dt><dd>Number of items in the buffer.</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">rb = Ringbuffer(1,2,3)
