library-mirrors/hump
1
0
Fork 0
mirror of https://github.com/vrld/hump.git synced 2024-11-23 12:24:19 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity
e5c9bfbac7
hump/index.html
Matthias Richter e5c9bfbac7 Fix broken links
2013-08-23 17:34:08 +02:00

1889 lines
103 KiB
HTML
Raw Blame History

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<title>hump - L&Ouml;VE Helper Utilities for More Productivity</title>
<link rel="stylesheet" type="text/css" href="style.css" />
<link rel="stylesheet" type="text/css" href="highlight.css" />
<script type="text/javascript" src="highlight.pack.js"></script>
<script type="text/javascript">
window.onload = function() {
var examples = document.getElementsByTagName("code");
for (i = 0; i < examples.length; ++i) {
if (examples[i].className == "lua")
hljs.highlightBlock(examples[i], " ");
}
};
</script>
</head>
<body><a name="top"></a>
<div id="header">
<h1><a href="http://github.com/vrld/hump">hump</a>
<span class="small"> Helper Utilities for More Productivity</span></h1>
<ul id="main-nav">
<li><a href="#Introduction">Introduction</a></li>
<li><a href="#Modules">Modules</a></li>
<li><a href="#License">License</a></li>
<li><a href="#Download">Download</a></li>
</ul>
<h2>&nbsp;</h2>
</div><div class="outer-block" id="Introduction"><h3>Introduction<a class="top" href="#top">^top</a></h3><div class="preamble"><p>Helper Utilities for a Multitude of Problems is a set of lightweight helpers
for the awesome LÖVE Engine.</p>
<p>hump differs from other libraries in that every component is independent of the
remaining ones. hump's footprint is very small and thus should fit nicely into
your projects.</p>
</div></div><div class="outer-block" id="Modules"><h3>Modules<a class="top" href="#top">^top</a></h3><div class="preamble"><dl><dt><a href="#hump.gamestate">hump.gamestate</a></dt><dd>A gamestate system.</dd><dt><a href="#hump.timer">hump.timer</a></dt><dd>Delayed and time-limited function calls, and tweening support.</dd><dt><a href="#hump.vector">hump.vector</a></dt><dd>2D vector math.</dd><dt><a href="#hump.vector-light">hump.vector-light</a></dt><dd>Lightweight 2D vector math.</dd><dt><a href="#hump.class">hump.class</a></dt><dd>Object oriented programming for Lua.</dd><dt><a href="#hump.signal">hump.signal</a></dt><dd>Simple Signal/Slot (aka. Observer) implementation.</dd><dt><a href="#hump.camera">hump.camera</a></dt><dd>A camera for LÖVE.</dd></dl>
</div></div><div class="outer-block" id="hump.gamestate"><h3>hump.gamestate<a class="top" href="#top">^top</a></h3><div class="preamble"><pre><code class="lua">Gamestate = require "hump.gamestate"
</code></pre>
<p>A gamestate encapsulates independent data an behaviour in a single table.</p>
<p>A typical game could consist of a menu-state, a level-state and a game-over-state.</p>
<h4>Example:</h4>
<pre><code class="lua">local menu = {} -- previously: Gamestate.new()
local game = {}
function menu:draw()
love.graphics.print("Press Enter to continue", 10, 10)
end
function menu:keyreleased(key, code)
if key == 'enter' then
Gamestate.switch(game)
end
end
function game:enter()
Entities.clear()
-- setup entities here
end
function game:update(dt)
Entities.update(dt)
end
function game:draw()
Entities.draw()
end
function love.load()
Gamestate.registerEvents()
Gamestate.switch(menu)
end
</code></pre>
</div><div class="overview"><h4>Module overview</h4><dl><dt><a href="#hump.gamestateCallbacks">Callbacks </a></dt><dd>Gamestate Callbacks.</dd><dt><a href="#hump.gamestatenew">new()</a></dt><dd>Create a new gamestate.</dd><dt><a href="#hump.gamestateswitch">switch()</a></dt><dd>Switch to gamestate.</dd><dt><a href="#hump.gamestatecurrent">current()</a></dt><dd>Get current gamestate.</dd><dt><a href="#hump.gamestatepush">push()</a></dt><dd>Push state on top of the stack.</dd><dt><a href="#hump.gamestatepop">pop()</a></dt><dd>Pops state from the stack.</dd><dt><a href="#hump.gamestate&lt;callback&gt;">&lt;callback&gt;()</a></dt><dd>Call function on active gamestate.</dd><dt><a href="#hump.gamestateregisterEvents">registerEvents()</a></dt><dd>Automatically do all of the above when needed.</dd></dl></div><div class="section-block" id="hump.gamestateCallbacks"><h4>Callbacks <a class="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><code class="lua">init()</code></dt>
<dd>Called once before entering the state. See <a href="#hump.gamestateswitch"><code class="lua">switch()</code></a>.</dd><dt><code class="lua">enter(previous, ...)</code></dt>
<dd>Called when entering the state. See <a href="#hump.gamestateswitch"><code class="lua">switch()</code></a>.</dd><dt><code class="lua">leave()</code></dt>
<dd>Called when leaving a state. See <a href="#hump.gamestateswitch"><code class="lua">switch()</code></a>.</dd><dt><code class="lua">update()</code></dt>
<dd>Update the game state. Called every frame.</dd><dt><code class="lua">draw()</code></dt>
<dd>Draw on the screen. Called every frame.</dd><dt><code class="lua">focus()</code></dt>
<dd>Called if the window gets or looses focus.</dd><dt><code class="lua">keypressed()</code></dt>
<dd>Triggered when a key is pressed.</dd><dt><code class="lua">keyreleased()</code></dt>
<dd>Triggered when a key is released.</dd><dt><code class="lua">mousepressed()</code></dt>
<dd>Triggered when a mouse button is pressed.</dd><dt><code class="lua">mousereleased()</code></dt>
<dd>Triggered when a mouse button is released.</dd><dt><code class="lua">joystickpressed()</code></dt>
<dd>Triggered when a joystick button is pressed.</dd><dt><code class="lua">joystickreleased()</code></dt>
<dd>Triggered when a joystick button is released.</dd><dt><code class="lua">quit()</code></dt>
<dd>Called on quitting the game. Only called on the active gamestate.</dd></dl>
<p>When using <a href="#hump.gamestateregisterEvents"><code class="lua">registerEvents()</code></a>, all these
callbacks will be called by the corresponding LÖVE callbacks and receive
receive the same arguments (e.g. <code class="lua">state:update(dt)</code> will be called by
<code class="lua">love.update(dt)</code>).</p>
<h4>Example:</h4>
<pre><code class="lua">menu = {} -- previously: Gamestate.new()
function menu:init() -- run only once
self.background = love.graphics.newImage('bg.jpg')
Buttons.initialize()
end
function menu:enter(previous) -- run every time the state is entered
Buttons.setActive(Buttons.start)
end
function menu:update(dt)
Buttons.update(dt)
end
function menu:draw()
love.graphics.draw(self.background, 0, 0)
Buttons.draw()
end
function menu:keyreleased(key)
if key == 'up' then
Buttons.selectPrevious()
elseif key == 'down' then
Buttons.selectNext()
elseif
Buttons.active:onClick()
end
end
function menu:mousereleased(x,y, mouse_btn)
local button = Buttons.hovered(x,y)
if button then
Button.select(button)
if mouse_btn == 'l' then
button:onClick()
end
end
end
</code></pre>
</div><div class="ref-block" id="hump.gamestatenew"><h4>function <span class="name">new</span><span class="arglist">()</span><a class="top" href="#hump.gamestate">^top</a></h4><p><strong>Deprecated: Use the table constructor instead (see example)</strong></p>
<p>Declare a new gamestate (just an empty table). A gamestate can define several
callbacks.</p>
<div class="arguments">Parameters:<dl><dt>None</dt></dl></div><div class="returns">Returns:<dl>
<dt>Gamestate</dt>
<dd>An empty table.</dd></dl>
</div><div class="example">Example:<pre><code class="lua">menu = {}
-- deprecated method:
menu = Gamestate.new()
</code></pre>
</div></div><div class="ref-block" id="hump.gamestateswitch"><h4>function <span class="name">switch</span><span class="arglist">(to, ...)</span><a class="top" href="#hump.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 <code class="lua">leave()</code> callback on the current
gamestate, replace the current gamestate with <code class="lua">to</code>, call the <code class="lua">init()</code> function
if the state was not yet inialized and finally call <code class="lua">enter(old_state, ...)</code> on
the new gamestate.</p>
<div class="arguments">Parameters:<dl>
<dt>Gamestate <code class="lua">to</code></dt>
<dd>Target gamestate.</dd><dt>mixed <code class="lua">...</code></dt>
<dd>Additional arguments to pass to <code class="lua">to:enter(current, ...)</code>.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>mixed</dt>
<dd>The results of <code class="lua">to:enter(current, ...)</code></dd></dl>
</div><div class="example">Example:<pre><code class="lua">Gamestate.switch(game, level_two)
</code></pre>
</div></div><div class="ref-block" id="hump.gamestatecurrent"><h4>function <span class="name">current</span><span class="arglist">()</span><a class="top" href="#hump.gamestate">^top</a></h4><p>Returns the currently activated gamestate.</p>
<div class="arguments">Parameters:<dl><dt>None</dt></dl></div><div class="returns">Returns:<dl>
<dt>table</dt>
<dd>The active gamestate.</dd></dl>
</div><div class="example">Example:<pre><code class="lua">function love.keypressed(key)
if Gamestate.current() ~= menu and key == 'p' then
Gamestate.push(pause)
end
end
</code></pre>
</div></div><div class="ref-block" id="hump.gamestatepush"><h4>function <span class="name">push</span><span class="arglist">(to, ...)</span><a class="top" href="#hump.gamestate">^top</a></h4><p>Pushes the <code class="lua">to</code> on top of the state stack, i.e. makes it the active state.
Semantics are the same as <code class="lua">switch(to, ...)</code>, except that <code class="lua">leave()</code> is <em>not</em>
called on the previously active state.</p>
<p>Useful for pause screens, menus, etc.</p>
<div class="arguments">Parameters:<dl>
<dt>Gamestate <code class="lua">to</code></dt>
<dd>Target gamestate.</dd><dt>mixed <code class="lua">...</code></dt>
<dd>Additional arguments to pass to <code class="lua">to:enter(current, ...)</code>.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>mixed</dt>
<dd>The results of <code class="lua">to:enter(current, ...)</code></dd></dl>
</div><div class="example">Example:<pre><code class="lua">-- pause gamestate
Pause = Gamestate.new()
function Pause:enter(from)
self.from = from -- record previous state
end
function Pause:draw()
local W, H = love.graphics.getWidth(), love.graphics.getHeight()
-- draw previous screen
self.from:draw()
-- overlay with pause message
love.graphics.setColor(0,0,0, 100)
love.graphics.rectangle('fill', 0,0, W,H)
love.graphics.setColor(255,255,255)
love.graphics.printf('PAUSE', 0, H/2, W, 'center')
end
-- [...]
function love.keypressed(key)
if Gamestate.current() ~= menu and key == 'p' then
Gamestate.push(pause)
end
end
</code></pre>
</div></div><div class="ref-block" id="hump.gamestatepop"><h4>function <span class="name">pop</span><span class="arglist">()</span><a class="top" href="#hump.gamestate">^top</a></h4><p>Calls <code class="lua">leave()</code> on the current state and then removes it from the stack, making
the state below the current state. Does <em>not</em> call <code class="lua">enter()</code> on the activated
state.</p>
<div class="arguments">Parameters:<dl><dt>None</dt></dl></div><div class="returns">Returns:<dl>
<dt>mixed</dt>
<dd>The results of <code class="lua">state:leave()</code></dd></dl>
</div><div class="example">Example:<pre><code class="lua">-- extending the example of Gamestate.push() above
function Pause:keypressed(key)
if key == 'p' then
Gamestate.pop() -- return to previous state
end
end
</code></pre>
</div></div><div class="ref-block" id="hump.gamestate&lt;callback&gt;"><h4>function <span class="name">&lt;callback&gt;</span><span class="arglist">(...)</span><a class="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 <a href="#hump.gamestateCallbacks">callbacks</a>. Mostly useful when not using
<a href="#hump.gamestateregisterEvents"><code class="lua">registerEvents()</code></a>.</p>
<div class="arguments">Parameters:<dl>
<dt>mixed <code class="lua">...</code></dt>
<dd>Arguments to pass to the corresponding function.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>mixed</dt>
<dd>The result of the callback function.</dd></dl>
</div><div class="example">Example:<pre><code class="lua">function love.draw()
Gamestate.draw() -- &lt;callback&gt; is `draw'
end
function love.update(dt)
Gamestate.update(dt) -- pass dt to currentState:update(dt)
end
function love.keypressed(key, code)
Gamestate.keypressed(key, code) -- pass multiple arguments
end
</code></pre>
</div></div><div class="ref-block" id="hump.gamestateregisterEvents"><h4>function <span class="name">registerEvents</span><span class="arglist">(callbacks)</span><a class="top" href="#hump.gamestate">^top</a></h4><p>Overwrite love callbacks to call <code class="lua">Gamestate.update()</code>, <code class="lua">Gamestate.draw()</code>, etc.
automatically. love callbacks (e.g. <code class="lua">love.update()</code>) are still invoked.</p>
<p>This is by done by overwriting the love callbacks, e.g.:</p>
<pre><code class="lua">local old_update = love.update
function love.update(dt)
old_update(dt)
return Gamestate.current:update(dt)
end
</code></pre>
<p><strong>Note:</strong> Only works when called in love.load() or any other function that is
executed <em>after</em> the whole file is loaded.</p>
<div class="arguments">Parameters:<dl>
<dt>table <code class="lua">callbacks</code> (optional)</dt>
<dd>Names of the callbacks to register. If omitted, register all love callbacks.</dd></dl>
</div><div class="returns">Returns:<dl><dt>Nothing</dt></dl></div><div class="example">Examples:<pre><code class="lua">function love.load()
Gamestate.registerEvents()
Gamestate.switch(menu)
end
-- love callback will still be invoked
function love.update(dt)
Timer.update(dt)
-- no need for Gamestate.update(dt)
end
</code></pre>
<pre><code class="lua">function love.load()
-- only register draw, update and quit
Gamestate.registerEvents{'draw', 'update', 'quit'}
Gamestate.switch(menu)
end
</code></pre>
</div></div></div><div class="outer-block" id="hump.timer"><h3>hump.timer<a class="top" href="#top">^top</a></h3><div class="preamble"><pre><code class="lua">Timer = require "hump.timer"
</code></pre>
<p>hump.timer offers a simple interface to schedule the execution of functions. It
is possible to run functions <em>after</em> and <em>for</em> some amount of time. For
example, a timer could be set to move critters every 5 seconds or to make the
player invincible for a short amount of time.</p>
<p>In addition to that, <code class="lua">hump.timer</code> offers various
<a href="http://en.wikipedia.org/wiki/Inbetweening">tweening</a> functions that make it
easier to produce <a href="http://www.youtube.com/watch?v=Fy0aCDmgnxg">juicy games</a>.</p>
<h4>Example:</h4>
<pre><code class="lua">function love.keypressed(key)
if key == ' ' then
Timer.add(1, function() print("Hello, world!") end)
end
end
function love.update(dt)
Timer.update(dt)
end
</code></pre>
</div><div class="overview"><h4>Module overview</h4><dl><dt><a href="#hump.timernew">new()</a></dt><dd>Create new timer instance.</dd><dt><a href="#hump.timeradd">add()</a></dt><dd>Schedule a function.</dd><dt><a href="#hump.timeraddPeriodic">addPeriodic()</a></dt><dd>Add a periodic function.</dd><dt><a href="#hump.timerdo_for">do_for()</a></dt><dd>Run a function for the next few seconds.</dd><dt><a href="#hump.timercancel">cancel()</a></dt><dd>Cancel a scheduled function.</dd><dt><a href="#hump.timerclear">clear()</a></dt><dd>Remove all timed and periodic functions.</dd><dt><a href="#hump.timerupdate">update()</a></dt><dd>Update scheduled functions.</dd><dt><a href="#hump.timertween">tween()</a></dt><dd>Add a tween.</dd><dt><a href="#hump.timerTweening_methods">Tweening methods </a></dt><dd>Predefined tweening methods.</dd><dt><a href="#hump.timerCustom_interpolators">Custom interpolators </a></dt><dd>Advanced: Adding custom tweening methods.</dd></dl></div><div class="ref-block" id="hump.timernew"><h4>function <span class="name">new</span><span class="arglist">()</span><a class="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. <code class="lua">instance:update(dt)</code>),
while the global timer uses the dot-notation (e.g. <code class="lua">Timer.update(dt)</code>).</p>
<div class="arguments">Parameters:<dl><dt>None</dt></dl></div><div class="returns">Returns:<dl>
<dt>Timer</dt>
<dd>A timer instance.</dd></dl>
</div><div class="example">Example:<pre><code class="lua">menuTimer = Timer.new()
</code></pre>
</div></div><div class="ref-block" id="hump.timeradd"><h4>function <span class="name">add</span><span class="arglist">(delay, func)</span><a class="top" href="#hump.timer">^top</a></h4><p>Schedule a function. The function will be executed after <code class="lua">delay</code> seconds have
elapsed, given that <code class="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><code class="lua">func</code> will receive itself as only parameter. This is useful to implement
periodic behavior (see the example).</p>
<div class="arguments">Parameters:<dl>
<dt>number <code class="lua">delay</code></dt>
<dd>Number of seconds the function will be delayed.</dd><dt>function <code class="lua">func</code></dt>
<dd>The function to be delayed.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>table</dt>
<dd>The timer handle.</dd></dl>
</div><div class="example">Examples:<pre><code class="lua">-- grant the player 5 seconds of immortality
player.isInvincible = true
Timer.add(5, function() player.isInvincible = false end)
</code></pre>
<pre><code class="lua">-- print "foo" every second. See also addPeriodic()
Timer.add(1, function(func) print("foo") Timer.add(1, func) end)
</code></pre>
<pre><code class="lua">--Using a timer instance:
menuTimer:add(1, finishAnimation)
</code></pre>
</div></div><div class="ref-block" id="hump.timeraddPeriodic"><h4>function <span class="name">addPeriodic</span><span class="arglist">(delay, func)</span><a class="top" href="#hump.timer">^top</a></h4><p>Add a function that will be called <code class="lua">count</code> times every <code class="lua">delay</code> seconds.</p>
<p>If <code class="lua">count</code> is omitted, the function will be called until it returns <code class="lua">false</code> or
<a href="#hump.timercancel"><code class="lua">cancel(handle)</code></a> or <a href="#hump.timerclear"><code class="lua">clear()</code></a> is
called.</p>
<div class="arguments">Parameters:<dl>
<dt>number <code class="lua">delay</code></dt>
<dd>Number of seconds between two consecutive function calls.</dd><dt>function <code class="lua">func</code></dt>
<dd>The function to be called periodically.</dd><dt>number <code class="lua">count</code> (optional)</dt>
<dd>Number of times the function is to be called.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>table</dt>
<dd>The timer handle. See also <a href="#hump.timercancel"><code class="lua">cancel()</code></a>.</dd></dl>
</div><div class="example">Examples:<pre><code class="lua">-- toggle light on and off every second
Timer.addPeriodic(1, function() lamp:toggleLight() end)
</code></pre>
<pre><code class="lua">-- launch 5 fighters in quick succession (using a timer instance)
mothership_timer:addPeriodic(0.3, function() self:launchFighter() end, 5)
</code></pre>
<pre><code class="lua">-- flicker player's image as long as he is invincible
Timer.addPeriodic(0.1, function()
player:flipImage()
return player.isInvincible
end)
</code></pre>
</div></div><div class="ref-block" id="hump.timerdo_for"><h4>function <span class="name">do_for</span><span class="arglist">(delay, func, after)</span><a class="top" href="#hump.timer">^top</a></h4><p>Run <code class="lua">func(dt)</code> for the next <code class="lua">delta</code> seconds. The function is called every time
<code class="lua">update(dt)</code> is called. Optionally run <code class="lua">after()</code> once <code class="lua">delta</code> seconds have
passed.</p>
<p><code class="lua">after()</code> will receive itself as only parameter.</p>
<p><strong>Note:</strong> You should not add new timers in <code class="lua">func(dt)</code>, as this can lead to random
crashes.</p>
<div class="arguments">Parameters:<dl>
<dt>number <code class="lua">delta</code></dt>
<dd>Number of seconds the func will be called.</dd><dt>function <code class="lua">func</code></dt>
<dd>The function to be called on <code class="lua">update(dt)</code>.</dd><dt>function <code class="lua">after</code> (optional)</dt>
<dd>A function to be called after delta seconds.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>table</dt>
<dd>The timer handle.</dd></dl>
</div><div class="example">Examples:<pre><code class="lua">-- play an animation for 5 seconds
Timer.do_for(5, function(dt) animation:update(dt) end)
</code></pre>
<pre><code class="lua">-- shake the camera for one second
local orig_x, orig_y = camera:pos()
Timer.do_for(1, function()
camera:lookAt(orig_x + math.random(-2,2), orig_y + math.random(-2,2))
end, function()
-- reset camera position
camera:lookAt(orig_x, orig_y)
end)
</code></pre>
<pre><code class="lua">player.isInvincible = true
-- flash player for 3 seconds
local t = 0
player.timer:do_for(3, function(dt)
t = t + dt
player.visible = (t % .2) &lt; .1
end, function()
-- make sure the player is visible after three seconds
player.visible = true
player.isInvincible = false
end)
</code></pre>
</div></div><div class="ref-block" id="hump.timercancel"><h4>function <span class="name">cancel</span><span class="arglist">(handle)</span><a class="top" href="#hump.timer">^top</a></h4><p>Prevent a timer from being executed in the future.</p>
<div class="arguments">Parameters:<dl>
<dt>table <code class="lua">handle</code></dt>
<dd>The function to be canceled.</dd></dl>
</div><div class="returns">Returns:<dl><dt>Nothing</dt></dl></div><div class="example">Examples:<pre><code class="lua">function tick()
print('tick... tock...')
end
handle = Timer.addPeriodic(1, tick)
-- later
Timer.cancel(handle) -- NOT: Timer.cancel(tick)
</code></pre>
<pre><code class="lua">-- using a timer instance
function tick()
print('tick... tock...')
end
handle = menuTimer:addPeriodic(1, tick)
-- later
menuTimer:cancel(handle)
</code></pre>
</div></div><div class="ref-block" id="hump.timerclear"><h4>function <span class="name">clear</span><span class="arglist">()</span><a class="top" href="#hump.timer">^top</a></h4><p>Remove all timed and periodic functions. Functions that have not yet been
executed will discarded.</p>
<div class="arguments">Parameters:<dl><dt>None</dt></dl></div><div class="returns">Returns:<dl><dt>Nothing</dt></dl></div><div class="example">Examples:<pre><code class="lua">Timer.clear()
</code></pre>
<pre><code class="lua">menu_timer:clear()
</code></pre>
</div></div><div class="ref-block" id="hump.timerupdate"><h4>function <span class="name">update</span><span class="arglist">(dt)</span><a class="top" href="#hump.timer">^top</a></h4><p>Update timers and execute functions if the deadline is reached. Use this in
<code class="lua">love.update(dt)</code>.</p>
<div class="arguments">Parameters:<dl>
<dt>number <code class="lua">dt</code></dt>
<dd>Time that has passed since the last <code class="lua">update()</code>.</dd></dl>
</div><div class="returns">Returns:<dl><dt>Nothing</dt></dl></div><div class="example">Examples:<pre><code class="lua">function love.update(dt)
do_stuff()
Timer.update(dt)
end
</code></pre>
<pre><code class="lua">-- using hump.gamestate and a timer instance
function menuState:update(dt)
self.timer:update(dt)
end
</code></pre>
</div></div><div class="ref-block" id="hump.timertween"><h4>function <span class="name">tween</span><span class="arglist">(duration, subject, target, method, after, ...)</span><a class="top" href="#hump.timer">^top</a></h4><p><a href="http://en.wikipedia.org/wiki/Inbetweening">Tweening</a> (short for in-betweening)
is the process that happens between two defined states. For example, a tween
can be used to gradually fade out a graphic or move a text message to the
center of the screen. For more information why tweening should be important to
you, check out this great talk on <a href="http://www.youtube.com/watch?v=Fy0aCDmgnxg">juicy
games</a>.</p>
<p><code class="lua">hump.timer</code> offers two interfaces for tweening: the low-level
<a href="#hump.timerdofor"><code class="lua">timer.to_for()</code></a> and the higher level interface
<a href="#hump.timertween"><code class="lua">timer.tween()</code></a>.</p>
<p>To see which tweening methods hump offers, <a href="#hump.timerTweening_methods">see
below</a>.</p>
<div class="arguments">Parameters:<dl>
<dt>number <code class="lua">duration</code></dt>
<dd>Duration of the tween.</dd><dt>table <code class="lua">subject</code></dt>
<dd>Object to be tweened.</dd><dt>table <code class="lua">target</code></dt>
<dd>Target values.</dd><dt>string <code class="lua">method</code> (optional)</dt>
<dd>Tweening method, defaults to 'linear' (<a href="#hump.timerTweening_methods">see here</a>).</dd><dt>function <code class="lua">after</code> (optiona)</dt>
<dd>Function to execute after the tween has finished.</dd><dt>mixed <code class="lua">...</code></dt>
<dd>Additional arguments to the <em>tweening</em> function.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>table</dt>
<dd>A timer handle.</dd></dl>
</div><div class="example">Examples:<pre><code class="lua">function love.load()
color = {0, 0, 0}
Timer.tween(10, color, {255, 255, 255}, 'in-out-quad')
end
function love.update(dt)
Timer.update(dt)
end
function love.draw()
love.graphics.setBackgroundColor(color)
end
</code></pre>
<pre><code class="lua">function love.load()
circle = {rad = 10, pos = {x = 400, y = 300}}
-- multiple tweens can work on the same subject
-- and nested values can be tweened, too
Timer.tween(5, circle, {rad = 50}, 'in-out-quad')
Timer.tween(2, circle, {pos = {y = 550}}, 'out-bounce')
end
function love.update(dt)
Timer.update(dt)
end
function love.draw()
love.graphics.circle('fill', circle.pos.x, circle.pos.y, circle.rad)
end
</code></pre>
<pre><code class="lua">function love.load()
-- repeated tweening
circle = {rad = 10, x = 100, y = 100}
local grow, shrink, move_down, move_up
grow = function()
Timer.tween(1, circle, {rad = 50}, 'in-out-quad', shrink)
end
shrink = function()
Timer.tween(2, circle, {rad = 10}, 'in-out-quad', grow)
end
move_down = function()
Timer.tween(3, circle, {x = 700, y = 500}, 'bounce', move_up)
end
move_up = function()
Timer.tween(5, circle, {x = 200, y = 200}, 'out-elastic', move_down)
end
grow()
move_down()
end
function love.update(dt)
Timer.update(dt)
end
function love.draw()
love.graphics.circle('fill', circle.x, circle.y, circle.rad)
end
</code></pre>
</div></div><div class="section-block" id="hump.timerTweening_methods"><h4>Tweening methods <a class="top" href="#hump.timer">^top</a></h4><p>At the core of tweening lie interpolation methods. These methods define how the
output should look depending on how much time has passed. For example, consider
the following tween:</p>
<pre><code class="lua">-- now: player.x = 0, player.y = 0
Timer.tween(2, player, {x = 2})
Timer.tween(4, player, {y = 8})
</code></pre>
<p>At the beginning of the tweens (no time passed), the interpolation method would
place the player at <code class="lua">x = 0, y = 0</code>. After one second, the player should be at
<code class="lua">x = 1, y = 2</code>, and after two seconds the output is <code class="lua">x = 2, y = 4</code>.</p>
<p>The actual duration of and time since starting the tween is not important, only
the fraction of the two. Similarly, the starting value and output are not
important to the interpolation method, since it can be calculated from the
start and end point. Thus an interpolation method can be fully characterized by
a function that takes a number between 0 and 1 and returns a number that
defines the output (usually also between 0 and 1). The interpolation function
must hold that the output is 0 for input 0 and 1 for input 1.</p>
<p><code class="lua">hump</code> predefines several commonly used interpolation methods, which are
generalized versions of <a href="http://www.robertpenner.com/easing/">Robert Penner's easing
functions</a>. Those are:</p>
<p><code class="lua">'linear'</code>, <code class="lua">'quad'</code>, <code class="lua">'cubic'</code>, <code class="lua">'quart'</code>, <code class="lua">'quint'</code>, <code class="lua">'sine'</code>,
<code class="lua">'expo'</code>, <code class="lua">'circ'</code>, <code class="lua">'back'</code>, <code class="lua">'bounce'</code>, and <code class="lua">'elastic'</code>.</p>
<p>Here are their respective graphs:</p>
<p><img src="interpolators.png" alt="Graph of interpolation functions" /></p>
<p>All methods can be 'inverted' by prefixing the keyword <code class="lua">out-</code>, for example
<code class="lua">'out-quad'</code>, <code class="lua">'out-sine'</code>, <code class="lua">'out-bounce'</code>, etc:</p>
<p><img src="inv-interpolators.png" alt="Graph of inverted interpolation functions" /></p>
<p>The <code class="lua">in-out-</code> and <code class="lua">out-in-</code> prefix chain the interpolators:</p>
<p><img src="in-out-interpolators.png" alt="Graph of chained interpolation functions" /></p>
<p>Of course these graphs cannot show how the different methods compare, so here's
an example script that highlights the different tweens:</p>
<pre><code class="lua">Timer = require 'hump.timer'
function love.load()
methods = {'linear', 'quad', 'cubic', 'quart', 'quint', 'sine', 'expo', 'circ', 'back', 'bounce', 'elastic'}
method = methods[#methods]
next_method = {} -- next_method.linear = 'quad', etc
for i = 1,#methods do
next_method[methods[i]] = methods[(i%#methods)+1]
end
target = {x = 700, brightness = 200, radius = 50}
local function reset()
circle = {
{x = 100, y = 100, brightness = 100, radius = 20},
{x = 100, y = 233, brightness = 100, radius = 20},
{x = 100, y = 367, brightness = 100, radius = 20},
{x = 100, y = 500, brightness = 100, radius = 20},
}
method = next_method[method]
Timer.tween(3, circle[1], target, 'in-'..method)
Timer.tween(3, circle[2], target, 'out-'..method)
Timer.tween(3, circle[3], target, 'in-out-'..method)
Timer.tween(3, circle[4], target, 'out-in-'..method,
function() Timer.add(.5, reset) end)
end
reset()
end
function love.update(dt)
Timer.update(dt)
end
function love.draw()
love.graphics.setColor(255,255,255)
love.graphics.print('in-' .. method, 50, 100-50)
love.graphics.print('out-' .. method, 50, 233-50)
love.graphics.print('in-out-' .. method, 50, 367-50)
love.graphics.print('out-in-' .. method, 50, 500-50)
for i = 1,#circle do
love.graphics.setColor(255,255,255, circle[i].brightness)
love.graphics.circle('fill', circle[i].x, circle[i].y,
circle[i].radius)
end
end
</code></pre>
</div><div class="section-block" id="hump.timerCustom_interpolators"><h4>Custom interpolators <a class="top" href="#hump.timer">^top</a></h4><p><strong>This is a stub</strong></p>
<p>You can add custom interpolation methods by adding them to the <code class="lua">tween</code> table:</p>
<pre><code class="lua">Timer.tween.sqrt = function(t) return math.sqrt(t) end
-- or just Timer.tween.sqrt = math.sqrt
</code></pre>
<p>Access the your method like you would the predefined ones. You can even use the
modyfing prefixes:</p>
<pre><code class="lua">Timer.tween(5, 'in-out-sqrt', circle, {radius = 50})
</code></pre>
<p>You can also invert and chain functions:</p>
<pre><code class="lua">outsqrt = Timer.tween.out(math.sqrt)
inoutsqrt = Timer.tween.chain(math.sqrt, outsqrt)
</code></pre>
</div></div><div class="outer-block" id="hump.vector"><h3>hump.vector<a class="top" href="#top">^top</a></h3><div class="preamble"><pre><code class="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 vec.x and vec.y.</p>
<h4>Example:</h4>
<pre><code class="lua">function player:update(dt)
local delta = vector(0,0)
if love.keyboard.isDown('left') then
delta.x = -1
elseif love.keyboard.isDown('right') then
delta.x = 1
end
if love.keyboard.isDown('up') then
delta.y = -1
elseif love.keyboard.isDown('down') then
delta.y = 1
end
delta:normalize_inplace()
player.velocity = player.velocity + delta * player.acceleration * dt
if player.velocity:len() &gt; player.max_velocity then
player.velocity = player.velocity:normalized() * player.max_velocity
end
player.position = player.position + player.velocity * dt
end
</code></pre>
</div><div class="overview"><h4>Module overview</h4><dl><dt><a href="#hump.vectorOperators">Operators </a></dt><dd>Arithmetics and relations.</dd><dt><a href="#hump.vectornew">new()</a></dt><dd>Create a new vector.</dd><dt><a href="#hump.vectorisvector">isvector()</a></dt><dd>Test if value is a vector.</dd><dt><a href="#hump.vectorvector:clone">vector:clone()</a></dt><dd>Copy a vector.</dd><dt><a href="#hump.vectorvector:unpack">vector:unpack()</a></dt><dd>Extract coordinates.</dd><dt><a href="#hump.vectorvector:permul">vector:permul()</a></dt><dd>Per element multiplication.</dd><dt><a href="#hump.vectorvector:len">vector:len()</a></dt><dd>Get length.</dd><dt><a href="#hump.vectorvector:len2">vector:len2()</a></dt><dd>Get squared length.</dd><dt><a href="#hump.vectorvector:dist">vector:dist()</a></dt><dd>Distance to other vector.</dd><dt><a href="#hump.vectorvector:dist2">vector:dist2()</a></dt><dd>Squared distance to other vector.</dd><dt><a href="#hump.vectorvector:normalized">vector:normalized()</a></dt><dd>Get normalized vector.</dd><dt><a href="#hump.vectorvector:normalize_inplace">vector:normalize_inplace()</a></dt><dd>Normalize vector in-place.</dd><dt><a href="#hump.vectorvector:rotated">vector:rotated()</a></dt><dd>Get rotated vector.</dd><dt><a href="#hump.vectorvector:rotate_inplace">vector:rotate_inplace()</a></dt><dd>Rotate vector in-place.</dd><dt><a href="#hump.vectorvector:perpendicular">vector:perpendicular()</a></dt><dd>Get perpendicular vector.</dd><dt><a href="#hump.vectorvector:projectOn">vector:projectOn()</a></dt><dd>Get projection onto another vector.</dd><dt><a href="#hump.vectorvector:mirrorOn">vector:mirrorOn()</a></dt><dd>Mirrors vector on other vector</dd><dt><a href="#hump.vectorvector:cross">vector:cross()</a></dt><dd>Cross product of two vectors.</dd><dt><a href="#hump.vectorvector:angleTo">vector:angleTo()</a></dt><dd>Measure angle between two vectors.</dd></dl></div><div class="section-block" id="hump.vectorOperators"><h4>Operators <a class="top" href="#hump.vector">^top</a></h4><p>Vector arithmetic is implemented by using <code class="lua">__add</code>, <code class="lua">__mul</code> and other
metamethods:</p>
<dl>
<dt><code class="lua">vector + vector = vector</code></dt>
<dd>Component wise sum.</dd><dt><code class="lua">vector - vector = vector</code></dt>
<dd>Component wise difference.</dd><dt><code class="lua">vector * vector = number</code></dt>
<dd>Dot product.</dd><dt><code class="lua">number * vector = vector</code></dt>
<dd>Scalar multiplication (scaling).</dd><dt><code class="lua">vector * number = vector</code></dt>
<dd>Scalar multiplication.</dd><dt><code class="lua">vector / number = vector</code></dt>
<dd>Scalar multiplication.</dd></dl>
<p>Relational operators are defined, too:</p>
<dl>
<dt><code class="lua">a == b</code></dt>
<dd>Same as <code class="lua">a.x == b.x and a.y == b.y</code>.</dd><dt><code class="lua">a &lt;= b</code></dt>
<dd>Same as <code class="lua">a.x &lt;= b.x and a.y &lt;= b.y</code>.</dd><dt><code class="lua">a &lt; b</code></dt>
<dd>Lexical sort: <code class="lua">a.x &lt; b.x or (a.x == b.x and a.y &lt; b.y)</code>.</dd></dl>
<h4>Example:</h4>
<pre><code class="lua">-- acceleration, player.velocity and player.position are vectors
acceleration = vector(0,-9)
player.velocity = player.velocity + acceleration * dt
player.position = player.position + player.velocity * dt
</code></pre>
</div><div class="ref-block" id="hump.vectornew"><h4>function <span class="name">new</span><span class="arglist">(x,y)</span><a class="top" href="#hump.vector">^top</a></h4><p>Create a new vector.</p>
<div class="arguments">Parameters:<dl>
<dt>numbers <code class="lua">x,y</code></dt>
<dd>Coordinates.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>vector</dt>
<dd>The vector.</dd></dl>
</div><div class="example">Examples:<pre><code class="lua">a = vector.new(10,10)
</code></pre>
<pre><code class="lua">-- as a shortcut, you can call the module like a function:
vector = require "hump.vector"
a = vector(10,10)
</code></pre>
</div></div><div class="ref-block" id="hump.vectorisvector"><h4>function <span class="name">isvector</span><span class="arglist">(v)</span><a class="top" href="#hump.vector">^top</a></h4><p>Test whether a variable is a vector.</p>
<div class="arguments">Parameters:<dl>
<dt>mixed <code class="lua">v</code></dt>
<dd>The variable to test.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>boolean</dt>
<dd><code class="lua">true</code> if <code class="lua">v</code> is a vector, <code class="lua">false</code> otherwise</dd></dl>
</div><div class="example">Example:<pre><code class="lua">if not vector.isvector(v) then
v = vector(v,0)
end
</code></pre>
</div></div><div class="ref-block" id="hump.vectorvector:clone"><h4>function <span class="name">vector:clone</span><span class="arglist">()</span><a class="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
also change the old one:</p>
<pre><code class="lua">a = vector(1,1) -- create vector
b = a -- b references a
c = a:clone() -- c is a copy of a
b.x = 0 -- changes a,b and c
print(a,b,c) -- prints '(1,0), (1,0), (1,1)'
</code></pre>
<div class="arguments">Parameters:<dl><dt>None</dt></dl></div><div class="returns">Returns:<dl>
<dt>vector</dt>
<dd>Copy of the vector</dd></dl>
</div><div class="example">Example:<pre><code class="lua">copy = original:clone()
</code></pre>
</div></div><div class="ref-block" id="hump.vectorvector:unpack"><h4>function <span class="name">vector:unpack</span><span class="arglist">()</span><a class="top" href="#hump.vector">^top</a></h4><p>Extract coordinates.</p>
<div class="arguments">Parameters:<dl><dt>None</dt></dl></div><div class="returns">Returns:<dl>
<dt>numbers</dt>
<dd>The coordinates</dd></dl>
</div><div class="example">Examples:<pre><code class="lua">x,y = pos:unpack()
</code></pre>
<pre><code class="lua">love.graphics.draw(self.image, self.pos:unpack())
</code></pre>
</div></div><div class="ref-block" id="hump.vectorvector:permul"><h4>function <span class="name">vector:permul</span><span class="arglist">(other)</span><a class="top" href="#hump.vector">^top</a></h4><p>Multiplies vectors coordinate wise, i.e. <code class="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>
<div class="arguments">Parameters:<dl>
<dt>vector <code class="lua">other</code></dt>
<dd>The other vector</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>vector</dt>
<dd>The new vector as described above</dd></dl>
</div><div class="example">Example:<pre><code class="lua">scaled = original:permul(vector(1,1.5))
</code></pre>
</div></div><div class="ref-block" id="hump.vectorvector:len"><h4>function <span class="name">vector:len</span><span class="arglist">()</span><a class="top" href="#hump.vector">^top</a></h4><p>Get length of a vector, i.e. <code class="lua">math.sqrt(vec.x * vec.x + vec.y * vec.y)</code>.</p>
<div class="arguments">Parameters:<dl><dt>None</dt></dl></div><div class="returns">Returns:<dl>
<dt>number</dt>
<dd>Length of the vector.</dd></dl>
</div><div class="example">Example:<pre><code class="lua">distance = (a - b):len()
</code></pre>
</div></div><div class="ref-block" id="hump.vectorvector:len2"><h4>function <span class="name">vector:len2</span><span class="arglist">()</span><a class="top" href="#hump.vector">^top</a></h4><p>Get squared length of a vector, i.e. <code class="lua">vec.x * vec.x + vec.y * vec.y</code>.</p>
<div class="arguments">Parameters:<dl><dt>None</dt></dl></div><div class="returns">Returns:<dl>
<dt>number</dt>
<dd>Squared length of the vector.</dd></dl>
</div><div class="example">Example:<pre><code class="lua">-- get closest vertex to a given vector
closest, dsq = vertices[1], (pos - vertices[1]):len2()
for i = 2,#vertices do
local temp = (pos - vertices[i]):len2()
if temp &lt; dsq then
closest, dsq = vertices[i], temp
end
end
</code></pre>
</div></div><div class="ref-block" id="hump.vectorvector:dist"><h4>function <span class="name">vector:dist</span><span class="arglist">(other)</span><a class="top" href="#hump.vector">^top</a></h4><p>Get distance of two vectors. The same as <code class="lua">(a - b):len()</code>.</p>
<div class="arguments">Parameters:<dl>
<dt>vector <code class="lua">other</code></dt>
<dd>Other vector to measure the distance to.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>number</dt>
<dd>The distance of the vectors.</dd></dl>
</div><div class="example">Example:<pre><code class="lua">-- get closest vertex to a given vector
-- slightly slower than the example using len2()
closest, dist = vertices[1], pos:dist(vertices[1])
for i = 2,#vertices do
local temp = pos:dist(vertices[i])
if temp &lt; dist then
closest, dist = vertices[i], temp
end
end
</code></pre>
</div></div><div class="ref-block" id="hump.vectorvector:dist2"><h4>function <span class="name">vector:dist2</span><span class="arglist">(other)</span><a class="top" href="#hump.vector">^top</a></h4><p>Get squared distance of two vectors. The same as <code class="lua">(a - b):len2()</code>.</p>
<div class="arguments">Parameters:<dl>
<dt>vector <code class="lua">other</code></dt>
<dd>Other vector to measure the distance to.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>number</dt>
<dd>The squared distance of the vectors.</dd></dl>
</div><div class="example">Example:<pre><code class="lua">-- get closest vertex to a given vector
-- slightly faster than the example using len2()
closest, dsq = vertices[1], pos:dist2(vertices[1])
for i = 2,#vertices do
local temp = pos:dist2(vertices[i])
if temp &lt; dsq then
closest, dsq = vertices[i], temp
end
end
</code></pre>
</div></div><div class="ref-block" id="hump.vectorvector:normalized"><h4>function <span class="name">vector:normalized</span><span class="arglist">()</span><a class="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 class="arguments">Parameters:<dl><dt>None</dt></dl></div><div class="returns">Returns:<dl>
<dt>vector</dt>
<dd>Vector with same direction as the input vector, but length 1.</dd></dl>
</div><div class="example">Example:<pre><code class="lua">direction = velocity:normalized()
</code></pre>
</div></div><div class="ref-block" id="hump.vectorvector:normalize_inplace"><h4>function <span class="name">vector:normalize_inplace</span><span class="arglist">()</span><a class="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
<a href="#hump.vectornormalized"><code class="lua">vector:normalized()</code></a>.</strong></p>
<div class="arguments">Parameters:<dl><dt>None</dt></dl></div><div class="returns">Returns:<dl>
<dt>vector</dt>
<dd>Itself - the normalized vector</dd></dl>
</div><div class="example">Example:<pre><code class="lua">normal = (b - a):perpendicular():normalize_inplace()
</code></pre>
</div></div><div class="ref-block" id="hump.vectorvector:rotated"><h4>function <span class="name">vector:rotated</span><span class="arglist">(angle)</span><a class="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>
<div class="arguments">Parameters:<dl>
<dt>number <code class="lua">angle</code></dt>
<dd>Rotation angle in radians.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>vector</dt>
<dd>The rotated vector</dd></dl>
</div><div class="example">Example:<pre><code class="lua">-- approximate a circle
circle = {}
for i = 1,30 do
local phi = 2 * math.pi * i / 30
circle[#circle+1] = vector(0,1):rotated(phi)
end
</code></pre>
</div><div class="example">Sketch:<p><img src="vector-rotated.png" alt="Rotated vector sketch" /></p>
</div></div><div class="ref-block" id="hump.vectorvector:rotate_inplace"><h4>function <span class="name">vector:rotate_inplace</span><span class="arglist">(angle)</span><a class="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
<a href="#hump.vectorrotate"><code class="lua">vector:rotate()</code></a>.</strong></p>
<div class="arguments">Parameters:<dl>
<dt>number <code class="lua">angle</code></dt>
<dd>Rotation angle in radians.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>vector</dt>
<dd>Itself - the rotated vector</dd></dl>
</div><div class="example">Example:<pre><code class="lua">-- ongoing rotation
spawner.direction:rotate_inplace(dt)
</code></pre>
</div></div><div class="ref-block" id="hump.vectorvector:perpendicular"><h4>function <span class="name">vector:perpendicular</span><span class="arglist">()</span><a class="top" href="#hump.vector">^top</a></h4><p>Quick rotation by 90°. Creates a new vector. The same (but faster) as
<code class="lua">vec:rotate(math.pi/2)</code>.</p>
<div class="arguments">Parameters:<dl><dt>None</dt></dl></div><div class="returns">Returns:<dl>
<dt>vector</dt>
<dd>A vector perpendicular to the input vector</dd></dl>
</div><div class="example">Example:<pre><code class="lua">normal = (b - a):perpendicular():normalize_inplace()
</code></pre>
</div><div class="example">Sketch:<p><img src="vector-perpendicular.png" alt="Perpendiculat vector sketch" /></p>
</div></div><div class="ref-block" id="hump.vectorvector:projectOn"><h4>function <span class="name">vector:projectOn</span><span class="arglist">(v)</span><a class="top" href="#hump.vector">^top</a></h4><p>Project vector onto another vector (see sketch).</p>
<div class="arguments">Parameters:<dl>
<dt>vector <code class="lua">v</code></dt>
<dd>The vector to project on.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>vector</dt>
<dd>The projected vector.</dd></dl>
</div><div class="example">Example:<pre><code class="lua">velocity_component = velocity:projectOn(axis)
</code></pre>
</div><div class="example">Sketch:<p><img src="vector-projectOn.png" alt="Projected vector sketch" /></p>
</div></div><div class="ref-block" id="hump.vectorvector:mirrorOn"><h4>function <span class="name">vector:mirrorOn</span><span class="arglist">(v)</span><a class="top" href="#hump.vector">^top</a></h4><p>Mirrors vector on the axis defined by the other vector.</p>
<div class="arguments">Parameters:<dl>
<dt>vector <code class="lua">v</code></dt>
<dd>The vector to mirror on.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>vector</dt>
<dd>The mirrored vector.</dd></dl>
</div><div class="example">Example:<pre><code class="lua">deflected_velocity = ball.velocity:mirrorOn(surface_normal)
</code></pre>
</div><div class="example">Sketch:<p><img src="vector-mirrorOn.png" alt="Mirrored vector sketch" /></p>
</div></div><div class="ref-block" id="hump.vectorvector:cross"><h4>function <span class="name">vector:cross</span><span class="arglist">(other)</span><a class="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>
<div class="arguments">Parameters:<dl>
<dt>vector <code class="lua">other</code></dt>
<dd>Vector to compute the cross product with.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>number</dt>
<dd>Cross product of both vectors.</dd></dl>
</div><div class="example">Example:<pre><code class="lua">parallelogram_area = a:cross(b)
</code></pre>
</div></div><div class="ref-block" id="hump.vectorvector:angleTo"><h4>function <span class="name">vector:angleTo</span><span class="arglist">(other)</span><a class="top" href="#hump.vector">^top</a></h4><p>Measures the angle between two vectors. If <code class="lua">other</code> is omitted it defaults
to the vector <code class="lua">(0,0)</code>, i.e. the function returns the angle to the coordinate
system.</p>
<div class="arguments">Parameters:<dl>
<dt>vector <code class="lua">other</code> (optional)</dt>
<dd>Vector to measure the angle to.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>number</dt>
<dd>Angle in radians.</dd></dl>
</div><div class="example">Example:<pre><code class="lua">lean = self.upvector:angleTo(vector(0,1))
if lean &gt; .1 then self:fallOver() end
</code></pre>
</div></div></div><div class="outer-block" id="hump.vector-light"><h3>hump.vector-light<a class="top" href="#top">^top</a></h3><div class="preamble"><pre><code class="lua">vector = require "hump.vector-light"
</code></pre>
<p>An table-free version of <a href="#hump.vector"><code class="lua">hump.vector</code></a>. Instead of a vector
type, <code class="lua">hump.vector-light</code> provides functions that operate on numbers.</p>
<p><strong>Note:</strong> Using this module instead of <a href="#hump.vector"><code class="lua">hump.vector</code></a> 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 using
<a href="#hump.vector"><code class="lua">hump.vector</code></a>.</p>
<h4>Example:</h4>
<pre><code class="lua">function player:update(dt)
local dx,dy = 0,0
if love.keyboard.isDown('left') then
dx = -1
elseif love.keyboard.isDown('right') then
dx = 1
end
if love.keyboard.isDown('up') then
dy = -1
elseif love.keyboard.isDown('down') then
dy = 1
end
dx,dy = vector.normalize(dx, dy)
player.velx, player.vely = vector.add(player.velx, player.vely,
vector.mul(dy, dx, dy))
if vector.len(player.velx, player.vely) &gt; player.max_velocity then
player.velx, player.vely = vector.mul(player.max_velocity,
vector.normalize(player.velx, player.vely)
end
player.x = player.x + dt * player.velx
player.y = player.y + dt * player.vely
end
</code></pre>
</div><div class="overview"><h4>Module overview</h4><dl><dt><a href="#hump.vector-lightstr">str()</a></dt><dd>String representation.</dd><dt><a href="#hump.vector-lightmul">mul()</a></dt><dd>Product of a vector and a scalar.</dd><dt><a href="#hump.vector-lightdiv">div()</a></dt><dd>Product of a vector and the inverse of a scalar.</dd><dt><a href="#hump.vector-lightadd">add()</a></dt><dd>Sum of two vectors.</dd><dt><a href="#hump.vector-lightsub">sub()</a></dt><dd>Difference of two vectors.</dd><dt><a href="#hump.vector-lightpermul">permul()</a></dt><dd>Per element multiplication.</dd><dt><a href="#hump.vector-lightdot">dot()</a></dt><dd>Dot product.</dd><dt><a href="#hump.vector-lightcross">cross()</a></dt><dd>Cross product.</dd><dt><a href="#hump.vector-lighteq">eq()</a></dt><dd>Equality.</dd><dt><a href="#hump.vector-lightle">le()</a></dt><dd>Partial lexical order.</dd><dt><a href="#hump.vector-lightlt">lt()</a></dt><dd>Strict lexical order.</dd><dt><a href="#hump.vector-lightlen">len()</a></dt><dd>Get length.</dd><dt><a href="#hump.vector-lightlen2">len2()</a></dt><dd>Get squared length.</dd><dt><a href="#hump.vector-lightdist">dist()</a></dt><dd>Distance of two points.</dd><dt><a href="#hump.vector-lightdist2">dist2()</a></dt><dd>Squared distance of two points.</dd><dt><a href="#hump.vector-lightnormalize">normalize()</a></dt><dd>Normalize vector.</dd><dt><a href="#hump.vector-lightrotate">rotate()</a></dt><dd>Rotate vector.</dd><dt><a href="#hump.vector-lightperpendicular">perpendicular()</a></dt><dd>Get perpendicular vector.</dd><dt><a href="#hump.vector-lightproject">project()</a></dt><dd>Project vector onto another vector.</dd><dt><a href="#hump.vector-lightmirror">mirror()</a></dt><dd>Mirror vector on other vector.</dd><dt><a href="#hump.vector-lightangleTo">angleTo()</a></dt><dd>Measure angle between two vectors.</dd></dl></div><div class="ref-block" id="hump.vector-lightstr"><h4>function <span class="name">str</span><span class="arglist">(x,y)</span><a class="top" href="#hump.vector-light">^top</a></h4><p>Transforms a vector to a string of the form <code class="lua">(x,y)</code>.</p>
<div class="arguments">Parameters:<dl>
<dt>numbers <code class="lua">x,y</code></dt>
<dd>The vector</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>string</dt>
<dd>The string representation</dd></dl>
</div><div class="example">Example:<pre><code class="lua">print(vector.str(love.mouse.getPosition()))
</code></pre>
</div></div><div class="ref-block" id="hump.vector-lightmul"><h4>function <span class="name">mul</span><span class="arglist">(s, x,y)</span><a class="top" href="#hump.vector-light">^top</a></h4><p>Computes <code class="lua">x*s,y*s</code>. The order of arguments is chosen so that it's possible to
chain multiple operations (see example).</p>
<div class="arguments">Parameters:<dl>
<dt>number <code class="lua">s</code></dt>
<dd>The scalar.</dd><dt>numbers <code class="lua">x,y</code></dt>
<dd>The vector.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>numbers</dt>
<dd><code class="lua">x*s, y*s</code></dd></dl>
</div><div class="example">Example:<pre><code class="lua">velx,vely = vec.mul(dt, vec.add(velx,vely, accx,accy))
</code></pre>
</div></div><div class="ref-block" id="hump.vector-lightdiv"><h4>function <span class="name">div</span><span class="arglist">(s, x,y)</span><a class="top" href="#hump.vector-light">^top</a></h4><p>Computes <code class="lua">x/s,y/s</code>. The order of arguments is chosen so that it's possible to
chain multiple operations.</p>
<div class="arguments">Parameters:<dl>
<dt>number <code class="lua">s</code></dt>
<dd>The scalar.</dd><dt>numbers <code class="lua">x,y</code></dt>
<dd>The vector.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>numbers</dt>
<dd><code class="lua">x/s, y/s</code></dd></dl>
</div><div class="example">Example:<pre><code class="lua">x,y = vec.div(self.zoom, x-w/2, y-h/2)
</code></pre>
</div></div><div class="ref-block" id="hump.vector-lightadd"><h4>function <span class="name">add</span><span class="arglist">(x1,y1, x2,y2)</span><a class="top" href="#hump.vector-light">^top</a></h4><p>Computes the sum (<code class="lua">x1+x2,y1+y2</code>) of two vectors. Meant to be used in
conjunction with other functions.</p>
<div class="arguments">Parameters:<dl>
<dt>numbers <code class="lua">x1,y1</code></dt>
<dd>First vector.</dd><dt>numbers <code class="lua">x2,y2</code></dt>
<dd>Second vector.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>numbers</dt>
<dd><code class="lua">x1+x2, x1+x2</code></dd></dl>
</div><div class="example">Example:<pre><code class="lua">player.x,player.y = vector.add(player.x,player.y, vector.mul(dt, dx,dy))
</code></pre>
</div></div><div class="ref-block" id="hump.vector-lightsub"><h4>function <span class="name">sub</span><span class="arglist">(x1,y1, x2,y2)</span><a class="top" href="#hump.vector-light">^top</a></h4><p>Computes the difference (<code class="lua">x1-x2,y1-y2</code>) of two vectors. Meant to be used in
conjunction with other functions.</p>
<div class="arguments">Parameters:<dl>
<dt>numbers <code class="lua">x1,y1</code></dt>
<dd>First vector.</dd><dt>numbers <code class="lua">x2,y2</code></dt>
<dd>Second vector.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>numbers</dt>
<dd><code class="lua">x1-x2, x1-x2</code></dd></dl>
</div><div class="example">Example:<pre><code class="lua">dx,dy = vector.sub(400,300, love.mouse.getPosition())
</code></pre>
</div></div><div class="ref-block" id="hump.vector-lightpermul"><h4>function <span class="name">permul</span><span class="arglist">(x1,y1, x2,y2)</span><a class="top" href="#hump.vector-light">^top</a></h4><p>Multiplies vectors coordinates, i.e.: <code class="lua">x1*x2, y1*y2</code>.</p>
<div class="arguments">Parameters:<dl>
<dt>numbers <code class="lua">x1,y1</code></dt>
<dd>First vector.</dd><dt>numbers <code class="lua">x2,y2</code></dt>
<dd>Second vector.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>numbers</dt>
<dd><code class="lua">x1*x2, y1*y2</code></dd></dl>
</div><div class="example">Example:<pre><code class="lua">x,y = vector.permul(x,y, 1,1.5)
</code></pre>
</div></div><div class="ref-block" id="hump.vector-lightdot"><h4>function <span class="name">dot</span><span class="arglist">(x1,y1, x2,y2)</span><a class="top" href="#hump.vector-light">^top</a></h4><p>Computes the <a href="http://en.wikipedia.org/wiki/Dot_product">dot product</a> of two
vectors: <code class="lua">x1*x2 + y1*y2</code>.</p>
<div class="arguments">Parameters:<dl>
<dt>numbers <code class="lua">x1,y1</code></dt>
<dd>First vector.</dd><dt>numbers <code class="lua">x2,y2</code></dt>
<dd>Second vector.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>number</dt>
<dd><code class="lua">x1*x2 + y1*y2</code></dd></dl>
</div><div class="example">Example:<pre><code class="lua">cosphi = vector.dot(rx,ry, vx,vy)
</code></pre>
</div></div><div class="ref-block" id="hump.vector-lightcross"><h4>function <span class="name">cross</span><span class="arglist">(x1,y1, x2,y2)</span><a class="top" href="#hump.vector-light">^top</a></h4><p>Computes the <a href="http://en.wikipedia.org/wiki/Cross_product">cross product</a> of two
vectors, <code class="lua">x1*y2 - y1*x2</code>.</p>
<div class="arguments">Parameters:<dl>
<dt>numbers <code class="lua">x1,y1</code></dt>
<dd>First vector.</dd><dt>numbers <code class="lua">x2,y2</code></dt>
<dd>Second vector.</dd></dl>
<dl>
<dt>numbers <code class="lua">x1,y1</code></dt>
<dd>First vector.</dd><dt>numbers <code class="lua">x2,y2</code></dt>
<dd>Second vector.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>number</dt>
<dd><code class="lua">x1*y2 - y1*x2</code></dd></dl>
<dl>
<dt>number</dt>
<dd><code class="lua">x1*y2 - y1*x2</code></dd></dl>
</div><div class="example">Examples:<pre><code class="lua">parallelogram_area = vector.cross(ax,ay, bx,by)
</code></pre>
<p>Alias to [<code class="lua">vector.cross(x1,y1, x2,y2)</code>].</p>
<pre><code class="lua">parallelogram_area = vector.det(ax,ay, bx,by)
</code></pre>
</div></div><div class="ref-block" id="hump.vector-lighteq"><h4>function <span class="name">eq</span><span class="arglist">(x1,y1, x2,y2)</span><a class="top" href="#hump.vector-light">^top</a></h4><p>Test for equality.</p>
<div class="arguments">Parameters:<dl>
<dt>numbers <code class="lua">x1,y1</code></dt>
<dd>First vector.</dd><dt>numbers <code class="lua">x2,y2</code></dt>
<dd>Second vector.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>boolean</dt>
<dd><code class="lua">x1 == x2 and y1 == y2</code></dd></dl>
</div><div class="example">Example:<pre><code class="lua">if vector.eq(x1,y1, x2,y2) then be.happy() end
</code></pre>
</div></div><div class="ref-block" id="hump.vector-lightle"><h4>function <span class="name">le</span><span class="arglist">(x1,y1, x2,y2)</span><a class="top" href="#hump.vector-light">^top</a></h4><p>Test for partial lexical order, <code class="lua">&lt;=</code>.</p>
<div class="arguments">Parameters:<dl>
<dt>numbers <code class="lua">x1,y1</code></dt>
<dd>First vector.</dd><dt>numbers <code class="lua">x2,y2</code></dt>
<dd>Second vector.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>boolean</dt>
<dd><code class="lua">x1 &lt;= x2 and y1 &lt;= y2</code></dd></dl>
</div><div class="example">Example:<pre><code class="lua">if vector.le(x1,y1, x2,y2) then be.happy() end
</code></pre>
</div></div><div class="ref-block" id="hump.vector-lightlt"><h4>function <span class="name">lt</span><span class="arglist">(x1,y1, x2,y2)</span><a class="top" href="#hump.vector-light">^top</a></h4><p>Test for strict lexical order, <code class="lua">&lt;</code>.</p>
<div class="arguments">Parameters:<dl>
<dt>numbers <code class="lua">x1,y1</code></dt>
<dd>First vector.</dd><dt>numbers <code class="lua">x2,y2</code></dt>
<dd>Second vector.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>boolean</dt>
<dd><code class="lua">x1 &lt; x2 or (x1 == x2) and y1 &lt;= y2</code></dd></dl>
</div><div class="example">Example:<pre><code class="lua">if vector.lt(x1,y1, x2,y2) then be.happy() end
</code></pre>
</div></div><div class="ref-block" id="hump.vector-lightlen"><h4>function <span class="name">len</span><span class="arglist">(x,y)</span><a class="top" href="#hump.vector-light">^top</a></h4><p>Get length of a vector, i.e. <code class="lua">math.sqrt(x*x + y*y)</code>.</p>
<div class="arguments">Parameters:<dl>
<dt>numbers <code class="lua">x,y</code></dt>
<dd>The vector.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>number</dt>
<dd>Length of the vector.</dd></dl>
</div><div class="example">Example:<pre><code class="lua">distance = vector.len(love.mouse.getPosition())
</code></pre>
</div></div><div class="ref-block" id="hump.vector-lightlen2"><h4>function <span class="name">len2</span><span class="arglist">(x,y)</span><a class="top" href="#hump.vector-light">^top</a></h4><p>Get squared length of a vector, i.e. <code class="lua">x*x + y*y</code>.</p>
<div class="arguments">Parameters:<dl>
<dt>numbers <code class="lua">x,y</code></dt>
<dd>The vector.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>number</dt>
<dd>Squared length of the vector.</dd></dl>
</div><div class="example">Example:<pre><code class="lua">-- get closest vertex to a given vector
closest, dsq = vertices[1], vector.len2(px-vertices[1].x, py-vertices[1].y)
for i = 2,#vertices do
local temp = vector.len2(px-vertices[i].x, py-vertices[i].y)
if temp &lt; dsq then
closest, dsq = vertices[i], temp
end
end
</code></pre>
</div></div><div class="ref-block" id="hump.vector-lightdist"><h4>function <span class="name">dist</span><span class="arglist">(x1,y1, x2,y2)</span><a class="top" href="#hump.vector-light">^top</a></h4><p>Get distance of two points. The same as <code class="lua">vector.len(x1-x2, y1-y2)</code>.</p>
<div class="arguments">Parameters:<dl>
<dt>numbers <code class="lua">x1,y1</code></dt>
<dd>First vector.</dd><dt>numbers <code class="lua">x2,y2</code></dt>
<dd>Second vector.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>number</dt>
<dd>The distance of the points.</dd></dl>
</div><div class="example">Example:<pre><code class="lua">-- get closest vertex to a given vector
-- slightly slower than the example using len2()
closest, dist = vertices[1], vector.dist(px,py, vertices[1].x,vertices[1].y)
for i = 2,#vertices do
local temp = vector.dist(px,py, vertices[i].x,vertices[i].y)
if temp &lt; dist then
closest, dist = vertices[i], temp
end
end
</code></pre>
</div></div><div class="ref-block" id="hump.vector-lightdist2"><h4>function <span class="name">dist2</span><span class="arglist">(x1,y1, x2,y2)</span><a class="top" href="#hump.vector-light">^top</a></h4><p>Get squared distance of two points. The same as <code class="lua">vector.len2(x1-x2, y1-y2)</code>.</p>
<div class="arguments">Parameters:<dl>
<dt>numbers <code class="lua">x1,y1</code></dt>
<dd>First vector.</dd><dt>numbers <code class="lua">x2,y2</code></dt>
<dd>Second vector.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>number</dt>
<dd>The squared distance of two points.</dd></dl>
</div><div class="example">Example:<pre><code class="lua">-- get closest vertex to a given vector
closest, dsq = vertices[1], vector.dist2(px,py, vertices[1].x,vertices[1].y)
for i = 2,#vertices do
local temp = vector.dist2(px,py, vertices[i].x,vertices[i].y)
if temp &lt; dsq then
closest, dsq = vertices[i], temp
end
end
</code></pre>
</div></div><div class="ref-block" id="hump.vector-lightnormalize"><h4>function <span class="name">normalize</span><span class="arglist">(x,y)</span><a class="top" href="#hump.vector-light">^top</a></h4><pre><code class="lua">Get normalized vector, i.e. a vector with the same direction as the input
vector, but with length 1.
</code></pre>
<div class="arguments">Parameters:<dl>
<dt>numbers <code class="lua">x,y</code></dt>
<dd>The vector.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>numbers</dt>
<dd>Vector with same direction as the input vector, but length 1.</dd></dl>
</div><div class="example">Example:<pre><code class="lua">dx,dy = vector.normalize(vx,vy)
</code></pre>
</div></div><div class="ref-block" id="hump.vector-lightrotate"><h4>function <span class="name">rotate</span><span class="arglist">(phi, x,y)</span><a class="top" href="#hump.vector-light">^top</a></h4><p>Get a rotated vector.</p>
<div class="arguments">Parameters:<dl>
<dt>number <code class="lua">phi</code></dt>
<dd>Rotation angle in radians.</dd><dt>numbers <code class="lua">x,y</code></dt>
<dd>The vector.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>numbers</dt>
<dd>The rotated vector</dd></dl>
</div><div class="example">Example:<pre><code class="lua">-- approximate a circle
circle = {}
for i = 1,30 do
local phi = 2 * math.pi * i / 30
circle[i*2-1], circle[i*2] = vector.rotate(phi, 0,1)
end
</code></pre>
</div></div><div class="ref-block" id="hump.vector-lightperpendicular"><h4>function <span class="name">perpendicular</span><span class="arglist">(x,y)</span><a class="top" href="#hump.vector-light">^top</a></h4><p>Quick rotation by 90°. The same (but faster) as <code class="lua">vector.rotate(math.pi/2, x,y)</code>.</p>
<div class="arguments">Parameters:<dl>
<dt>numbers <code class="lua">x,y</code></dt>
<dd>The vector.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>numbers</dt>
<dd>A vector perpendicular to the input vector</dd></dl>
</div><div class="example">Example:<pre><code class="lua">nx,ny = vector.normalize(vector.perpendicular(bx-ax, by-ay))
</code></pre>
</div></div><div class="ref-block" id="hump.vector-lightproject"><h4>function <span class="name">project</span><span class="arglist">(x,y, u,v)</span><a class="top" href="#hump.vector-light">^top</a></h4><p>Project vector onto another vector.</p>
<div class="arguments">Parameters:<dl>
<dt>numbers <code class="lua">x,y</code></dt>
<dd>The vector to project.</dd><dt>numbers <code class="lua">u,v</code></dt>
<dd>The vector to project onto.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>numbers</dt>
<dd>The projected vector.</dd></dl>
</div><div class="example">Example:<pre><code class="lua">vx_p,vy_p = vector.project(vx,vy, ax,ay)
</code></pre>
</div></div><div class="ref-block" id="hump.vector-lightmirror"><h4>function <span class="name">mirror</span><span class="arglist">(x,y, u,v)</span><a class="top" href="#hump.vector-light">^top</a></h4><p>Mirrors vector on the axis defined by the other vector.</p>
<div class="arguments">Parameters:<dl>
<dt>numbers <code class="lua">x,y</code></dt>
<dd>The vector to mirror.</dd><dt>numbers <code class="lua">u,v</code></dt>
<dd>The vector defining the axis.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>numbers</dt>
<dd>The mirrored vector.</dd></dl>
</div><div class="example">Example:<pre><code class="lua">vx,vy = vector.mirror(vx,vy, surface.x,surface.y)
</code></pre>
</div></div><div class="ref-block" id="hump.vector-lightangleTo"><h4>function <span class="name">angleTo</span><span class="arglist">(ox,y, u,v)</span><a class="top" href="#hump.vector-light">^top</a></h4><p>Measures the angle between two vectors. <code class="lua">u</code> and <code class="lua">v</code> default to <code class="lua">0</code> if omitted,
i.e. the function returns the angle to the coordinate system.</p>
<div class="arguments">Parameters:<dl>
<dt>numbers <code class="lua">x,y</code></dt>
<dd>Vector to measure the angle.</dd><dt>numbers <code class="lua">u,v</code> (optional)</dt>
<dd>Reference vector.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>number</dt>
<dd>Angle in radians.</dd></dl>
</div><div class="example">Example:<pre><code class="lua">lean = vector.angleTo(self.upx, self.upy, 0,1)
if lean &gt; .1 then self:fallOver() end
</code></pre>
</div></div></div><div class="outer-block" id="hump.class"><h3>hump.class<a class="top" href="#top">^top</a></h3><div class="preamble"><pre><code class="lua">Class = require "hump.class"
</code></pre>
<p>A small, fast class/prototype implementation with multiple inheritance.</p>
<p>Implements <a href="https://github.com/bartbes/Class-Commons">class commons</a>.</p>
<h4>Example:</h4>
<pre><code class="lua">Critter = Class{
init = function(self, pos, img)
self.pos = pos
self.img = img
end,
speed = 5
}
function Critter:update(dt, player)
-- see hump.vector
local dir = (player.pos - self.pos):normalize_inplace()
self.pos = self.pos + dir * Critter.speed * dt
end
function Critter:draw()
love.graphics.draw(self.img, self.pos.x, self.pos.y)
end
</code></pre>
</div><div class="overview"><h4>Module overview</h4><dl><dt><a href="#hump.classnew">new()</a></dt><dd>Declare a new class.</dd><dt><a href="#hump.classclass.init">class.init()</a></dt><dd>Call class constructor.</dd><dt><a href="#hump.classclass:include">class:include()</a></dt><dd>Explicit class inheritance/mixin support.</dd><dt><a href="#hump.classclass:clone">class:clone()</a></dt><dd>Clone class/prototype support.</dd><dt><a href="#hump.classCaveats">Caveats </a></dt><dd>Common gotchas.</dd></dl></div><div class="ref-block" id="hump.classnew"><h4>function <span class="name">new</span><span class="arglist">{init = constructor, __includes = parents, ...}</span><a class="top" href="#hump.class">^top</a></h4><p>Declare a new class.</p>
<p><code class="lua">init()</code> will receive the new object instance as first argument. Any other
arguments will also be forwarded (see examples), i.e. <code class="lua">init()</code> has the
following signature:</p>
<pre><code class="lua">function init(self, ...)
</code></pre>
<p>If you do not specify a constructor, an empty constructor will be used instead.</p>
<p>The name of the variable that holds the module can be used as a shortcut to
<code class="lua">new()</code> (see example).</p>
<div class="arguments">Parameters:<dl>
<dt>function <code class="lua">constructor</code> (optional)</dt>
<dd>Class constructor. Can be accessed with theclass.init(object, ...)</dd><dt>class <code class="lua">or table of classes parents</code> (optional)</dt>
<dd>Classes to inherit from. Can either be a single class or a table of classes</dd><dt>mixed <code class="lua">...</code> (optional)</dt>
<dd>Any other fields or methods common to all instances of this class.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>class</dt>
<dd>The class.</dd></dl>
</div><div class="example">Examples:<pre><code class="lua">Class = require 'hump.class' -- `Class' is now a shortcut to new()
-- define a class class
Feline = Class{
init = function(self, size, weight)
self.size = size
self.weight = weight
end;
-- define a method
stats = function(self)
return string.format("size: %.02f, weight: %.02f", self.size, self.weight)
end;
}
-- create two objects
garfield = Feline(.7, 45)
felix = Feline(.8, 12)
print("Garfield: " .. garfield:stats(), "Felix: " .. felix:stats())
</code></pre>
<pre><code class="lua">Class = require 'hump.class'
-- same as above, but with 'external' function definitions
Feline = Class{}
function Feline:init(size, weight)
self.size = size
self.weight = weight
end
function Feline:stats()
return string.format("size: %.02f, weight: %.02f", self.size, self.weight)
end
garfield = Feline(.7, 45)
print(Feline, garfield)
</code></pre>
<pre><code class="lua">Class = require 'hump.class'
A = Class{
foo = function() print('foo') end
}
B = Class{
bar = function() print('bar') end
}
-- single inheritance
C = Class{__includes = A}
instance = C()
instance:foo() -- prints 'foo'
instance:bar() -- error: function not defined
-- multiple inheritance
D = Class{__includes = {A,B}}
instance = D()
instance:foo() -- prints 'foo'
instance:bar() -- prints 'bar'
</code></pre>
<pre><code class="lua">-- class attributes are shared across instances
A = Class{ foo = 'foo' } -- foo is a class attribute/static member
one, two, three = A(), A(), A()
print(one.foo, two.foo, three.foo) --&gt; prints 'foo foo foo'
one.foo = 'bar' -- overwrite/specify for instance `one' only
print(one.foo, two.foo, three.foo) --&gt; prints 'bar foo foo'
A.foo = 'baz' -- overwrite for all instances without specification
print(one.foo, two.foo, three.foo) --&gt; prints 'bar baz baz'
</code></pre>
</div></div><div class="ref-block" id="hump.classclass.init"><h4>function <span class="name">class.init</span><span class="arglist">(object, ...)</span><a class="top" href="#hump.class">^top</a></h4><p>Calls class constructor of a class on an object.</p>
<p>Derived classes should use this function their constructors to initialize the
parent class(es) portions of the object.</p>
<div class="arguments">Parameters:<dl>
<dt>Object <code class="lua">object</code></dt>
<dd>The object. Usually <code class="lua">self</code>.</dd><dt>mixed <code class="lua">...</code></dt>
<dd>Arguments to pass to the constructor.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>mixed</dt>
<dd>Whatever the parent class constructor returns.</dd></dl>
</div><div class="example">Example:<pre><code class="lua">Class = require 'hump.class'
Shape = Class{
init = function(self, area)
self.area = area
end;
__tostring = function(self)
return "area = " .. self.area
end
}
Rectangle = Class{__includes = Shape,
init = function(self, width, height)
Shape.init(self, width * height)
self.width = width
self.height = height
end;
__tostring = function(self)
local strs = {
"width = " .. self.width,
"height = " .. self.height,
Shape.__tostring(self)
}
return table.concat(strs, ", ")
end
}
print( Rectangle(2,4) ) -- prints 'width = 2, height = 4, area = 8'
</code></pre>
</div></div><div class="ref-block" id="hump.classclass:include"><h4>function <span class="name">class:include</span><span class="arglist">(other)</span><a class="top" href="#hump.class">^top</a></h4><p>Inherit functions and variables of another class, but if they are not already
defined. This is done by (deeply) copying the functions and variables over to
the subclass.</p>
<p><strong>Note:</strong> <code class="lua">class:include()</code> doesn't actually care if the arguments supplied are
hump classes. Just any table will work.</p>
<p><strong>Note 2:</strong> You can use <code class="lua">Class.include(a, b)</code> to copy any fields from table <code class="lua">a</code>
to table <code class="lua">b</code> (see second example).</p>
<div class="arguments">Parameters:<dl>
<dt>tables <code class="lua">other</code></dt>
<dd>Parent classes/mixins.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>table</dt>
<dd>The class.</dd></dl>
</div><div class="example">Examples:<pre><code class="lua">Class = require 'hump.class'
Entity = Class{
init = function(self)
GameObjects.register(self)
end
}
Collidable = {
dispatch_collision = function(self, other, dx, dy)
if self.collision_handler[other.type])
return collision_handler[other.type](self, other, dx, dy)
end
return collision_handler["*"](self, other, dx, dy)
end,
collision_handler = {["*"] = function() end},
}
Spaceship = Class{
init = function(self)
self.type = "Spaceship"
-- ...
end
}
-- make Spaceship collidable
Spaceship:include(Collidable)
Spaceship.collision_handler["Spaceship"] = function(self, other, dx, dy)
-- ...
end
</code></pre>
<pre><code class="lua">-- using Class.include()
Class = require 'hump.class'
a = {
foo = 'bar',
bar = {one = 1, two = 2, three = 3},
baz = function() print('baz') end,
}
b = {
foo = 'nothing to see here...'
}
Class.include(b, a) -- copy values from a to b
-- note that neither a nor b are hump classes!
print(a.foo, b.foo) -- prints 'bar nothing to see here...'
b.baz() -- prints 'baz'
b.bar.one = 10 -- changes only values in b
print(a.bar.one, b.bar.one) -- prints '1 10'
</code></pre>
</div></div><div class="ref-block" id="hump.classclass:clone"><h4>function <span class="name">class:clone</span><span class="arglist">()</span><a class="top" href="#hump.class">^top</a></h4><p>Create a clone/deep copy of the class.</p>
<p><strong>Note:</strong> You can use <code class="lua">Class.clone(a)</code> to create a deep copy of any table
(see second example).</p>
<div class="arguments">Parameters:<dl><dt>None</dt></dl></div><div class="returns">Returns:<dl>
<dt>table</dt>
<dd>A deep copy of the class/table.</dd></dl>
</div><div class="example">Examples:<pre><code class="lua">Class = require 'hump.class'
point = Class{ x = 0, y = 0 }
a = point:clone()
a.x, a.y = 10, 10
print(a.x, a.y) --&gt; prints '10 10'
b = point:clone()
print(b.x, b.y) --&gt; prints '10 10'
</code></pre>
<pre><code class="lua">-- using Class.clone() to copy tables
Class = require 'hump.class'
a = {
foo = 'bar',
bar = {one = 1, two = 2, three = 3},
baz = function() print('baz') end,
}
b = Class.clone(a)
b.baz() -- prints 'baz'
b.bar.one = 10
print(a.bar.one, b.bar.one) -- prints '1 10'
</code></pre>
</div></div><div class="section-block" id="hump.classCaveats"><h4>Caveats <a class="top" href="#hump.class">^top</a></h4><p>Be careful when using metamethods like <code class="lua">__add</code> or <code class="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>
<p>Class = require 'hump.class'</p>
<pre><code class="lua">A = Class{init = function(self, x) self.x = x end}
function A:__add(other) return A(self.x + other.x) end
function A:show() print("A:", self.x) end
B = Class{init = function(self, x, y) A.init(self, x) self.y = y end}
function B:show() print("B:", self.x, self.y) end
function B:foo() print("foo") end
B:include(A)
one, two = B(1,2), B(3,4)
result = one + two -- result will be of type A, *not* B!
result:show() -- prints "A: 4"
result:foo() -- error: method does not exist
</code></pre>
<p>Note that while you can define the <code class="lua">__index</code> metamethod of the class, this is
not a good idea: It will break the class mechanism. To add a custom <code class="lua">__index</code>
metamethod without breaking the class system, you have to use <code class="lua">rawget()</code>. But
beware that this won't affect subclasses:</p>
<pre><code class="lua">Class = require 'hump.class'
A = Class{}
function A:foo() print('bar') end
function A:__index(key)
print(key)
return rawget(A, key)
end
instance = A()
instance:foo() -- prints foo bar
B = Class{__includes = A}
instance = B()
instance:foo() -- prints only foo
</code></pre>
</div></div><div class="outer-block" id="hump.signal"><h3>hump.signal<a class="top" href="#top">^top</a></h3><div class="preamble"><pre><code class="lua">Signals = require 'hump.signal'
</code></pre>
<p>A simple yet effective implementation of <a href="http://en.wikipedia.org/wiki/Signals_and_slots">Signals and
Slots</a>, also known as <a href="http://en.wikipedia.org/wiki/Observer_pattern">Observer
pattern</a>: Functions can be
dynamically bound to signals. When a <em>signal</em> is <em>emitted</em>, all registered
functions will be invoked. Simple as that.</p>
<p><code class="lua">hump.signal</code> makes things more interesing by allowing to emit all signals that
match a <a href="http://www.lua.org/manual/5.1/manual.html#5.4.1">Lua string pattern</a>.</p>
<h4>Example:</h4>
<pre><code class="lua">-- in AI.lua
signals.register('shoot', function(x,y, dx,dy)
-- for every critter in the path of the bullet:
-- try to avoid being hit
for critter in pairs(critters) do
if critter:intersectsRay(x,y, dx,dy) then
critter:setMoveDirection(-dy, dx)
end
end
end)
-- in sounds.lua
signals.register('shoot', function()
Sounds.fire_bullet:play()
end)
-- in main.lua
function love.keypressed(key)
if key == ' ' then
local x,y = player.pos:unpack()
local dx,dy = player.direction:unpack()
signals.emit('shoot', x,y, dx,dy)
end
end
</code></pre>
</div><div class="overview"><h4>Module overview</h4><dl><dt><a href="#hump.signalnew">new()</a></dt><dd>Create a new signal registry</dd><dt><a href="#hump.signalregister">register()</a></dt><dd>Register function with signal.</dd><dt><a href="#hump.signalemit">emit()</a></dt><dd>Call all functions bound to a signal.</dd><dt><a href="#hump.signalremove">remove()</a></dt><dd>Remove functions from registry. </dd><dt><a href="#hump.signalclear">clear()</a></dt><dd>Clears a signal registry.</dd><dt><a href="#hump.signalemit_pattern">emit_pattern()</a></dt><dd>Emits signals matching a pattern.</dd><dt><a href="#hump.signalremove_pattern">remove_pattern()</a></dt><dd>Remove functions from signals matching a pattern.</dd><dt><a href="#hump.signalclear_pattern">clear_pattern()</a></dt><dd>Clears signal registry matching a pattern.</dd></dl></div><div class="ref-block" id="hump.signalnew"><h4>function <span class="name">new</span><span class="arglist">()</span><a class="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.
<code class="lua">instance:emit("foo")</code>), while the global registry uses the dot-notation (e.g.
<code class="lua">Signal.emit("foo")</code>).</p>
<div class="arguments">Parameters:<dl><dt>None</dt></dl></div><div class="returns">Returns:<dl>
<dt>Registry</dt>
<dd>A new signal registry.</dd></dl>
</div><div class="example">Example:<pre><code class="lua">player.signals = Signals.new()
</code></pre>
</div></div><div class="ref-block" id="hump.signalregister"><h4>function <span class="name">register</span><span class="arglist">(s, f)</span><a class="top" href="#hump.signal">^top</a></h4><p>Registers a function <code class="lua">f</code> to be called when signal <code class="lua">s</code> is emitted.</p>
<div class="arguments">Parameters:<dl>
<dt>string <code class="lua">s</code></dt>
<dd>The signal identifier.</dd><dt>function <code class="lua">f</code></dt>
<dd>The function to register.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>function</dt>
<dd>A function handle to use in <a href="#hump.signalremove"><code class="lua">remove()</code></a>.</dd></dl>
</div><div class="example">Examples:<pre><code class="lua">Signal.register('level-complete', function() self.fanfare:play() end)
</code></pre>
<pre><code class="lua">handle = Signal.register('level-load', function(level) level.show_help() end)
</code></pre>
<pre><code class="lua">menu:register('key-left', select_previous_item)
</code></pre>
</div></div><div class="ref-block" id="hump.signalemit"><h4>function <span class="name">emit</span><span class="arglist">(s, ...)</span><a class="top" href="#hump.signal">^top</a></h4><p>Calls all functions bound to signal <code class="lua">s</code> with the supplied arguments.</p>
<div class="arguments">Parameters:<dl>
<dt>string <code class="lua">s</code></dt>
<dd>The signal identifier.</dd><dt>mixed <code class="lua">...</code> (optional)</dt>
<dd>Arguments to pass to the bound functions.</dd></dl>
</div><div class="returns">Returns:<dl><dt>Nothing</dt></dl></div><div class="example">Examples:<pre><code class="lua">function love.keypressed(key)
-- using a signal instance
if key == 'left' then menu:emit('key-left') end
end
</code></pre>
<pre><code class="lua">if level.is_finished() then
-- adding arguments
Signal.emit('level-load', level.next_level)
end
</code></pre>
</div></div><div class="ref-block" id="hump.signalremove"><h4>function <span class="name">remove</span><span class="arglist">(s, ...)</span><a class="top" href="#hump.signal">^top</a></h4><p>Unbinds (removes) functions from signal <code class="lua">s</code>.</p>
<div class="arguments">Parameters:<dl>
<dt>string <code class="lua">s</code></dt>
<dd>The signal identifier.</dd><dt>functions <code class="lua">...</code></dt>
<dd>Functions to unbind from the signal.</dd></dl>
</div><div class="returns">Returns:<dl><dt>Nothing</dt></dl></div><div class="example">Example:<pre><code class="lua">Signal.remove('level-load', handle)
</code></pre>
</div></div><div class="ref-block" id="hump.signalclear"><h4>function <span class="name">clear</span><span class="arglist">(s)</span><a class="top" href="#hump.signal">^top</a></h4><p>Removes all functions from signal <code class="lua">s</code>.</p>
<div class="arguments">Parameters:<dl>
<dt>string <code class="lua">s</code></dt>
<dd>The signal identifier.</dd></dl>
</div><div class="returns">Returns:<dl><dt>Nothing</dt></dl></div><div class="example">Example:<pre><code class="lua">Signal.clear('key-left')
</code></pre>
</div></div><div class="ref-block" id="hump.signalemit_pattern"><h4>function <span class="name">emit_pattern</span><span class="arglist">(p, ...)</span><a class="top" href="#hump.signal">^top</a></h4><p>Emits all signals matching a <a href="http://www.lua.org/manual/5.1/manual.html#5.4.1">string pattern</a>.</p>
<div class="arguments">Parameters:<dl>
<dt>string <code class="lua">p</code></dt>
<dd>The signal identifier pattern.</dd><dt>mixed <code class="lua">...</code> (optional)</dt>
<dd>Arguments to pass to the bound functions.</dd></dl>
</div><div class="returns">Returns:<dl><dt>Nothing</dt></dl></div><div class="example">Example:<pre><code class="lua">Signal.emit_pattern('^update%-.*', dt)
</code></pre>
</div></div><div class="ref-block" id="hump.signalremove_pattern"><h4>function <span class="name">remove_pattern</span><span class="arglist">(p, ...)</span><a class="top" href="#hump.signal">^top</a></h4><p>Removes functions from all signals matching a <a href="http://www.lua.org/manual/5.1/manual.html#5.4.1">string pattern</a>.</p>
<div class="arguments">Parameters:<dl>
<dt>string <code class="lua">p</code></dt>
<dd>The signal identifier pattern.</dd><dt>functions <code class="lua">...</code></dt>
<dd>Functions to unbind from the signals.</dd></dl>
</div><div class="returns">Returns:<dl><dt>Nothing</dt></dl></div><div class="example">Example:<pre><code class="lua">Signal.remove_pattern('key%-.*', play_click_sound)
</code></pre>
</div></div><div class="ref-block" id="hump.signalclear_pattern"><h4>function <span class="name">clear_pattern</span><span class="arglist">(p)</span><a class="top" href="#hump.signal">^top</a></h4><p>Removes <em>all</em> functions from all signals matching a <a href="http://www.lua.org/manual/5.1/manual.html#5.4.1">string pattern</a>.</p>
<div class="arguments">Parameters:<dl>
<dt>string <code class="lua">p</code></dt>
<dd>The signal identifier pattern.</dd></dl>
</div><div class="returns">Returns:<dl><dt>Nothing</dt></dl></div><div class="example">Examples:<pre><code class="lua">Signal.clear_pattern('sound%-.*')
</code></pre>
<pre><code class="lua">player.signals:clear_pattern('.*') -- clear all signals
</code></pre>
</div></div></div><div class="outer-block" id="hump.camera"><h3>hump.camera<a class="top" href="#top">^top</a></h3><div class="preamble"><pre><code class="lua">Camera = require "hump.camera"
</code></pre>
<p>A camera utility for LÖVE. A camera can "look" at a position. It can zoom in
and out and it can rotate it's view. In the background, this is done by
actually moving, scaling and rotating everything in the game world. But don't
worry about that.</p>
<h4>Example:</h4>
<pre><code class="lua">function love.load()
cam = Camera(player.pos.x, player.pos.y)
end
function love.update(dt)
local dx,dy = player.x - cam.x, player.y - cam.y
cam:move(dx/2, dy/2)
end
</code></pre>
</div><div class="overview"><h4>Module overview</h4><dl><dt><a href="#hump.cameranew">new()</a></dt><dd>Create a new camera.</dd><dt><a href="#hump.cameracamera:move">camera:move()</a></dt><dd>Move camera.</dd><dt><a href="#hump.cameracamera:lookAt">camera:lookAt()</a></dt><dd>Move camera to position.</dd><dt><a href="#hump.cameracamera:pos">camera:pos()</a></dt><dd>Get camera position.</dd><dt><a href="#hump.cameracamera:rotate">camera:rotate()</a></dt><dd>Rotate camera.</dd><dt><a href="#hump.cameracamera:rotateTo">camera:rotateTo()</a></dt><dd>Set camera rotation.</dd><dt><a href="#hump.cameracamera:zoom">camera:zoom()</a></dt><dd>Change zoom.</dd><dt><a href="#hump.cameracamera:zoomTo">camera:zoomTo()</a></dt><dd>Set zoom.</dd><dt><a href="#hump.cameracamera:attach">camera:attach()</a></dt><dd>Attach camera.</dd><dt><a href="#hump.cameracamera:detach">camera:detach()</a></dt><dd>Detach camera.</dd><dt><a href="#hump.cameracamera:draw">camera:draw()</a></dt><dd>Attach, draw, then detach.</dd><dt><a href="#hump.cameracamera:worldCoords">camera:worldCoords()</a></dt><dd>Convert point to world coordinates.</dd><dt><a href="#hump.cameracamera:cameraCoords">camera:cameraCoords()</a></dt><dd>Convert point to camera coordinates.</dd><dt><a href="#hump.cameracamera:mousepos">camera:mousepos()</a></dt><dd>Get mouse position in world coordinates.</dd></dl></div><div class="ref-block" id="hump.cameranew"><h4>function <span class="name">new</span><span class="arglist">(x,y, zoom, rot)</span><a class="top" href="#hump.camera">^top</a></h4><p>Creates a new camera. You can access the camera position using <code class="lua">camera.x,
camera.y</code>, the zoom using <code class="lua">camera.scale</code> and the rotation using <code class="lua">camera.rot</code>.</p>
<p>The module variable name can be used at a shortcut to <code class="lua">new()</code>.</p>
<div class="arguments">Parameters:<dl>
<dt>numbers <code class="lua">x,y</code> (optional)</dt>
<dd>Point for the camera to look at.</dd><dt>number <code class="lua">zoom</code> (optional)</dt>
<dd>Camera zoom.</dd><dt>number <code class="lua">rot</code> (optional)</dt>
<dd>Camera rotation in radians.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>camera</dt>
<dd>A new camera.</dd></dl>
</div><div class="example">Example:<pre><code class="lua">camera = require 'hump.camera'
-- camera looking at (100,100) with zoom 2 and rotated by 45 degrees
cam = camera(100,100, 2, math.pi/2)
</code></pre>
</div></div><div class="ref-block" id="hump.cameracamera:move"><h4>function <span class="name">camera:move</span><span class="arglist">(dx,dy)</span><a class="top" href="#hump.camera">^top</a></h4><p>Move the camera <em>by</em> some vector. To set the position, use
<a href="#hump.cameralookAt"><code class="lua">camera:lookAt(x,y)</code></a>.</p>
<p>This function is shortcut to camera.x,camera.y = camera.x+dx, camera.y+dy.</p>
<div class="arguments">Parameters:<dl>
<dt>numbers <code class="lua">dx,dy</code></dt>
<dd>Direction to move the camera.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>camera</dt>
<dd>The camera.</dd></dl>
</div><div class="example">Examples:<pre><code class="lua">function love.update(dt)
camera:move(dt * 5, dt * 6)
end
</code></pre>
<pre><code class="lua">function love.update(dt)
camera:move(dt * 5, dt * 6):rotate(dt)
end
</code></pre>
</div></div><div class="ref-block" id="hump.cameracamera:lookAt"><h4>function <span class="name">camera:lookAt</span><span class="arglist">(x,y)</span><a class="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 <a href="#hump.cameramove"><code class="lua">camera:move(x,y)</code></a>.</p>
<p>This function is shortcut to <code class="lua">camera.x,camera.y = x, y</code>.</p>
<div class="arguments">Parameters:<dl>
<dt>numbers <code class="lua">x,y</code></dt>
<dd>Position to look at.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>camera</dt>
<dd>The camera.</dd></dl>
</div><div class="example">Examples:<pre><code class="lua">function love.update(dt)
camera:lookAt(player.pos:unpack())
end
</code></pre>
<pre><code class="lua">function love.update(dt)
camera:lookAt(player.pos:unpack()):rotation(player.rot)
end
</code></pre>
</div></div><div class="ref-block" id="hump.cameracamera:pos"><h4>function <span class="name">camera:pos</span><span class="arglist">()</span><a class="top" href="#hump.camera">^top</a></h4><p>Returns <code class="lua">camera.x, camera.y</code>.</p>
<div class="arguments">Parameters:<dl><dt>None</dt></dl></div><div class="returns">Returns:<dl>
<dt>numbers</dt>
<dd>Camera position.</dd></dl>
</div><div class="example">Example:<pre><code class="lua">-- let the camera fly!
local cam_dx, cam_dy = 0, 0
function love.mousereleased(x,y)
local cx,cy = camera:position()
dx, dy = x-cx, y-cy
end
function love.update(dt)
camera:move(dx * dt, dy * dt)
end
</code></pre>
</div></div><div class="ref-block" id="hump.cameracamera:rotate"><h4>function <span class="name">camera:rotate</span><span class="arglist">(angle)</span><a class="top" href="#hump.camera">^top</a></h4><p>Rotate the camera by some angle. To set the angle use <code class="lua">camera.rot = new_angle</code>.</p>
<p>This function is shortcut to <code class="lua">camera.rot = camera.rot + angle</code>.</p>
<div class="arguments">Parameters:<dl>
<dt>number <code class="lua">angle</code></dt>
<dd>Rotation angle in radians</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>camera</dt>
<dd>The camera.</dd></dl>
</div><div class="example">Examples:<pre><code class="lua">function love.update(dt)
camera:rotate(dt)
end
</code></pre>
<pre><code class="lua">function love.update(dt)
camera:rotate(dt):move(dt,dt)
end
</code></pre>
</div></div><div class="ref-block" id="hump.cameracamera:rotateTo"><h4>function <span class="name">camera:rotateTo</span><span class="arglist">(angle)</span><a class="top" href="#hump.camera">^top</a></h4><p>Set rotation: <code class="lua">camera.rot = angle</code>.</p>
<div class="arguments">Parameters:<dl>
<dt>number <code class="lua">angle</code></dt>
<dd>Rotation angle in radians</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>number</dt>
<dd>The camera.</dd></dl>
</div><div class="example">Example:<pre><code class="lua">camera:rotateTo(math.pi/2)
</code></pre>
</div></div><div class="ref-block" id="hump.cameracamera:zoom"><h4>function <span class="name">camera:zoom</span><span class="arglist">(mul)</span><a class="top" href="#hump.camera">^top</a></h4><p><em>Multiply</em> zoom: <code class="lua">camera.scale = camera.scale * mul</code>.</p>
<div class="arguments">Parameters:<dl>
<dt>number <code class="lua">mul</code></dt>
<dd>Zoom change. Should be > 0.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>number</dt>
<dd>The camera.</dd></dl>
</div><div class="example">Examples:<pre><code class="lua">camera:zoom(2) -- make everything twice as big
</code></pre>
<pre><code class="lua">camera:zoom(0.5) -- ... and back to normal
</code></pre>
<pre><code class="lua">camera:zoom(-1) -- flip everything
</code></pre>
</div></div><div class="ref-block" id="hump.cameracamera:zoomTo"><h4>function <span class="name">camera:zoomTo</span><span class="arglist">(zoom)</span><a class="top" href="#hump.camera">^top</a></h4><p>Set zoom: <code class="lua">camera.scale = zoom</code>.</p>
<div class="arguments">Parameters:<dl>
<dt>number <code class="lua">zoom</code></dt>
<dd>New zoom.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>number</dt>
<dd>The camera.</dd></dl>
</div><div class="example">Example:<pre><code class="lua">camera:zoomTo(1)
</code></pre>
</div></div><div class="ref-block" id="hump.cameracamera:attach"><h4>function <span class="name">camera:attach</span><span class="arglist">()</span><a class="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
<code class="lua">camera:detach()</code> as if looking through the camera.</p>
<div class="arguments">Parameters:<dl><dt>None</dt></dl></div><div class="returns">Returns:<dl><dt>Nothing</dt></dl></div><div class="example">Example:<pre><code class="lua">function love.draw()
camera:attach()
draw_world()
cam:detach()
draw_hud()
end
</code></pre>
</div></div><div class="ref-block" id="hump.cameracamera:detach"><h4>function <span class="name">camera:detach</span><span class="arglist">()</span><a class="top" href="#hump.camera">^top</a></h4><p>Stop looking through the camera.</p>
<div class="arguments">Parameters:<dl><dt>None</dt></dl></div><div class="returns">Returns:<dl><dt>Nothing</dt></dl></div><div class="example">Example:<pre><code class="lua">function love.draw()
camera:attach()
draw_world()
cam:detach()
draw_hud()
end
</code></pre>
</div></div><div class="ref-block" id="hump.cameracamera:draw"><h4>function <span class="name">camera:draw</span><span class="arglist">(func)</span><a class="top" href="#hump.camera">^top</a></h4><p>Wrap a function between a <code class="lua">camera:attach()/camera:detach()</code> pair:</p>
<pre><code class="lua">cam:attach()
func()
cam:detach()
</code></pre>
<div class="arguments">Parameters:<dl>
<dt>function <code class="lua">func</code></dt>
<dd>Drawing function to be wrapped.</dd></dl>
</div><div class="returns">Returns:<dl><dt>Nothing</dt></dl></div><div class="example">Example:<pre><code class="lua">function love.draw()
camera:draw(draw_world)
draw_hud()
end
</code></pre>
</div></div><div class="ref-block" id="hump.cameracamera:worldCoords"><h4>function <span class="name">camera:worldCoords</span><span class="arglist">(x, y)</span><a class="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><code class="lua">camera:worldCoords(x,y)</code> and <code class="lua">camera:cameraCoords(x,y)</code> transform a point
between these two coordinate systems.</p>
<div class="arguments">Parameters:<dl>
<dt>numbers <code class="lua">x, y</code></dt>
<dd>Point to transform.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>numbers</dt>
<dd>Transformed point.</dd></dl>
</div><div class="example">Example:<pre><code class="lua">x,y = camera:worldCoords(love.mouse.getPosition())
selectedUnit:plotPath(x,y)
</code></pre>
</div></div><div class="ref-block" id="hump.cameracamera:cameraCoords"><h4>function <span class="name">camera:cameraCoords</span><span class="arglist">(x, y)</span><a class="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><code class="lua">camera:worldCoords(x,y)</code> and <code class="lua">camera:cameraCoords(x,y)</code> transform a point
between these two coordinate systems.</p>
<div class="arguments">Parameters:<dl>
<dt>numbers <code class="lua">x, y</code></dt>
<dd>Point to transform.</dd></dl>
</div><div class="returns">Returns:<dl>
<dt>numbers</dt>
<dd>Transformed point.</dd></dl>
</div><div class="example">Example:<pre><code class="lua">x,y = cam:cameraCoords(player.pos)
love.graphics.line(x, y, love.mouse.getPosition())
</code></pre>
</div></div><div class="ref-block" id="hump.cameracamera:mousepos"><h4>function <span class="name">camera:mousepos</span><span class="arglist">()</span><a class="top" href="#hump.camera">^top</a></h4><p>Shortcut to <code class="lua">camera:worldCoords(love.mouse.getPosition())</code>.</p>
<div class="arguments">Parameters:<dl><dt>None</dt></dl></div><div class="returns">Returns:<dl>
<dt>numbers</dt>
<dd>Mouse position in world coordinates.</dd></dl>
</div><div class="example">Example:<pre><code class="lua">x,y = camera:mousepos()
selectedUnit:plotPath(x,y)
</code></pre>
</div></div></div><div class="outer-block" id="License"><h3>License<a class="top" href="#top">^top</a></h3><div class="preamble"><p>Yay, <em>free software</em></p>
<blockquote><p>Copyright (c) 2010-2012 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><div class="outer-block" id="Download"><h3>Download<a class="top" href="#top">^top</a></h3><div class="preamble"><p>You can view and download the individual modules on github: <a href="http://github.com/vrld/hump">vrld/hump</a>
You may also download the whole packed sourcecode either in
<a href="http://github.com/vrld/hump/zipball/master">zip</a> or
<a href="http://github.com/vrld/hump/tarball/master">tar</a> formats.</p>
<p>Using <a href="http://git-scm.com">Git</a>, you can clone the project by running:</p>
<pre><code class="lua">git clone git://github.com/vrld/hump
</code></pre>
<p>Once done, tou can check for updates by running</p>
<pre><code class="lua">git pull
</code></pre>
</div></div></body></html>
Reference in New Issue View Git Blame Copy Permalink