</div><divclass="outer-block"id="Introduction"><h3>Introduction<aclass="top"href="#top">^top</a></h3><divclass="preamble"><p>Helper Utilities for a Multitude of Problems is a set of lightweight helpers
</div></div><divclass="outer-block"id="Modules"><h3>Modules<aclass="top"href="#top">^top</a></h3><divclass="preamble"><dl><dt><ahref="#hump.gamestate">hump.gamestate</a></dt><dd>A gamestate system.</dd><dt><ahref="#hump.timer">hump.timer</a></dt><dd>Delayed and time-limited function calls.</dd><dt><ahref="#hump.vector">hump.vector</a></dt><dd>2D vector math.</dd><dt><ahref="#hump.vector-light">hump.vector-light</a></dt><dd>Lightweight 2D vector math.</dd><dt><ahref="#hump.class">hump.class</a></dt><dd>Class-based object orientated programming for Lua.</dd><dt><ahref="#hump.signal">hump.signal</a></dt><dd>Simple Signal/Slot (aka. Observer) implementation.</dd><dt><ahref="#hump.camera">hump.camera</a></dt><dd>A camera for LÖVE.</dd><dt><ahref="#hump.ringbuffer">hump.ringbuffer</a></dt><dd>A data structure that wraps around itself.</dd></dl>
</div><divclass="overview"><h4>Module overview</h4><dl><dt><ahref="#hump.gamestateCallbacks ">Callbacks </a></dt><dd>Gamestate Callbacks.</dd><dt><ahref="#hump.gamestatenew">new()</a></dt><dd>Create a new gamestate.</dd><dt><ahref="#hump.gamestateswitch">switch()</a></dt><dd>Switch to gamestate.</dd><dt><ahref="#hump.gamestate<callback>"><callback>()</a></dt><dd>Call function on active gamestate.</dd><dt><ahref="#hump.gamestateregisterEvents">registerEvents()</a></dt><dd>Automatically do all of the above when needed.</dd></dl></div><divclass="section-block"id="hump.gamestateCallbacks "><h4>Callbacks <aclass="top"href="#hump.gamestate">^top</a></h4><p>A gamestate can define all callbacks that LÖVE defines. In addition, there are
callbacks for initalizing, entering and leaving a state:</p>
<dl>
<dt><codeclass="lua">init()</code></dt>
<dd>Called once before entering the state. See <ahref="#hump.gamestateswitch"><codeclass="lua">switch()</code></a>.</dd><dt><codeclass="lua">enter(previous, ...)</code></dt>
<dd>Called when entering the state. See <ahref="#hump.gamestateswitch"><codeclass="lua">switch()</code></a>.</dd><dt><codeclass="lua">leave()</code></dt>
<dd>Called when leaving a state. See <ahref="#hump.gamestateswitch"><codeclass="lua">switch()</code></a>.</dd><dt><codeclass="lua">update()</code></dt>
<dd>Update the game state. Called every frame.</dd><dt><codeclass="lua">draw()</code></dt>
<dd>Draw on the screen. Called every frame.</dd><dt><codeclass="lua">focus()</code></dt>
<dd>Called if the window gets or looses focus.</dd><dt><codeclass="lua">keypressed()</code></dt>
<dd>Triggered when a key is pressed.</dd><dt><codeclass="lua">keyreleased()</code></dt>
<dd>Triggered when a key is released.</dd><dt><codeclass="lua">mousepressed()</code></dt>
<dd>Triggered when a mouse button is pressed.</dd><dt><codeclass="lua">mousereleased()</code></dt>
<dd>Triggered when a mouse button is released.</dd><dt><codeclass="lua">joystickpressed()</code></dt>
<dd>Triggered when a joystick button is pressed.</dd><dt><codeclass="lua">joystickreleased()</code></dt>
<dd>Triggered when a joystick button is released.</dd><dt><codeclass="lua">quit()</code></dt>
<dd>Called on quitting the game. Only called on the active gamestate.</dd></dl>
<p>When using <ahref="#hump.gamestateregisterEvents"><codeclass="lua">registerEvents()</code></a>, all these
callbacks will be called by the corresponding LÖVE callbacks and receive
receive the same arguments (e.g. <codeclass="lua">state:update(dt)</code> will be called by
</div><divclass="ref-block"id="hump.gamestatenew"><h4>function <spanclass="name">new</span><spanclass="arglist">()</span><aclass="top"href="#hump.gamestate">^top</a></h4><p>Declare a new gamestate. A gamestate can define several callbacks.</p>
</div></div><divclass="ref-block"id="hump.gamestateswitch"><h4>function <spanclass="name">switch</span><spanclass="arglist">(to, ...)</span><aclass="top"href="#hump.gamestate">^top</a></h4><p>Switch to a gamestate, with any additional arguments passed to the new state.</p>
</div></div><divclass="ref-block"id="hump.gamestate<callback>"><h4>function <spanclass="name"><callback></span><spanclass="arglist">(...)</span><aclass="top"href="#hump.gamestate">^top</a></h4><p>Calls a function on the current gamestate. Can be any function, but is intended to
be one of the <ahref="#hump.gamestateCallbacks">callbacks</a>. Mostly useful when not using
</div></div><divclass="ref-block"id="hump.gamestateregisterEvents"><h4>function <spanclass="name">registerEvents</span><spanclass="arglist">(callbacks)</span><aclass="top"href="#hump.gamestate">^top</a></h4><p>Overwrite love callbacks to call <codeclass="lua">Gamestate.update()</code>, <codeclass="lua">Gamestate.draw()</code>, etc.
automatically. love callbacks (e.g. <codeclass="lua">love.update()</code>) are still invoked.</p>
<p>This is by done by overwriting the love callbacks, e.g.:</p>
</div><divclass="overview"><h4>Module overview</h4><dl><dt><ahref="#hump.timernew">new()</a></dt><dd>Create new timer instance.</dd><dt><ahref="#hump.timeradd">add()</a></dt><dd>Schedule a function.</dd><dt><ahref="#hump.timeraddPeriodic">addPeriodic()</a></dt><dd>Add a periodic function.</dd><dt><ahref="#hump.timerdo_for">do_for()</a></dt><dd>Run a function for the next few seconds.</dd><dt><ahref="#hump.timercancel">cancel()</a></dt><dd>Cancel a scheduled function.</dd><dt><ahref="#hump.timerclear">clear()</a></dt><dd>Remove all timed and periodic functions.</dd><dt><ahref="#hump.timerupdate">update()</a></dt><dd>Update scheduled functions.</dd></dl></div><divclass="ref-block"id="hump.timernew"><h4>function <spanclass="name">new</span><spanclass="arglist">()</span><aclass="top"href="#hump.timer">^top</a></h4><p><strong>If you don't need multiple independent schedulers, you can use the
global/default timer (see examples).</strong></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 timer instances.</p>
<p><strong>Note:</strong> 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>
</div></div><divclass="ref-block"id="hump.timeradd"><h4>function <spanclass="name">add</span><spanclass="arglist">(delay, func)</span><aclass="top"href="#hump.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><strong>Note:</strong> There is no guarantee that the delay will not be exceeded, it is only
guaranteed that the function will <em>not</em> be executed <em>before</em> the delay has
passed.</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 <codeclass="lua">delay</code></dt>
<dd>Number of seconds the function will be delayed.</dd><dt>function <codeclass="lua">func</code></dt>
<dd>The function to be delayed.</dd></dl>
</div><divclass="returns">Returns:<dl>
<dt>table</dt>
<dd>The timer handle.</dd></dl>
</div><divclass="example">Examples:<pre><codeclass="lua">-- grant the player 5 seconds of immortality
</div></div><divclass="ref-block"id="hump.timeraddPeriodic"><h4>function <spanclass="name">addPeriodic</span><spanclass="arglist">(delay, func)</span><aclass="top"href="#hump.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
<ahref="#hump.timercancel"><codeclass="lua">cancel(handle)</code></a> or <ahref="#hump.timerclear"><codeclass="lua">clear()</code></a> is
called.</p>
<divclass="arguments">Parameters:<dl>
<dt>number <codeclass="lua">delay</code></dt>
<dd>Number of seconds between two consecutive function calls.</dd><dt>function <codeclass="lua">func</code></dt>
<dd>The function to be called periodically.</dd><dt>number <codeclass="lua">count</code> (optional)</dt>
<dd>Number of times the function is to be called.</dd></dl>
</div><divclass="returns">Returns:<dl>
<dt>table</dt>
<dd>The timer handle. See also <ahref="#hump.timercancel"><codeclass="lua">cancel()</code></a>.</dd></dl>
</div><divclass="example">Examples:<pre><codeclass="lua">-- toggle light on and off every second
</div></div><divclass="ref-block"id="hump.timerdo_for"><h4>function <spanclass="name">do_for</span><spanclass="arglist">(delay, func, after)</span><aclass="top"href="#hump.timer">^top</a></h4><p>Run <codeclass="lua">func(dt)</code> for the next <codeclass="lua">delta</code> seconds. The function is called every time
<codeclass="lua">update(dt)</code> is called. Optionally run <codeclass="lua">after()</code> once <codeclass="lua">delta</code> seconds have
passed.</p>
<p><codeclass="lua">after()</code> will receive itself as only parameter.</p>
<p><strong>Note:</strong> You should not add new timers in <codeclass="lua">func(dt)</code>, as this can lead to random
crashes.</p>
<divclass="arguments">Parameters:<dl>
<dt>number <codeclass="lua">delta</code></dt>
<dd>Number of seconds the func will be called.</dd><dt>function <codeclass="lua">func</code></dt>
<dd>The function to be called on <codeclass="lua">update(dt)</code>.</dd><dt>function <codeclass="lua">after</code> (optional)</dt>
<dd>A function to be called after delta seconds.</dd></dl>
</div><divclass="returns">Returns:<dl>
<dt>table</dt>
<dd>The timer handle.</dd></dl>
</div><divclass="example">Examples:<pre><codeclass="lua">-- play an animation for 5 seconds
-- make sure the player is visible after three seconds
player.visible = true
player.isInvincible = false
end)
</code></pre>
</div></div><divclass="ref-block"id="hump.timercancel"><h4>function <spanclass="name">cancel</span><spanclass="arglist">(handle)</span><aclass="top"href="#hump.timer">^top</a></h4><p>Prevent a timer from being executed in the future.</p>
</div></div><divclass="ref-block"id="hump.timerclear"><h4>function <spanclass="name">clear</span><spanclass="arglist">()</span><aclass="top"href="#hump.timer">^top</a></h4><p>Remove all timed and periodic functions. Functions that have not yet been
</div></div><divclass="ref-block"id="hump.timerupdate"><h4>function <spanclass="name">update</span><spanclass="arglist">(dt)</span><aclass="top"href="#hump.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 <codeclass="lua">dt</code></dt>
<dd>Time that has passed since the last <codeclass="lua">update()</code>.</dd></dl>
</div><divclass="overview"><h4>Module overview</h4><dl><dt><ahref="#hump.vectorOperators ">Operators </a></dt><dd>Arithmetics and relations.</dd><dt><ahref="#hump.vectornew">new()</a></dt><dd>Create a new vector.</dd><dt><ahref="#hump.vectorisvector">isvector()</a></dt><dd>Test if value is a vector.</dd><dt><ahref="#hump.vectorvector:clone">vector:clone()</a></dt><dd>Copy a vector.</dd><dt><ahref="#hump.vectorvector:unpack">vector:unpack()</a></dt><dd>Extract coordinates.</dd><dt><ahref="#hump.vectorvector:permul">vector:permul()</a></dt><dd>Per element multiplication.</dd><dt><ahref="#hump.vectorvector:len">vector:len()</a></dt><dd>Get length.</dd><dt><ahref="#hump.vectorvector:len2">vector:len2()</a></dt><dd>Get squared length.</dd><dt><ahref="#hump.vectorvector:dist">vector:dist()</a></dt><dd>Distance to other vector.</dd><dt><ahref="#hump.vectorvector:normalized">vector:normalized()</a></dt><dd>Get normalized vector.</dd><dt><ahref="#hump.vectorvector:normalize_inplace">vector:normalize_inplace()</a></dt><dd>Normalize vector in-place.</dd><dt><ahref="#hump.vectorvector:rotated">vector:rotated()</a></dt><dd>Get rotated vector.</dd><dt><ahref="#hump.vectorvector:rotate_inplace">vector:rotate_inplace()</a></dt><dd>Rotate vector in-place.</dd><dt><ahref="#hump.vectorvector:perpendicular">vector:perpendicular()</a></dt><dd>Get perpendicular vector.</dd><dt><ahref="#hump.vectorvector:projectOn">vector:projectOn()</a></dt><dd>Get projection onto another vector.</dd><dt><ahref="#hump.vectorvector:mirrorOn">vector:mirrorOn()</a></dt><dd>Mirrors vector on other vector</dd><dt><ahref="#hump.vectorvector:cross">vector:cross()</a></dt><dd>Cross product of two vectors.</dd></dl></div><divclass="section-block"id="hump.vectorOperators "><h4>Operators <aclass="top"href="#hump.vector">^top</a></h4><p>Vector arithmetic is implemented by using <codeclass="lua">__add</code>, <codeclass="lua">__mul</code> and other
</div><divclass="ref-block"id="hump.vectornew"><h4>function <spanclass="name">new</span><spanclass="arglist">(x,y)</span><aclass="top"href="#hump.vector">^top</a></h4><p>Create a new vector.</p>
<divclass="arguments">Parameters:<dl>
<dt>numbers <codeclass="lua">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:<p> a = vector.new(10,10)</p>
<p> -- as a shortcut, you can call the module like a function:
vector = require "hump.vector"
a = vector(10,10)</p>
</div></div><divclass="ref-block"id="hump.vectorisvector"><h4>function <spanclass="name">isvector</span><spanclass="arglist">(v)</span><aclass="top"href="#hump.vector">^top</a></h4><p>Test whether a variable is a vector.</p>
<divclass="arguments">Parameters:<dl>
<dt>mixed <codeclass="lua">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
</div></div><divclass="ref-block"id="hump.vectorvector:clone"><h4>function <spanclass="name">vector:clone</span><spanclass="arglist">()</span><aclass="top"href="#hump.vector">^top</a></h4><p>Copy a vector. Simply assigning a vector a vector to a variable will create a
<em>reference</em>, so when modifying the vector referenced by the new variable would
</div></div><divclass="ref-block"id="hump.vectorvector:len"><h4>function <spanclass="name">vector:len</span><spanclass="arglist">()</span><aclass="top"href="#hump.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>
</div><divclass="example">Example:<pre><codeclass="lua">distance = (a - b):len()
</code></pre>
</div></div><divclass="ref-block"id="hump.vectorvector:len2"><h4>function <spanclass="name">vector:len2</span><spanclass="arglist">()</span><aclass="top"href="#hump.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>
</div></div><divclass="ref-block"id="hump.vectorvector:dist"><h4>function <spanclass="name">vector:dist</span><spanclass="arglist">(other)</span><aclass="top"href="#hump.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 <codeclass="lua">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
</div></div><divclass="ref-block"id="hump.vectorvector:normalized"><h4>function <spanclass="name">vector:normalized</span><spanclass="arglist">()</span><aclass="top"href="#hump.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>
</div></div><divclass="ref-block"id="hump.vectorvector:normalize_inplace"><h4>function <spanclass="name">vector:normalize_inplace</span><spanclass="arglist">()</span><aclass="top"href="#hump.vector">^top</a></h4><p>Normalize a vector, i.e. make the vector unit length. Great to use on
intermediate results.</p>
<p><strong>This modifies the vector. If in doubt, use
</div></div><divclass="ref-block"id="hump.vectorvector:rotated"><h4>function <spanclass="name">vector:rotated</span><spanclass="arglist">(angle)</span><aclass="top"href="#hump.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 <codeclass="lua">angle</code></dt>
<dd>Rotation angle in radians.</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
</div></div><divclass="ref-block"id="hump.vectorvector:rotate_inplace"><h4>function <spanclass="name">vector:rotate_inplace</span><spanclass="arglist">(angle)</span><aclass="top"href="#hump.vector">^top</a></h4><p>Rotate a vector in-place. Great to use on intermediate results.</p>
<p><strong>This modifies the vector. If in doubt, use
</div></div><divclass="ref-block"id="hump.vectorvector:perpendicular"><h4>function <spanclass="name">vector:perpendicular</span><spanclass="arglist">()</span><aclass="top"href="#hump.vector">^top</a></h4><p>Quick rotation by 90°. Creates a new vector. The same (but faster) as
</div></div><divclass="ref-block"id="hump.vectorvector:projectOn"><h4>function <spanclass="name">vector:projectOn</span><spanclass="arglist">(v)</span><aclass="top"href="#hump.vector">^top</a></h4><p>Project vector onto another vector (see sketch).</p>
</div></div><divclass="ref-block"id="hump.vectorvector:mirrorOn"><h4>function <spanclass="name">vector:mirrorOn</span><spanclass="arglist">(v)</span><aclass="top"href="#hump.vector">^top</a></h4><p>Mirrors vector on the axis defined by the other vector.</p>
</div></div><divclass="ref-block"id="hump.vectorvector:cross"><h4>function <spanclass="name">vector:cross</span><spanclass="arglist">(other)</span><aclass="top"href="#hump.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 <codeclass="lua">other</code></dt>
<dd>Vector to compute the cross product with.</dd></dl>
</div><divclass="overview"><h4>Module overview</h4><dl><dt><ahref="#hump.vector-lightstr">str()</a></dt><dd>String representation.</dd><dt><ahref="#hump.vector-lightmul">mul()</a></dt><dd>Product of a vector and a scalar.</dd><dt><ahref="#hump.vector-lightdiv">div()</a></dt><dd>Product of a vector and the inverse of a scalar.</dd><dt><ahref="#hump.vector-lightadd">add()</a></dt><dd>Sum of two vectors.</dd><dt><ahref="#hump.vector-lightsub">sub()</a></dt><dd>Difference of two vectors.</dd><dt><ahref="#hump.vector-lightpermul">permul()</a></dt><dd>Per element multiplication.</dd><dt><ahref="#hump.vector-lightdot">dot()</a></dt><dd>Dot product.</dd><dt><ahref="#hump.vector-lightcross">cross()</a></dt><dd>Cross product.</dd><dt><ahref="#hump.vector-lighteq">eq()</a></dt><dd>Equality.</dd><dt><ahref="#hump.vector-lightle">le()</a></dt><dd>Partial lexical order.</dd><dt><ahref="#hump.vector-lightlt">lt()</a></dt><dd>Strict lexical order.</dd><dt><ahref="#hump.vector-lightlen">len()</a></dt><dd>Get length.</dd><dt><ahref="#hump.vector-lightlen2">len2()</a></dt><dd>Get squared length.</dd><dt><ahref="#hump.vector-lightdist">dist()</a></dt><dd>Distance of two points.</dd><dt><ahref="#hump.vector-lightnormalize">normalize()</a></dt><dd>Normalize vector.</dd><dt><ahref="#hump.vector-lightrotate">rotate()</a></dt><dd>Rotate vector.</dd><dt><ahref="#hump.vector-lightperpendicular">perpendicular()</a></dt><dd>Get perpendicular vector.</dd><dt><ahref="#hump.vector-lightproject">project()</a></dt><dd>Project vector onto another vector.</dd><dt><ahref="#hump.vector-lightmirror">mirror()</a></dt><dd>Mirror vector on other vector.</dd></dl></div><divclass="ref-block"id="hump.vector-lightstr"><h4>function <spanclass="name">str</span><spanclass="arglist">(x,y)</span><aclass="top"href="#hump.vector-light">^top</a></h4><p>Transforms a vector to a string of the form <codeclass="lua">(x,y)</code>.</p>
</div></div><divclass="ref-block"id="hump.vector-lightmul"><h4>function <spanclass="name">mul</span><spanclass="arglist">(s, x,y)</span><aclass="top"href="#hump.vector-light">^top</a></h4><p>Computes <codeclass="lua">x*s,y*s</code>. The order of arguments is chosen so that it's possible to
</div></div><divclass="ref-block"id="hump.vector-lightdiv"><h4>function <spanclass="name">div</span><spanclass="arglist">(s, x,y)</span><aclass="top"href="#hump.vector-light">^top</a></h4><p>Computes <codeclass="lua">x/s,y/s</code>. The order of arguments is chosen so that it's possible to
</div></div><divclass="ref-block"id="hump.vector-lightadd"><h4>function <spanclass="name">add</span><spanclass="arglist">(x1,y1, x2,y2)</span><aclass="top"href="#hump.vector-light">^top</a></h4><p>Computes the sum (<codeclass="lua">x1+x2,y1+y2</code>) of two vectors. Meant to be used in
</div></div><divclass="ref-block"id="hump.vector-lightsub"><h4>function <spanclass="name">sub</span><spanclass="arglist">(x1,y1, x2,y2)</span><aclass="top"href="#hump.vector-light">^top</a></h4><p>Computes the difference (<codeclass="lua">x1-x2,y1-y2</code>) of two vectors. Meant to be used in
</div></div><divclass="ref-block"id="hump.vector-lightdot"><h4>function <spanclass="name">dot</span><spanclass="arglist">(x1,y1, x2,y2)</span><aclass="top"href="#hump.vector-light">^top</a></h4><p>Computes the <ahref="http://en.wikipedia.org/wiki/Dot_product">dot product</a> of two
</div></div><divclass="ref-block"id="hump.vector-lightcross"><h4>function <spanclass="name">cross</span><spanclass="arglist">(x1,y1, x2,y2)</span><aclass="top"href="#hump.vector-light">^top</a></h4><p>Computes the <ahref="http://en.wikipedia.org/wiki/Cross_product">cross product</a> of two
</div></div><divclass="ref-block"id="hump.vector-lighteq"><h4>function <spanclass="name">eq</span><spanclass="arglist">(x1,y1, x2,y2)</span><aclass="top"href="#hump.vector-light">^top</a></h4><p>Test for equality.</p>
<dd><codeclass="lua">x1 < x2 or (x1 == x2) and y1 <= y2</code></dd></dl>
</div><divclass="example">Example:<pre><codeclass="lua">if vector.lt(x1,y1, x2,y2) then be.happy() end
</code></pre>
</div></div><divclass="ref-block"id="hump.vector-lightlen"><h4>function <spanclass="name">len</span><spanclass="arglist">(x,y)</span><aclass="top"href="#hump.vector-light">^top</a></h4><p>Get length of a vector, i.e. <codeclass="lua">math.sqrt(x*x + y*y)</code>.</p>
</div></div><divclass="ref-block"id="hump.vector-lightlen2"><h4>function <spanclass="name">len2</span><spanclass="arglist">(x,y)</span><aclass="top"href="#hump.vector-light">^top</a></h4><p>Get squared length of a vector, i.e. <codeclass="lua">x*x + y*y</code>.</p>
<divclass="arguments">Parameters:<dl>
<dt>numbers <codeclass="lua">x,y</code></dt>
<dd>The vector.</dd></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
</div></div><divclass="ref-block"id="hump.vector-lightdist"><h4>function <spanclass="name">dist</span><spanclass="arglist">(x1,y1, x2,y2)</span><aclass="top"href="#hump.vector-light">^top</a></h4><p>Get distance of two points. The same as <codeclass="lua">vector.len(x1-x2, y1-y2)</code>.</p>
</div></div><divclass="ref-block"id="hump.vector-lightnormalize"><h4>function <spanclass="name">normalize</span><spanclass="arglist">(x,y)</span><aclass="top"href="#hump.vector-light">^top</a></h4><pre><codeclass="lua">Get normalized vector, i.e. a vector with the same direction as the input
vector, but with length 1.
</code></pre>
<divclass="arguments">Parameters:<dl>
<dt>numbers <codeclass="lua">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></div><divclass="ref-block"id="hump.vector-lightperpendicular"><h4>function <spanclass="name">perpendicular</span><spanclass="arglist">(x,y)</span><aclass="top"href="#hump.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 <codeclass="lua">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></div><divclass="ref-block"id="hump.vector-lightmirror"><h4>function <spanclass="name">mirror</span><spanclass="arglist">(x,y, u,v)</span><aclass="top"href="#hump.vector-light">^top</a></h4><p>Mirrors vector on the axis defined by the other vector.</p>
<divclass="arguments">Parameters:<dl>
<dt>numbers <codeclass="lua">x,y</code></dt>
<dd>The vector to mirror.</dd><dt>numbers <codeclass="lua">u,v</code></dt>
</div><divclass="overview"><h4>Module overview</h4><dl><dt><ahref="#hump.classnew">new()</a></dt><dd>Declare a new class.</dd><dt><ahref="#hump.classclass.construct">class.construct()</a></dt><dd>Call class constructor.</dd><dt><ahref="#hump.classclass:inherit">class:inherit()</a></dt><dd>Explicit class inheritance/mixin support.</dd><dt><ahref="#hump.classobject:is_a">object:is_a()</a></dt><dd>Test object's type.</dd><dt><ahref="#hump.classCaveats ">Caveats </a></dt><dd>Common gotchas.</dd></dl></div><divclass="ref-block"id="hump.classnew"><h4>function <spanclass="name">new</span><spanclass="arglist">{constructor, name = the_name, inherits = super}</span><aclass="top"href="#hump.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
</div></div><divclass="ref-block"id="hump.classclass.construct"><h4>function <spanclass="name">class.construct</span><spanclass="arglist">(object, ...)</span><aclass="top"href="#hump.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 <codeclass="lua">object</code></dt>
<dd>The object. Usually <codeclass="lua">self</code>.</dd><dt>mixed <codeclass="lua">...</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></div><divclass="ref-block"id="hump.classclass:inherit"><h4>function <spanclass="name">class:inherit</span><spanclass="arglist">(...)</span><aclass="top"href="#hump.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><strong>Be careful with changing table values in a subclass: This will change the
value in the parent class too.</strong></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><strong>Note:</strong><codeclass="lua">class:inherit()</code> doesn't actually care if the arguments supplied are
</div></div><divclass="ref-block"id="hump.classobject:is_a"><h4>function <spanclass="name">object:is_a</span><spanclass="arglist">(cls)</span><aclass="top"href="#hump.class">^top</a></h4><p>Tests whether an object is an instance of a class.</p>
<divclass="arguments">Parameters:<dl>
<dt>class <codeclass="lua">cls</code></dt>
<dd>Class to test. <strong>Note:</strong> this is the class itself, not 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></div><divclass="section-block"id="hump.classCaveats "><h4>Caveats <aclass="top"href="#hump.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:</p>
</div><divclass="overview"><h4>Module overview</h4><dl><dt><ahref="#hump.signalnew">new()</a></dt><dd>Create a new signal registry</dd><dt><ahref="#hump.signalregister">register()</a></dt><dd>Register function with signal.</dd><dt><ahref="#hump.signalemit">emit()</a></dt><dd>Call all functions bound to a signal.</dd><dt><ahref="#hump.signalremove">remove()</a></dt><dd>Remove functions from registry. </dd><dt><ahref="#hump.signalclear">clear()</a></dt><dd>Clears a signal registry.</dd><dt><ahref="#hump.signalemit_pattern">emit_pattern()</a></dt><dd>Emits signals matching a pattern.</dd><dt><ahref="#hump.signalremove_pattern">remove_pattern()</a></dt><dd>Remove functions from signals matching a pattern.</dd><dt><ahref="#hump.signalclear_pattern">clear_pattern()</a></dt><dd>Clears signal registry matching a pattern.</dd></dl></div><divclass="ref-block"id="hump.signalnew"><h4>function <spanclass="name">new</span><spanclass="arglist">()</span><aclass="top"href="#hump.signal">^top</a></h4><p><strong>If you don't need multiple independent registries, you can use the
global/default registry (see examples).</strong></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><strong>Note:</strong> Independent registries use the colon-notation (e.g.
<codeclass="lua">instance:emit("foo")</code>), while the global registry uses the dot-notation (e.g.
</div></div><divclass="ref-block"id="hump.signalregister"><h4>function <spanclass="name">register</span><spanclass="arglist">(s, f)</span><aclass="top"href="#hump.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 <codeclass="lua">s</code></dt>
<dd>The signal identifier.</dd><dt>function <codeclass="lua">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 <ahref="#hump.signalremove"><codeclass="lua">remove()</code></a>.</dd></dl>
</div></div><divclass="ref-block"id="hump.signalemit"><h4>function <spanclass="name">emit</span><spanclass="arglist">(s, ...)</span><aclass="top"href="#hump.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 <codeclass="lua">s</code></dt>
<dd>The signal identifier.</dd><dt>mixed <codeclass="lua">...</code> (optional)</dt>
<dd>Arguments to pass to the bound functions.</dd></dl>
</div></div><divclass="ref-block"id="hump.signalremove"><h4>function <spanclass="name">remove</span><spanclass="arglist">(s, ...)</span><aclass="top"href="#hump.signal">^top</a></h4><p>Unbinds (removes) functions from signal <codeclass="lua">s</code>.</p>
<divclass="arguments">Parameters:<dl>
<dt>string <codeclass="lua">s</code></dt>
<dd>The signal identifier.</dd><dt>functions <codeclass="lua">...</code></dt>
<dd>Functions to unbind from the signal.</dd></dl>
</div></div><divclass="ref-block"id="hump.signalclear"><h4>function <spanclass="name">clear</span><spanclass="arglist">(s)</span><aclass="top"href="#hump.signal">^top</a></h4><p>Removes all functions from signal <codeclass="lua">s</code>.</p>
</div></div><divclass="ref-block"id="hump.signalemit_pattern"><h4>function <spanclass="name">emit_pattern</span><spanclass="arglist">(p, ...)</span><aclass="top"href="#hump.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 <codeclass="lua">p</code></dt>
<dd>The signal identifier pattern.</dd><dt>mixed <codeclass="lua">...</code> (optional)</dt>
<dd>Arguments to pass to the bound functions.</dd></dl>
</div></div><divclass="ref-block"id="hump.signalremove_pattern"><h4>function <spanclass="name">remove_pattern</span><spanclass="arglist">(p, ...)</span><aclass="top"href="#hump.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 <codeclass="lua">p</code></dt>
<dd>The signal identifier pattern.</dd><dt>functions <codeclass="lua">...</code></dt>
<dd>Functions to unbind from the signals.</dd></dl>
</div></div><divclass="ref-block"id="hump.signalclear_pattern"><h4>function <spanclass="name">clear_pattern</span><spanclass="arglist">(p)</span><aclass="top"href="#hump.signal">^top</a></h4><p>Removes <em>all</em> functions from all signals matching a <ahref="http://www.lua.org/manual/5.1/manual.html#5.4.1">string pattern</a>.</p>
</div><divclass="overview"><h4>Module overview</h4><dl><dt><ahref="#hump.cameranew">new()</a></dt><dd>Create a new camera.</dd><dt><ahref="#hump.cameracamera:move">camera:move()</a></dt><dd>Move camera.</dd><dt><ahref="#hump.cameracamera:lookAt">camera:lookAt()</a></dt><dd>Move camera to position.</dd><dt><ahref="#hump.cameracamera:pos">camera:pos()</a></dt><dd>Get camera position.</dd><dt><ahref="#hump.cameracamera:rotate">camera:rotate()</a></dt><dd>Rotate camera.</dd><dt><ahref="#hump.cameracamera:rotateTo">camera:rotateTo()</a></dt><dd>Set camera rotation.</dd><dt><ahref="#hump.cameracamera:zoom">camera:zoom()</a></dt><dd>Change zoom.</dd><dt><ahref="#hump.cameracamera:zoomTo">camera:zoomTo()</a></dt><dd>Set zoom.</dd><dt><ahref="#hump.cameracamera:attach">camera:attach()</a></dt><dd>Attach camera.</dd><dt><ahref="#hump.cameracamera:detach">camera:detach()</a></dt><dd>Detach camera.</dd><dt><ahref="#hump.cameracamera:draw">camera:draw()</a></dt><dd>Attach, draw, then detach.</dd><dt><ahref="#hump.cameracamera:worldCoords">camera:worldCoords()</a></dt><dd>Convert point to world coordinates.</dd><dt><ahref="#hump.cameracamera:cameraCoords">camera:cameraCoords()</a></dt><dd>Convert point to camera coordinates.</dd><dt><ahref="#hump.cameracamera:mousepos">camera:mousepos()</a></dt><dd>Get mouse position in world coordinates.</dd></dl></div><divclass="ref-block"id="hump.cameranew"><h4>function <spanclass="name">new</span><spanclass="arglist">(x,y, zoom, rot)</span><aclass="top"href="#hump.camera">^top</a></h4><p>Creates a new camera. You can access the camera position using <codeclass="lua">camera.x,
camera.y</code>, the zoom using <codeclass="lua">camera.scale</code> and the rotation using <codeclass="lua">camera.rot</code>.</p>
</div></div><divclass="ref-block"id="hump.cameracamera:move"><h4>function <spanclass="name">camera:move</span><spanclass="arglist">(dx,dy)</span><aclass="top"href="#hump.camera">^top</a></h4><p>Move the camera <em>by</em> some vector. To set the position, use
</div></div><divclass="ref-block"id="hump.cameracamera:lookAt"><h4>function <spanclass="name">camera:lookAt</span><spanclass="arglist">(x,y)</span><aclass="top"href="#hump.camera">^top</a></h4><p>Let the camera look at a point. In other words, it sets the camera position. To
move the camera <em>by</em> some amount, use <ahref="#hump.cameramove"><codeclass="lua">camera:move(x,y)</code></a>.</p>
<p>This function is shortcut to <codeclass="lua">camera.x,camera.y = x, y</code>.</p>
</div></div><divclass="ref-block"id="hump.cameracamera:rotate"><h4>function <spanclass="name">camera:rotate</span><spanclass="arglist">(angle)</span><aclass="top"href="#hump.camera">^top</a></h4><p>Rotate the camera by some angle. To set 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>
</div></div><divclass="ref-block"id="hump.cameracamera:attach"><h4>function <spanclass="name">camera:attach</span><spanclass="arglist">()</span><aclass="top"href="#hump.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>
</div></div><divclass="ref-block"id="hump.cameracamera:detach"><h4>function <spanclass="name">camera:detach</span><spanclass="arglist">()</span><aclass="top"href="#hump.camera">^top</a></h4><p>Stop looking through the camera.</p>
</div></div><divclass="ref-block"id="hump.cameracamera:draw"><h4>function <spanclass="name">camera:draw</span><spanclass="arglist">(func)</span><aclass="top"href="#hump.camera">^top</a></h4><p>Wrap a function between a <codeclass="lua">camera:attach()/camera:detach()</code> pair:</p>
</div></div><divclass="ref-block"id="hump.cameracamera:worldCoords"><h4>function <spanclass="name">camera:worldCoords</span><spanclass="arglist">(x, y)</span><aclass="top"href="#hump.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><codeclass="lua">camera:worldCoords(x,y)</code> and <codeclass="lua">camera:cameraCoords(x,y)</code> transform a point
</div></div><divclass="ref-block"id="hump.cameracamera:cameraCoords"><h4>function <spanclass="name">camera:cameraCoords</span><spanclass="arglist">(x, y)</span><aclass="top"href="#hump.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><codeclass="lua">camera:worldCoords(x,y)</code> and <codeclass="lua">camera:cameraCoords(x,y)</code> transform a point
</div></div><divclass="ref-block"id="hump.cameracamera:mousepos"><h4>function <spanclass="name">camera:mousepos</span><spanclass="arglist">()</span><aclass="top"href="#hump.camera">^top</a></h4><p>Shortcut to <codeclass="lua">camera:worldCoords(love.mouse.getPosition())</code>.</p>
<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 <ahref="http://www.youtube.com/watch?v=YTdsKq77_lg">Tomb Raider style
inventories</a>, 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="#hump.ringbuffernew">new()</a></dt><dd>Create a new ringbuffer.</dd><dt><ahref="#hump.ringbufferringbuffer:insert">ringbuffer:insert()</a></dt><dd>Inser elements.</dd><dt><ahref="#hump.ringbufferringbuffer:remove">ringbuffer:remove()</a></dt><dd>Remove currently selected item.</dd><dt><ahref="#hump.ringbufferringbuffer:removeAt">ringbuffer:removeAt()</a></dt><dd>Remove an item.</dd><dt><ahref="#hump.ringbufferringbuffer:next">ringbuffer:next()</a></dt><dd>Select next item.</dd><dt><ahref="#hump.ringbufferringbuffer:prev">ringbuffer:prev()</a></dt><dd>Select previous item.</dd><dt><ahref="#hump.ringbufferringbuffer:get">ringbuffer:get()</a></dt><dd>Get currently selected item.</dd><dt><ahref="#hump.ringbufferringbuffer:size">ringbuffer:size()</a></dt><dd>Get ringbuffer size.</dd></dl></div><divclass="ref-block"id="hump.ringbuffernew"><h4>function <spanclass="name">new</span><spanclass="arglist">(...)</span><aclass="top"href="#hump.ringbuffer">^top</a></h4><p>Create new ring-buffer.</p>
</div></div><divclass="ref-block"id="hump.ringbufferringbuffer:remove"><h4>function <spanclass="name">ringbuffer:remove</span><spanclass="arglist">()</span><aclass="top"href="#hump.ringbuffer">^top</a></h4><p>Remove current item, return it and select next element.</p>
</div></div><divclass="ref-block"id="hump.ringbufferringbuffer:removeAt"><h4>function <spanclass="name">ringbuffer:removeAt</span><spanclass="arglist">(pos)</span><aclass="top"href="#hump.ringbuffer">^top</a></h4><p>Remove the item at a position relative to the current element.</p>
</div></div><divclass="ref-block"id="hump.ringbufferringbuffer:next"><h4>function <spanclass="name">ringbuffer:next</span><spanclass="arglist">()</span><aclass="top"href="#hump.ringbuffer">^top</a></h4><p>Select and return the next element.</p>
</div></div><divclass="ref-block"id="hump.ringbufferringbuffer:prev"><h4>function <spanclass="name">ringbuffer:prev</span><spanclass="arglist">()</span><aclass="top"href="#hump.ringbuffer">^top</a></h4><p>Select and return the previous item.</p>
</div></div><divclass="ref-block"id="hump.ringbufferringbuffer:get"><h4>function <spanclass="name">ringbuffer:get</span><spanclass="arglist">()</span><aclass="top"href="#hump.ringbuffer">^top</a></h4><p>Return the current element.</p>
</div></div><divclass="ref-block"id="hump.ringbufferringbuffer:size"><h4>function <spanclass="name">ringbuffer:size</span><spanclass="arglist">()</span><aclass="top"href="#hump.ringbuffer">^top</a></h4><p>Get number of items in the buffer</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><divclass="outer-block"id="Download"><h3>Download<aclass="top"href="#top">^top</a></h3><divclass="preamble"><p>You can view and download the individual modules on github: <ahref="%22http://github.com/vrld/hump%22">vrld/hump</a>
You may also download the whole packed sourcecode either in
<ahref="http://github.com/vrld/hump/zipball/master">zip</a> or
