<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><htmlxmlns="http://www.w3.org/1999/xhtml"xml:lang="en"lang="en"><head><metahttp-equiv="Content-Type"content="text/html; charset=utf-8"/><title>hump - LÖVE Helper Utilities for More Productivity</title><linkrel="stylesheet"type="text/css"href="style.css"/><linkrel="stylesheet"type="text/css"href="highlight.css"/><scripttype="text/javascript"src="highlight.pack.js"></script><scripttype="text/javascript">window.onload=function(){varexamples=document.getElementsByTagName("code");for(i=0;i<examples.length;++i){if(examples[i].className=="lua")hljs.highlightBlock(examples[i]," ");}};</script></head><body><aname="top"id="top"></a><divid="header"><h1><ahref="http://github.com/vrld/hump">hump</a><spanclass="small"> Helper Utilities for More Productivity</span></h1><ulid="main-nav"><li><ahref="#intro">Introduction</a></li><li><ahref="#doc">Documentation</a></li><li><ahref="#license">License</a></li><li><ahref="#download">Download</a></li></ul><h2> </h2></div><aname="intro"id="intro"></a><divclass="outer-block"><h3>Introduction<aclass="top"href="#top">^ top</a></h3><divclass="preamble"><p><em>Helper Utilities for a Multitude of Problems</em> is a set of lightweight helpers for the <strong>awesome</strong><ahref="http://love2d.org/">LÖVE</a> Engine.</p><p><em>hump</em> differs from other libraries in that every component is independent of the remaining ones (apart from camera.lua, which does depends on vector-light.lua). <em>hump</em>'s footprint is very small and thus should fit nicely into your projects.</p></div></div><aname="doc"></a><divclass="outer-block"><h3>Documentation<aclass="top"href="#top">^ top</a></h3><divclass="preamble"><dl><dt><ahref="#Gamestate">hump.gamestate</a></dt><dd>A gamestate system</dd><dt><ahref="#Timer">hump.timer</a></dt><dd>Delayed function calls and helpers for interpolating functions.</dd><dt><ahref="#vector">hump.vector</a></dt><dd>2D vector math.</dd><dt><ahref="#vector-light">hump.vector-light</a></dt><dd>Lightweight 2D vector math.</dd><dt><ahref="#Class">hump.class</a></dt><dd>Class-based object orientated programming for Lua</dd><dt><ahref="#Signal">hump.signal</a></dt><dd>Simple Signal/Slot (aka. Observer) implementation.</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"id="Gamestate"></a><divclass="outer-block"><h3>hump.gamestate<aclass="top"href="#top">^ top</a></h3><divclass="preamble"><pre><codeclass="lua">Gamestate = require "hump.gamestate"</code></pre><p>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>.</p></div><divclass="overview"><h4>Module overview</h4><dl><dt><ahref="#Gamestate-callbacks">callbacks</a></dt><dd>Gamestate Callbacks</dd><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 curren
end</code></pre></div></div><aname="Gamestate-new"id="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"id="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 <codeclass="lua">leave()</code> callback on the current gamestate, replace the current gamestate with to, call the <codeclass="lua">init()</code> function if the state was not yet inialized and finally call <codeclass="lua">enter(old_state, ...)</code> 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"id="Gamestate-update"></a><aname="Gamestate-draw"id="Gamestate-draw"></a><aname="Gamestate-focus"id="Gamestate-focus"></a><aname="Gamestate-keypressed"id="Gamestate-keypressed"></a><aname="Gamestate-keyreleased"id="Gamestate-keyreleased"></a><aname="Gamestate-mousepressed"id="Gamestate-mousepressed"></a><aname="Gamestate-mousereleased"id="Gamestate-mousereleased"></a><aname="Gamestate-joystickpressed"id="Gamestate-joystickpressed"></a><aname="Gamestate-joystickreleased"id="Gamestate-joystickreleased"></a><aname="Gamestate-quit"id="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 <codeclass="lua">registerEvents()</code>.</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"id="Gamestate-registerEvents"></a><divclass="ref-block"><h4>function <spanclass="name">registerEvents</span><spanclass="arglist">(callbacks)</span><aclass="top"href="#Gamestate">^ top</a></h4><p>Register love callbacks to call <codeclass="lua">Gamestate.update()</code>, <codeclass="lua">Gamestate.draw()</code>, etc. automatically.</p><p>This is by done by overwriting the love callbacks, e.g.: <pre><codeclass="lua">local old_update = love.update
end</code></pre></p><p><spanclass="warning">Note:</span> Only works when called in <codeclass="lua">love.load()</code> or any other function that is executedafter the whole file is loaded.</p><divclass="arguments">Parameters:<dl><dt>table <code>callbacks</code> (optional)</dt><dd>Names of the callbacks to register. If omitted, register all callbacks.</dd></dl></div><divclass="returns">Returns:<dl><dt>Nothing</dt></dl></div><divclass="example">Example:<pre><codeclass="lua">function love.load()
end</code></pre></div></div></div><aname="Timer"id="Timer"></a><divclass="outer-block"><h3>hump.timer<aclass="top"href="#top">^ top</a></h3><divclass="preamble"><pre><codeclass="lua">Timer = require "hump.timer"</code></pre><p>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.</p></div><divclass="overview"><h4>Module overview</h4><dl><dt><ahref="#Timer-new">new()</a></dt><dd>Create new timer instance.</dd><dt><ahref="#Timer-add">add()</a></dt><dd>Schedule a function.</dd><dt><ahref="#Timer-addPeriodic">addPeriodic()</a></dt><dd>Add a periodic function.</dd><dt><ahref="#Timer-cancel">cancel()</a></dt><dd>Cancel a scheduled 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 scheduled 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-new"id="Timer-new"></a><divclass="ref-block"><h4>function <spanclass="name">new</span><spanclass="arglist">()</span><aclass="top"href="#Timer">^ top</a></h4><p><spanclass="warning">If you don't need multiple independent schedulers, you can use the global/default timer (see examples).</span></p><p>Creates a new timer instance that is independent of the global timer: It will manage it's own list of scheduled functions and does not in any way affect the the global timer. Likewise, the global timer does not affect the timer instance.</p><p><spanclass="warning">Note:</span> Timer instances use the colon-notation (e.g. <codeclass="lua">instance:update(dt)</code>), while the global timer uses the dot-notation (e.g. <codeclass="lua">Timer.update(dt)</code>).</p><divclass="arguments">Parameters:<dl><dt>None</dt></dl></div><divclass="returns">Returns:<dl><dt>Timer</dt><dd>A timer instance</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">menuTimer = Timer.new()</code></pre></div></div><aname="Timer-add"id="Timer-add"></a><aname="Timer-instance:add"id="Timer-instance:add"></a><divclass="ref-block"><h4>function <spanclass="name">add</span><spanclass="arglist">(delay, func)</span><aclass="top"href="#Timer">^ top</a></h4><h4>function <spanclass="name">instance:add</span><spanclass="arglist">(delay, func)</span><aclass="top"href="#Timer">^ top</a></h4><p>Schedule a function. The function will be executed after <codeclass="lua">delay</code> seconds have elapsed, given that <codeclass="lua">update(dt)</code> 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>It is an error to schedule a function again if it is not yet finished or canceled.</p><p><codeclass="lua">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>function</dt><dd>The timer handle.</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">-- grant the player 5 seconds of immortality
Timer.add(1, function(func) print("foo") Timer.add(1, func) end)</code></pre><pre><codeclass="lua">menuTimer:add(1, finishAnimation)</code></pre></div></div><aname="Timer-addPeriodic"id="Timer-addPeriodic"></a><aname="Timer-instance:addPeriodic"id="Timer-instance:addPeriodic"></a><divclass="ref-block"><h4>function <spanclass="name">addPeriodic</span><spanclass="arglist">(delay, func, count)</span><aclass="top"href="#Timer">^ top</a></h4><h4>function <spanclass="name">instance:addPeriodic</span><spanclass="arglist">(delay, func, count)</span><aclass="top"href="#Timer">^ top</a></h4><p>Add a function that will be called <codeclass="lua">count</code> times every <codeclass="lua">delay</code> seconds.</p><p>If <codeclass="lua">count</code> is omitted, the function will be called until it returns <codeclass="lua">false</code> or <codeclass="lua">clear()</code> 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>function</dt><dd>The timer handle.</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">Timer.addPeriodic(1, function() lamp:toggleLight() end)</code></pre><pre><codeclass="lua">mothership_timer:addPeriodic(0.3, function() self:spawnFighter() end, 5)</code></pre><pre><codeclass="lua">-- flicker player's image as long as he is invincible
end)</code></pre></div></div><aname="Timer-cancel"id="Timer-cancel"></a><aname="Timer-instance:cancel"id="Timer-instance:cancel"></a><divclass="ref-block"><h4>function <spanclass="name">cancel</span><spanclass="arglist">(func)</span><aclass="top"href="#Timer">^ top</a></h4><h4>function <spanclass="name">instance:cancel</span><spanclass="arglist">(func)</span><aclass="top"href="#Timer">^ top</a></h4><p>Prevent a timer from being executed in the future.</p><p><em>Always</em> use the function handle returned by <codeclass="lua">add()</code>/<codeclass="lua">addPeriodic()</code> to cancel a timer.</p><p><em>Never</em> use this inside a scheduled function.</p><divclass="arguments">Parameters:<dl><dt>function <code>func</code></dt><dd>The function to be canceled.</dd></dl></div><divclass="returns">Returns:<dl><dt>Nothing</dt></dl></div><divclass="example">Example:<pre><codeclass="lua">function tick()
Timer.cancel(handle) -- NOT: Timer.cancel(tick)</code></pre></div></div><aname="Timer-clear"id="Timer-clear"></a><aname="Timer-instance:clear"id="Timer-instance:clear"></a><divclass="ref-block"><h4>function <spanclass="name">clear</span><spanclass="arglist">()</span><aclass="top"href="#Timer">^ top</a></h4><h4>function <spanclass="name">instance: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. <em>Never</em> use this inside a scheduled function.</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"id="Timer-update"></a><aname="Timer-instance:update"id="Timer-instance:update"></a><divclass="ref-block"><h4>function <spanclass="name">update</span><spanclass="arglist">(dt)</span><aclass="top"href="#Timer">^ top</a></h4><h4>function <spanclass="name">instance: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 <codeclass="lua">love.update(dt)</code>.</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"id="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: <pre><codeclass="lua">function wrapper(dt, ...)</code></pre> where <codeclass="lua">dt</code> is the time that has passed since the last call of the wrapper and <codeclass="lua">...</code> 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.</p><p>The prototype of the interpolating function is: <pre><codeclass="lua">function interpolator(fraction, ...)</code></pre> where <codeclass="lua">fraction</code> is a number between 0 and 1 depending on how much time has passed and <codeclass="lua">...</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"id="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 <codeclass="lua">Interpolator()</code>: <pre><codeclass="lua">function wrapper(dt, ...)</code></pre><pre><codeclass="lua">function oscillator(fraction, ...)</code></pre></p><p>As with <codeclass="lua">Interpolator</code>, the wrapper will return whatever <codeclass="lua">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)
end</code></pre></div></div></div><aname="vector"id="vector"></a><divclass="outer-block"><h3>hump.vector<aclass="top"href="#top">^ top</a></h3><divclass="preamble"><pre><codeclass="lua">vector = require "hump.vector"</code></pre><p>A handy 2D vector class providing most of the things you do with vectors.</p><p>You can access the individual coordinates by using <codeclass="lua">vec.x</code> and <codeclass="lua">vec.y</code>.</p></div><divclass="overview"><h4>Module overview</h4><dl><dt><ahref="#vector-operators">operators</a></dt><dd>Arithmetics and relations</dd><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"id="vector-operators"></a><divclass="section-block"><h4>Arithmetics and relations<aclass="top"href="#vector">^ top</a></h4><p>Vector arithmetic is implemented by using <codeclass="lua">__add</code>, <codeclass="lua">__mul</code> and other metamethods:</p><p><dl><dt><codeclass="lua">vector + vector = vector</code></dt><dd>Component wise sum.</dd><dt><codeclass="lua">vector - vector = vector</code></dt><dd>Component wise difference.</dd><dt><codeclass="lua">vector * vector = number</code></dt><dd>Dot product.</dd><dt><codeclass="lua">number * vector = vector</code></dt><dd>Scalar multiplication (scaling).</dd><dt><codeclass="lua">vector * number = vector</code></dt><dd>Scalar multiplication.</dd><dt><codeclass="lua">vector / number = vector</code></dt><dd>Scalar multiplication.</dd></dl></p><p>Relational operators are defined, too:</p><p><dl><dt>a == b</dt><dd><codeclass="lua">true</code>, if <codeclass="lua">a.x == b.x</code> and <codeclass="lua">a.y == b.y</code>.</dd><dt>a <= b</dt><dd><codeclass="lua">true</code>, if <codeclass="lua">a.x <= b.x</code> and <codeclass="lua">a.y <= b.y</code>.</dd><dt>a <b</dt><dd>Lexical sort: <codeclass="lua">true</code>, if <codeclass="lua">a.x <b.x</code> or <codeclass="lua">a.x == b.x</code> and <codeclass="lua">a.y <b.y</code>.</dd></dl></p><divclass="example">Example:<pre><codeclass="lua">-- acceleration, player.velocity and player.position are vectors
player.position = player.position + player.velocity * dt</code></pre></div></div><aname="vector-new"id="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">Example:<pre><codeclass="lua">a = vector.new(10,10)</code></pre><pre><codeclass="lua">-- as a shortcut, you can call the module like a function:
a = vector(10,10)</code></pre></div></div><aname="vector-isvector"id="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><codeclass="lua">true</code> if <codeclass="lua">v</code> is a vector, <codeclass="lua">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"id="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 would also change the old one: <pre><codeclass="lua">a = vector(1,1) -- create vector
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"id="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">Example:<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"id="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. <codeclass="lua">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"id="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. <codeclass="lua">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"id="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. <codeclass="lua">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"id="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 <codeclass="lua">(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"id="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"id="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 <codeclass="lua">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"id="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:<imgsrc="vector-rotated.png"width="260"height="171"/></div></div><aname="vector-vector:rotate_inplace"id="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 <codeclass="lua">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"id="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 (but faster) as <codeclass="lua">vec:rotate(math.pi/2)</code></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:<imgsrc="vector-perpendicular.png"width="267"height="202"/></div></div><aname="vector-vector:projectOn"id="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:<imgsrc="vector-projectOn.png"width="605"height="178"/></div></div><aname="vector-vector:mirrorOn"id="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 vector.</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_normal)</code></pre></div><divclass="example">Sketch:<imgsrc="vector-mirrorOn.png"width="334"height="201"/></div></div><aname="vector-vector:cross"id="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. Equals 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><divclass="example">Sketch:<imgsrc="vector-cross.png"width="271"height="137"/></div></div></div><aname="vector-light"id="vector-light"></a><divclass="outer-block"><h3>hump.vector-light<aclass="top"href="#top">^ top</a></h3><divclass="preamble"><pre><codeclass="lua">vector = require "hump.vector-light"</code></pre><p>An table-free version of <codeclass="lua">hump.vector</code>. Instead of a vector class, <codeclass="lua">hump.vector-light</code> provides functions that operate on numbers.</p><p>Using this module instead of <codeclass="lua">vector</code> 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 <codeclass="lua">hump.vector</code>.</p></div><divclass="overview"><h4>Module overview</h4><dl><dt><ahref="#vector-light-str">str()</a></dt><dd>String representation.</dd><dt><ahref="#vector-light-mul">mul()</a></dt><dd>Product of a vector and a scalar.</dd><dt><ahref="#vector-light-div">div()</a></dt><dd>Product of a vector and the inverse of a scalar.</dd><dt><ahref="#vector-light-add">add()</a></dt><dd>Sum of two vectors.</dd><dt><ahref="#vector-light-sub">sub()</a></dt><dd>D
end</code></pre></div></div><aname="vector-light-dist"id="vector-light-dist"></a><divclass="ref-block"><h4>function <spanclass="name">dist</span><spanclass="arglist">(x1,y1, x2,y2)</span><aclass="top"href="#vector-light">^ top</a></h4><p>Get distance of two points. The same as <codeclass="lua">vector.len(x1-x2, y1-y2)</code>.</p><divclass="arguments">Parameters:<dl><dt>numbers <code>x1,y1</code></dt><dd>First vector.</dd><dt>numbers <code>x2,y2</code></dt><dd>Second vector.</dd></dl></div><divclass="returns">Returns:<dl><dt>number</dt><dd>The distance of the points.</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">-- get closest vertex to a given vector
end</code></pre></div></div><aname="vector-light-normalize"id="vector-light-normalize"></a><divclass="ref-block"><h4>function <spanclass="name">normalize</span><spanclass="arglist">(x,y)</span><aclass="top"href="#vector-light">^ top</a></h4><p>Get normalized vector, i.e. a vector with the same direction as the input vector, but with length 1.</p><divclass="arguments">Parameters:<dl><dt>numbers <code>x,y</code></dt><dd>The vector.</dd></dl></div><divclass="returns">Returns:<dl><dt>numbers</dt><dd>Vector with same direction as the input vector, but length 1.</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">dx,dy = vector.normalize(vx,vy)</code></pre></div></div><aname="vector-light-rotate"id="vector-light-rotate"></a><divclass="ref-block"><h4>function <spanclass="name">rotate</span><spanclass="arglist">(phi, x,y)</span><aclass="top"href="#vector-light">^ top</a></h4><p>Get a rotated 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><dt>numbers <code>x,y</code></dt><dd>The vector.</dd></dl></div><divclass="returns">Returns:<dl><dt>numbers</dt><dd>The rotated vector</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">-- approximate a circle
end</code></pre></div></div><aname="vector-light-perpendicular"id="vector-light-perpendicular"></a><divclass="ref-block"><h4>function <spanclass="name">perpendicular</span><spanclass="arglist">(x,y)</span><aclass="top"href="#vector-light">^ top</a></h4><p>Quick rotation by 90°. The same (but faster) as <codeclass="lua">vector.rotate(math.pi/2, x,y)</code></p><divclass="arguments">Parameters:<dl><dt>numbers <code>x,y</code></dt><dd>The vector.</dd></dl></div><divclass="returns">Returns:<dl><dt>numbers</dt><dd>A vector perpendicular to the input vector</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">nx,ny = vector.normalize(vector.perpendicular(bx-ax, by-ay))</code></pre></div></div><aname="vector-light-project"id="vector-light-project"></a><divclass="ref-block"><h4>function <spanclass="name">project</span><spanclass="arglist">(x,y, u,v)</span><aclass="top"href="#vector-light">^ top</a></h4><p>Project vector onto another vector.</p><divclass="arguments">Parameters:<dl><dt>numbers <code>x,y</code></dt><dd>The vector to project.</dd><dt>numbers <code>u,v</code></dt><dd>The vector to project onto.</dd></dl></div><divclass="returns">Returns:<dl><dt>numbers</dt><dd>The projected vector.</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">vx_p,vy_p = vector.project(vx,vy, ax,ay)</code></pre></div></div><aname="vector-light-mirror"id="vector-light-mirror"></a><divclass="ref-block"><h4>function <spanclass="name">mirror</span><spanclass="arglist">(x,y, u,v)</span><aclass="top"href="#vector-light">^ top</a></h4><p>Mirrors vector on the axis defined by the other vector.</p><divclass="arguments">Parameters:<dl><dt>numbers <code>x,y</code></dt><dd>The vector to mirror.</dd><dt>numbers <code>u,v</code></dt><dd>The vector defining the axis.</dd></dl></div><divclass="returns">Returns:<dl><dt>numbers</dt><dd>The mirrored vector.</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">vx,vy = vector.mirror(vx,vy, surface.x,surface.y)</code></pre></div></div></div><aname="Class"id="Class"></a><divclass="outer-block"><h3>hump.class<aclass="top"href="#top">^ top</a></h3><divclass="preamble"><pre><codeclass="lua">Class = require "hump.class"</code></pre><p>A small, fast class implementation with multiple inheritance support</p></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><dt><ahref="#Class-caveats">caveats</a></dt><dd>Caveats</dd></dl></div><aname="Class-new"id="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>You can check if an object is an instance of a class using <codeclass="lua">object:is_a()</code>.</p><p>The name of the variable that holds the module can be used as a shortcut to <codeclass="lua">new()</code> (see example).</p><divclass="arguments">Parameters:<dl><dt>function <code>constructor</code> (optional)</dt><dd>Class constructor. Can be accessed with <codeclass="lua">theclass.construct(object, ...)</code></dd><dt>string <code>the_name</code> (optional)</dt><dd>Class name (used only to make the class compliant to <codeclass="lua">tostring()</code>.</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">Example:<pre><codeclass="lua">Class = require 'hump.class' -- `Class' is now a shortcut to new()
</code></pre></div></div><aname="Class-class.construct"id="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 <codeclass="lua">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">Example:<pre><codeclass="lua">Class = require 'hump.class'
</code></pre></div></div><aname="Class-class:inherit"id="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: <codeclass="lua">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'
</code></pre></div></div><aname="Class-object:is_a"id="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><codeclass="lua">true</code> if the object is an instance of the class, <codeclass="lua">false</code> otherwise</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">Class = require 'hump.class'
</code></pre></div></div><aname="Class-caveats"id="Class-caveats"></a><divclass="section-block"><h4>Caveats<aclass="top"href="#Class">^ top</a></h4><p>Be careful when using metamethods like <codeclass="lua">__add</code> or <codeclass="lua">__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: <pre><codeclass="lua">Class = require 'hump.class'
result:foo() -- error: method does not exist</code></pre></p><p>Note that while you can define the <codeclass="lua">__index</code> metamethod of the class, this is not a good idea: It will break the class. To add a custom <codeclass="lua">__index</code> metamethod without breaking the class system, you have to use <codeclass="lua">rawget()</code>. But beware that this won't affect subclasses: <pre><codeclass="lua">Class = require 'hump.class'
instance:foo() -- prints only foo</code></pre></p></div></div><aname="Signal"id="Signal"></a><divclass="outer-block"><h3>hump.signal<aclass="top"href="#top">^ top</a></h3><divclass="preamble"><pre><codeclass="lua">Signal = require "hump.signal"</code></pre><p>A simple yet effective implementation of <ahref="http://en.wikipedia.org/wiki/Signals_and_slots">Signals and Slots</a>, also known as <ahref="http://en.wikipedia.org/wiki/Observer_pattern">Observer pattern</a>: Functions can be dynamically bound to <em>signals</em>. When a signal is <em>emitted</em>, all registered functions will be invoked. Simple as that.</p><p><codeclass="lua">hump.signal</code> makes things more interesing by allowing to emit all signals that match a <ahref="http://www.lua.org/manual/5.1/manual.html#5.4.1">Lua string
pattern</a>.</p></div><divclass="overview"><h4>Module overview</h4><dl><dt><ahref="#Signal-new">new()</a></dt><dd>Create new signal registry.</dd><dt><ahref="#Signal-register">register()</a></dt><dd>Register function with a signal.</dd><dt><ahref="#Signal-emit">emit()</a></dt><dd>Call all functions bound to a signal.</dd><dt><ahref="#Signal-remove">remove()</a></dt><dd>Remove functions from registry.</dd><dt><ahref="#Signal-clear">clear()</a></dt><dd>Clears a signal registry.</dd><dt><ahref="#Signal-emit_pattern">emit_pattern()</a></dt><dd>Emits signals matching a pattern.</dd><dt><ahref="#Signal-remove_pattern">remove_pattern()</a></dt><dd>Remove functions from signals matching a pattern.</dd><dt><ahref="#Signal-clear_pattern">clear_pattern()</a></dt><dd>Clears signal registry matching a pattern.</dd></dl></div><aname="Signal-new"id="Signal-new"></a><divclass="ref-block"><h4>function <spanclass="name">new</span><spanclass="arglist">()</span><aclass="top"href="#Signal">^ top</a></h4><p><spanclass="warning">If you don't need multiple independent registries, you can use the global/default registry (see examples).</span></p><p>Creates a new signal registry that is independent of the default registry: It will manage it's own list of signals and does not in any way affect the the global registry. Likewise, the global registry does not affect the instance.</p><p><spanclass="warning">Note:</span> Independent registries use the colon-notation (e.g. <codeclass="lua">instance:emit("foo")</code>), while the global registry uses the dot-notation (e.g. <codeclass="lua">Signal.emit("foo")</code>).</p><divclass="arguments">Parameters:<dl><dt>None</dt></dl></div><divclass="returns">Returns:<dl><dt>Registry</dt><dd>A new signal registry.</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">player.signals = Signals.new()</code></pre></div></div><aname="Signal-register"id="Signal-register"></a><aname="Signal-instance:register"id="Signal-instance:register"></a><divclass="ref-block"><h4>function <spanclass="name">register</span><spanclass="arglist">(s, f)</span><aclass="top"href="#Signal">^ top</a></h4><h4>function <spanclass="name">instance:register</span><spanclass="arglist">(s, f)</span><aclass="top"href="#Signal">^ top</a></h4><p>Registers a function <codeclass="lua">f</code> to be called when signal <codeclass="lua">s</code> is emitted. </p><divclass="arguments">Parameters:<dl><dt>string <code>s</code></dt><dd>The signal identifier.</dd><dt>function <code>f</code></dt><dd>The function to register.</dd></dl></div><divclass="returns">Returns:<dl><dt>function</dt><dd>A function handle to use in <codeclass="lua">remove</code>.</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">Signal.register('level-complete', function() self.fanfare:play() end)</code></pre><pre><codeclass="lua">handle = Signal.register('level-load', function(level) level.show_help() end)</code></pre><pre><codeclass="lua">menu:register('key-left', select_previous_item)</code></pre></div></div><aname="Signal-emit"id="Signal-emit"></a><aname="Signal-instance:emit"id="Signal-instance:emit"></a><divclass="ref-block"><h4>function <spanclass="name">emit</span><spanclass="arglist">(s, ...)</span><aclass="top"href="#Signal">^ top</a></h4><h4>function <spanclass="name">instance:emit</span><spanclass="arglist">(s, ...)</span><aclass="top"href="#Signal">^ top</a></h4><p>Calls all functions bound to signal <codeclass="lua">s</code> with the supplied arguments. </p><divclass="arguments">Parameters:<dl><dt>string <code>s</code></dt><dd>The signal identifier.</dd><dt>mixed <code>...</code> (optional)</dt><dd>Arguments to pass to the bound functions.</dd></dl></div><divclass="returns">Returns:<dl><dt>Nothing</dt></dl></div><divclass="example">Example:<pre><codeclass="lua">function love.keypressed(key)
if key == 'left' then menu:emit('key-left') end
end</code></pre><pre><codeclass="lua">if level.is_finished() then
end</code></pre></div></div><aname="Signal-remove"id="Signal-remove"></a><aname="Signal-instance:remove"id="Signal-instance:remove"></a><divclass="ref-block"><h4>function <spanclass="name">remove</span><spanclass="arglist">(s, ...)</span><aclass="top"href="#Signal">^ top</a></h4><h4>function <spanclass="name">instance:remove</span><spanclass="arglist">(s, ...)</span><aclass="top"href="#Signal">^ top</a></h4><p>Unbinds (removes) functions from signal <codeclass="lua">s</code>. </p><divclass="arguments">Parameters:<dl><dt>string <code>s</code></dt><dd>The signal identifier.</dd><dt>functions <code>...</code></dt><dd>Functions to unbind from the signal.</dd></dl></div><divclass="returns">Returns:<dl><dt>Nothing</dt></dl></div><divclass="example">Example:<pre><codeclass="lua">Signal.remove('level-load', handle)</code></pre></div></div><aname="Signal-clear"id="Signal-clear"></a><aname="Signal-instance:clear"id="Signal-instance:clear"></a><divclass="ref-block"><h4>function <spanclass="name">clear</span><spanclass="arglist">(s)</span><aclass="top"href="#Signal">^ top</a></h4><h4>function <spanclass="name">instance:clear</span><spanclass="arglist">(s)</span><aclass="top"href="#Signal">^ top</a></h4><p>Removes all functions from signal <codeclass="lua">s</code>. </p><divclass="arguments">Parameters:<dl><dt>string <code>s</code></dt><dd>The signal identifier.</dd></dl></div><divclass="returns">Returns:<dl><dt>Nothing</dt></dl></div><divclass="example">Example:<pre><codeclass="lua">Signal.clear('key-left')</code></pre></div></div><aname="Signal-emit_pattern"id="Signal-emit_pattern"></a><aname="Signal-instance:emit_pattern"id="Signal-instance:emit_pattern"></a><divclass="ref-block"><h4>function <spanclass="name">emit_pattern</span><spanclass="arglist">(p, ...)</span><aclass="top"href="#Signal">^ top</a></h4><h4>function <spanclass="name">instance:emit_pattern</span><spanclass="arglist">(p, ...)</span><aclass="top"href="#Signal">^ top</a></h4><p>Emits all signals matching a <ahref="http://www.lua.org/manual/5.1/manual.html#5.4.1">string pattern</a>. </p><divclass="arguments">Parameters:<dl><dt>string <code>p</code></dt><dd>The signal identifier pattern.</dd><dt>mixed <code>...</code> (optional)</dt><dd>Arguments to pass to the bound functions.</dd></dl></div><divclass="returns">Returns:<dl><dt>Nothing</dt></dl></div><divclass="example">Example:<pre><codeclass="lua">Signal.emit_pattern('^update%-.*', dt)</code></pre></div></div><aname="Signal-remove_pattern"id="Signal-remove_pattern"></a><aname="Signal-instance:remove_pattern"id="Signal-instance:remove_pattern"></a><divclass="ref-block"><h4>function <spanclass="name">remove_pattern</span><spanclass="arglist">(p, ...)</span><aclass="top"href="#Signal">^ top</a></h4><h4>function <spanclass="name">instance:remove_pattern</span><spanclass="arglist">(p, ...)</span><aclass="top"href="#Signal">^ top</a></h4><p>Removes functions from all signals matching a <ahref="http://www.lua.org/manual/5.1/manual.html#5.4.1">string pattern</a>. </p><divclass="arguments">Parameters:<dl><dt>string <code>p</code></dt><dd>The signal identifier pattern.</dd><dt>functions <code>...</code></dt><dd>Functions to unbind from the signals.</dd></dl></div><divclass="returns">Returns:<dl><dt>Nothing</dt></dl></div><divclass="example">Example:<pre><codeclass="lua">Signal.remove_pattern('key%-.*', play_click_sound)</code></pre></div></div><aname="Signal-clear_pattern"id="Signal-clear_pattern"></a><aname="Signal-instance:clear_pattern"id="Signal-instance:clear_pattern"></a><divclass="ref-block"><h4>function <spanclass="name">clear_pattern</span><spanclass="arglist">(p)</span><aclass="top"href="#Signal">^ top</a></h4><h4>function <spanclass="name">instance:clear_pattern</span><spanclass="arglist">(p)</span><aclass="top"href="#Signal">^ top</a></h4><p>Removes all functions from all signals matching a <ahref="http://www.lua.org/manual/5.1/manual.html#5.4.1">string pattern</a>. </p><divclass="arguments">Parameters:<dl><dt>string <c
</code></pre></div></div><aname="Camera-camera:rotate"id="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 <codeclass="lua">camera.rot = new_angle</code>.</p><p>This function is shortcut to <codeclass="lua">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">Example:<pre><codeclass="lua">function love.update(dt)
end</code></pre></div></div><aname="Camera-camera:move"id="Camera-camera:move"></a><divclass="ref-block"><h4>function <spanclass="name">camera:move</span><spanclass="arglist">(dx,dy)</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 <codeclass="lua">camera.x,camera.y = new_x,new_y</code>.</p><p>This function is shortcut to <codeclass="lua">camera.x,camera.y = camera.x+dx, camera.y+dy</code>.</p><divclass="arguments">Parameters:<dl><dt>numbers <code>dx,dy</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">Example:<pre><codeclass="lua">function love.update(dt)
end</code></pre></div></div><aname="Camera-camera:attach"id="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 <codeclass="lua">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"id="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"id="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 <codeclass="lua">camera:attach()</code>/<codeclass="lua">camera:detach()</code> pair: <pre><codeclass="lua">cam:attach()
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"id="Camera-camera:worldCoords"></a><aname="Camera-camera:cameraCoords"id="Camera-camera:cameraCoords"></a><divclass="ref-block"><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">(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>numbers <code>x, y</code></dt><dd>Point to transform.</dd></dl></div><divclass="returns">Returns:<dl><dt>numbers</dt><dd>Transformed point.</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">x,y = camera:worldCoords(love.mouse.getPosition())
</code></pre></div></div><aname="Camera-camera:mousepos"id="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 <codeclass="lua">camera:worldCoords(love.mouse.getPosition())</code>.</p><divclass="arguments">Parameters:<dl><dt>None</dt></dl></div><divclass="returns">Returns:<dl><dt>numbers</dt><dd>Mouse position in world coordinates.</dd></dl></div><divclass="example">Example:<pre><codeclass="lua">x,y = camera:mousepos()
</code></pre></div></div></div><aname="Ringbuffer"id="Ringbuffer"></a><divclass="outer-block"><h3>hump.ringbuffer<aclass="top"href="#top">^ top</a></h3><divclass="preamble"><pre><codeclass="lua">Ringbuffer = require "hump.ringbuffer"</code></pre><p>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.</p></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"id="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'
</code></pre></div></div><aname="Ringbuffer-ringbuffer:remove"id="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
</code></pre></div></div><aname="Ringbuffer-ringbuffer:removeAt"id="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
</code></pre></div></div><aname="Ringbuffer-ringbuffer:next"id="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)
</code></pre></div></div><aname="Ringbuffer-ringbuffer:get"id="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)
</code></pre></div></div><aname="Ringbuffer-ringbuffer:size"id="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)
</code></pre></div></div></div><aname="license"id="license"></a><divclass="outer-block"><h3>License<aclass="top"href="#top">^ top</a></h3><divclass="preamble"><p>Yay, <em>free software</em>:</p><blockquote><p>Copyright (c) 2010 Matthias Richter</p><p>Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:</p><p>The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.</p><p>Except as contained in this notice, the name(s) of the above copyright holders shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization.</p><p>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</p></blockquote></div></div><aname="download"id="download"></a><divclass="outer-block"><h3>Download<aclass="top"href="#top">^ top</a></h3><divclass="preamble"><p>You can view and download the individual modules on github: <ahref="http://github.com/vrld/hump">vrld/hump</a>. You may also download the whole packed sourcecode either in <ahref="http://github.com/vrld/hump/zipball/master">zip</a> or <ahref="http://github.com/vrld/hump/tarball/master">tar</a> formats.</p><p>You can clone the project with <ahref="http://git-scm.com">Git</a> by running: <pre>git clone git://github.com/vrld/hump</pre> Once done, you can check for updates by running <pre>git pull</pre></p></div></div></body>
