Reuh/ubiquitousse
1
0
Fork 0
mirror of https://github.com/Reuh/ubiquitousse.git synced 2025-10-27 09:09:30 +00:00
Code Releases Activity
ubiquitousse/docs/modules/input.html

1730 lines
48 KiB
HTML
Raw Permalink Blame History

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<head>
<title>Ubiquitousse reference</title>
<link rel="stylesheet" href="../ldoc_new.css" type="text/css" />
</head>
<body>
<div id="container">
<div id="product">
<div id="product_logo"></div>
<div id="product_name"><big><b></b></big></div>
<div id="product_description"></div>
</div> <!-- id="product" -->
<div id="main">
<!-- Menu -->
<div id="navigation">
<br/>
<h1>Ubiquitousse</h1>
<ul>
<li><a href="../index.html">Index</a></li>
</ul>
<h2>Contents</h2>
<ul>
<li><a href="#Functions">Functions</a></li>
<li><a href="#Input_expressions">Input expressions </a></li>
<li><a href="#Input_objects">Input objects </a></li>
<li><a href="#Input_sources">Input sources </a></li>
</ul>
<h2>Modules</h2>
<ul class="nowrap">
<li><a href="../modules/ubiquitousse.html">ubiquitousse</a></li>
<li><a href="../modules/asset.html">asset</a></li>
<li><a href="../modules/ecs.html">ecs</a></li>
<li><strong>input</strong></li>
<li><a href="../modules/ldtk.html">ldtk</a></li>
<li><a href="../modules/scene.html">scene</a></li>
<li><a href="../modules/signal.html">signal</a></li>
<li><a href="../modules/timer.html">timer</a></li>
<li><a href="../modules/util.html">util</a></li>
</ul>
<h2>Topics</h2>
<ul class="">
<li><a href="../topics/README.md.html">README</a></li>
<li><a href="../topics/LICENSE.html">LICENSE</a></li>
</ul>
</div>
<div id="content">
<h1>Module <code>input</code></h1>
<p>Input management facilities.</p>
<p>The module returns a single function, <a href="../modules/input.html#">input</a>.</p>
<p>You can find in the module <code>uqt.input.default</code> (in file <code>input/default.lua</code>) some common input configuration for
2D movement, confirmation and cancellation (for both keyboard and joystick). Feel free to
use them as-is, or as a base for your own inputs.</p>
<p><strong>Requires</strong> ubiquitousse.signal.</p>
<h3>Usage:</h3>
<ul>
<pre class="example">local input = require(&quot;ubiquitousse.input&quot;)
-- Joystick-only control for player 1
local player1 = {
move = {
-- 2D movement, clamped on a circle
&quot;clamped(child.right - child.left, child.down - child.up)&quot;,
dimension = 2,
-- All the directions we can go, using both the left joystick and the D-pad
right = { &quot;axis.leftx.p&quot;, &quot;button.dpright&quot; },
left = { &quot;axis.leftx.n&quot;, &quot;button.dpleft&quot; },
down = { &quot;axis.lefty.p&quot;, &quot;button.dpdown&quot; },
up = { &quot;axis.lefty.n&quot;, &quot;button.dpup&quot; }
},
fire = { &quot;button.a&quot; }
}
-- Only consider inputs from the first joystick (in practice you will want to check if the joystick exists before running this line)
player1:setJoystick(love.joystick.getJoysticks()[1])
-- Player 2, using a second gamepad!
local player2 = player1:clone()
player2:setJoystick(love.joystick.getJoysticks()[2])
-- Define input callbacks.
player1.fire.event:bind(&quot;pressed&quot;, function() print(&quot;player 1 starts firing!&quot;) end)
player1.fire.event:bind(&quot;released&quot;, function() print(&quot;player 1 stop firing...&quot;) end)
function love.update()
-- Get player 1&apos;s 2D movement
local x, y = player1.move:value()
movePlayer1(x, y)
-- Check current state of the firing input
if player1.fire:down() then
-- currently firing!
end
-- Update inputs.
player1:update()
player2:update()
end
</pre>
</ul>
<h2><a href="#Functions">Functions</a></h2>
<table class="function_list">
<tr>
<td class="name" nowrap><a href="#input">input ([config])</a></td>
<td class="summary">Make a new input object.</td>
</tr>
</table>
<h2><a href="#Input_expressions">Input expressions </a></h2>
<table class="function_list">
<tr>
<td class="name" nowrap><a href="#floor">floor (x)</a></td>
<td class="summary">Same as Lua&rsquo;s <a href="https://www.lua.org/manual/5.1/manual.html#pdf-math.floor">math.floor</a>.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#floor">floor (x)</a></td>
<td class="summary">Same as Lua&rsquo;s <a href="https://www.lua.org/manual/5.1/manual.html#pdf-math.ceil">math.ceil</a>.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#floor">floor (x)</a></td>
<td class="summary">Same as Lua&rsquo;s <a href="https://www.lua.org/manual/5.1/manual.html#pdf-math.abs">math.abs</a>.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#clamp">clamp (x, xmin, xmax)</a></td>
<td class="summary">Clamp x between xmin and xmax.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#min">min (x, y, ...)</a></td>
<td class="summary">Returns the minimal value among all parameters.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#max">max (x, y, ...)</a></td>
<td class="summary">Returns the maximal value among all parameters.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#deadzone">deadzone (x, deadzone)</a></td>
<td class="summary">If x &lt; deadzone, returns 0; otherwise returns the value.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#normalize">normalize (x, y)</a></td>
<td class="summary">Returns a normalized version of the vector (x,y), i.e.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#passive">passive (source)</a></td>
<td class="summary">Mark an input source as passive.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#passive">passive (source)</a></td>
<td class="summary">Mark an input source as active.</td>
</tr>
</table>
<h2><a href="#Input_objects">Input objects </a></h2>
<table class="function_list">
<tr>
<td class="name" nowrap><a href="#Input.config">Input.config</a></td>
<td class="summary">Input configuration table.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#Input.children">Input.children <sup><em>[read-only]</em></sup></a></td>
<td class="summary">List and map of children <a href="../modules/input.html#Input_objects">Input</a>s.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#Input.name">Input.name <sup><em>[read-only]</em></sup></a></td>
<td class="summary">Name of the input.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#Input.enabled">Input.enabled <sup><em>[read-only]</em></sup></a></td>
<td class="summary"><code>false</code> if the input is disabled, <code>true</code> otherwise.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#Input.grabbed">Input.grabbed <sup><em>[read-only]</em></sup></a></td>
<td class="summary"><code>false</code> if the input is currently not grabbed, the grabbing <a href="../modules/input.html#Input_objects">Input</a> otherwise.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#Input.grabbing">Input.grabbing <sup><em>[read-only]</em></sup></a></td>
<td class="summary"><code>false</code> if the input is not grabbing another input, the <a href="../modules/input.html#Input_objects">Input</a> it is grabbing from otherwise.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#Input.event">Input.event</a></td>
<td class="summary">Input event registry.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#Input:update">Input:update ()</a></td>
<td class="summary">Update the input and its children.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#Input:clone">Input:clone ([copyState=false])</a></td>
<td class="summary">Create a new input object based on this input <a href="../modules/input.html#Input.config">config</a> data.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#Input:reload">Input:reload ()</a></td>
<td class="summary">Reload the input <a href="../modules/input.html#Input.config">config</a>, and do the same for its children.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#Input:disable">Input:disable ()</a></td>
<td class="summary">Disable the input and its children, preventing further updates and events.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#Input:enable">Input:enable ()</a></td>
<td class="summary">Enable the input and its children, allowing further updates and events.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#Input:onNextActiveSource">Input:onNextActiveSource (fn[, filter])</a></td>
<td class="summary">Will call <code>fn(source)</code> on the next activated source (including sources not currently used by this input).</td>
</tr>
<tr>
<td class="name" nowrap><a href="#Input:grab">Input:grab ()</a></td>
<td class="summary">Grab the input and its children and returns the resulting grabbing input.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#Input:release">Input:release ()</a></td>
<td class="summary">Release an input that is currently grabbing another and its children.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#Input:neutralize">Input:neutralize ()</a></td>
<td class="summary">Set the state of this input and its children to a neutral position (i.e.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#Input:set">Input:set (...)</a></td>
<td class="summary">Manually set the state of this input.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#Input:setJoystick">Input:setJoystick (joystick)</a></td>
<td class="summary">Set the joystick associated with this input.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#Input:getJoystick">Input:getJoystick ()</a></td>
<td class="summary">Returns the currently selected joystick.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#Input:down">Input:down ()</a></td>
<td class="summary">Returns <code>true</code> if the input is currently down, <code>false</code> otherwise.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#Input:pressed">Input:pressed ()</a></td>
<td class="summary">Returns <code>true</code> if the input has just been pressed, <code>false</code> otherwise.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#Input:released">Input:released ()</a></td>
<td class="summary">Returns <code>true</code> if the input has just been released, <code>false</code> otherwise.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#Input:value">Input:value ()</a></td>
<td class="summary">Returns the current value of the input.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#Input:delta">Input:delta ()</a></td>
<td class="summary">Returns the delta value of the input since the last call to <a href="../modules/input.html#Input:update">update</a>.</td>
</tr>
</table>
<h2><a href="#Input_sources">Input sources </a></h2>
<table class="function_list">
<tr>
<td class="name" nowrap><a href="#key.X">key.X</a></td>
<td class="summary">Keyboard input: 1 if the key X is down, 0 otherwise.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#scancode.X">scancode.X</a></td>
<td class="summary">Keyboard input: 1 if the key with scancode X is down, 0 otherwise.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#text.X">text.X</a></td>
<td class="summary">Text input: 1 if the text X was entered, 0 otherwise.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#mouse">mouse</a></td>
<td class="summary">Mouse input: <code>mouse[N]</code> is 1 if the mouse button is down, 0 otherwise.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#mouse.x">mouse.x</a></td>
<td class="summary">Mouse input: X position of the mouse cursor in the game window.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#mouse.y">mouse.y</a></td>
<td class="summary">Mouse input: Y position of the mouse cursor in the game window.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#mouse.dx">mouse.dx</a></td>
<td class="summary">Mouse input: latest X movement of the mouse cursor.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#mouse.dy">mouse.dy</a></td>
<td class="summary">Mouse input: latest Y movement of the mouse cursor.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#wheel.dx">wheel.dx</a></td>
<td class="summary">Mouse input: latest X movement of the mouse wheel.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#wheel.dy">wheel.dy</a></td>
<td class="summary">Mouse input: latest Y movement of the mouse wheel.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#button.X">button.X</a></td>
<td class="summary">Gamepad input: 1 if the button X is down, 0 otherwise.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#axis.X">axis.X</a></td>
<td class="summary">Gamepad input: current value of the gamepad axis (between -1 and 1).</td>
</tr>
<tr>
<td class="name" nowrap><a href="#dt">dt</a></td>
<td class="summary">On new frame: current delta time value since last frame.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#child.X">child.X</a></td>
<td class="summary">Children inputs: current value of a child input of the current input.</td>
</tr>
<tr>
<td class="name" nowrap><a href="#value">value</a></td>
<td class="summary">Current input: current value of the current input.</td>
</tr>
</table>
<br/>
<br/>
<h2 class="section-header "><a name="Functions"></a>Functions</h2>
<dl class="function">
<dt>
<a name = "input"></a>
<strong>input ([config])</strong>
</dt>
<dd>
Make a new input object. </p>
<p> This constructor is returned by the <code>uqt.input</code> module.
</ul>
</ul>
</ul>
</ul>
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">config</span>
<span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
input configuration table, see <a href="../modules/input.html#Input.config">Input.config</a>
(<em>optional</em>)
</li>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><a class="type" href="../modules/input.html#Input_objects">Input</a></span>
Input object
</ol>
<h3>Usage:</h3>
<ul>
<pre class="example"><span class="keyword">local</span> player = uqt.input {
fire = { <span class="string">"key.a"</span> },
jump = { <span class="string">"key.space"</span> }
}
player.fire.event:bind(<span class="string">"pressed"</span>, <span class="keyword">function</span>() <span class="global">print</span>(<span class="string">"pew pew"</span>) <span class="keyword">end</span>)</pre>
</ul>
</dd>
</dl>
<h2 class="section-header has-description"><a name="Input_expressions"></a>Input expressions </h2>
<div class="section-description">
Each <a href="../modules/input.html#Input_objects">Input</a> is associated with a list of <em>input expressions</em>.</p>
<p> An input expression is a <a href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a> representing a valid Lua expression.
These Lua expressions are used to compute the values returned by the input.
An input expression should returns as many values as the dimension of its input.</p>
<p> When referring to a variable in an expression, it will be interpreted as an <em>input source</em>.
An input source is where the initial input data comes from: for example, an input source could be the current state of
the Q key: <code>&quot;key.q&quot;</code> (=1 when the key is down, 0 otherwise).
See <a href="#Input_sources">sources</a> for details on how to define sources and built-in sources.</p>
<p> When a source that is present is the expression is updated, the input will be automatically updated in a reactive way, unless
the input is <em>passive</em> &ndash; that is, it can not trigger input update.</p>
<p> Additionally, you can also define your own variables to be used in input expression by giving arguments.</p>
<p> In input expression, you have no access to the Lua standard library; some other, more specific functions are available instead
and described below.
</div>
<h3>Usage:</h3>
<pre class="example"> <span class="comment">-- Example input configs for various input expression features.
</span> fire = {
<span class="comment">-- Basic input expression: 1 when Q is pressed, 0 otherwise. Will automatically update when Q is pressed.
</span> <span class="string">"key.q"</span>,
<span class="comment">-- Example using two inputs sources: when either A or Q is pressed, this will update, and returns 1 is at least one of them is pressed.
</span> <span class="string">"max(key.q, key.a)"</span>,
<span class="comment">-- This input has two input expression: it will be updated when either of them is updated and keep the value of the expression that was updated last.
</span> }
horizontal = {
<span class="comment">-- Another example, typically used to define an input for horizontal movement: returns 1 when pressing only right, -1 when pressing only left, and 0 otherwise.
</span> <span class="string">"key.right - key.left"</span>,
}
arguments = {
<span class="comment">-- You can give arguments to an expression by wrapping the expression in a table containing the arguments.
</span> { <span class="string">"axis.leftx + offset"</span>, offset = <span class="number">1</span> }
}
passive = {
<span class="comment">-- Same as the example above, but this will only update when Q is pressed - pressing A will not update the input on its own.
</span> <span class="comment">-- Passive input are typically used for modifiers keys (shift, alt, etc.) that should not trigger an update when pressed on their own.
</span> <span class="string">"max(key.q, passive(key.a))"</span>
}
dimension = {
<span class="comment">-- A two-dimensional input should have input expressions that return two values.
</span> <span class="comment">-- Here a common example that could be used to move something in 2D.
</span> <span class="string">"key.right - key.left, key.down - key.up"</span>,
dimension = <span class="number">2</span>
}
mouse = {
<span class="comment">-- Example input that returns the position of the mouse cursor, that can be controlled both using an actual mouse or
</span> <span class="comment">-- through a joystick.
</span> dimension = <span class="number">2</span>,
<span class="string">"mouse.x, mouse.y"</span>,
{ <span class="string">"value[1] + axis.leftx * speed * dt, value[2] + axis.lefty * speed * dt"</span>, speed = <span class="number">300</span> } <span class="comment">-- contains dt, so updated only once per frame. Thus speed here is the speed in pixel/second, as expected.
</span> }
mouse = {
<span class="comment">-- A special case: if the <a href="../modules/input.html#dt">dt</a> source is present in an expression, it will make every other input source passive by default in the expression.
</span> <span class="comment">-- This is the case since <a href="../modules/input.html#dt">dt</a> will trigger an update every frame, and is therefore mostly relevant for input that is used once per frame only
</span> <span class="comment">-- (while other input sources might cause the input to update several times per frame).
</span> <span class="string">"axis.leftx * dt"</span>
}
child = {
<span class="comment">-- Children input can be used as input sources using the <code>child.name</code> syntax.
</span> <span class="comment">-- If the children input has more than one dimension, you will need to specify it using a numeric index like <code>child.fire[2]</code> (for the dimension 2 of the child).
</span> <span class="string">"child.fire"</span>,
fire = { <span class="string">"key.q"</span> }
}</pre>
<dl class="function">
<dt>
<a name = "floor"></a>
<strong>floor (x)</strong>
</dt>
<dd>
Same as Lua&rsquo;s <a href="https://www.lua.org/manual/5.1/manual.html#pdf-math.floor">math.floor</a>.
</ul>
</ul>
</ul>
</ul>
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">x</span>
<span class="types"><span class="type">number</span></span>
number to round
</li>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">number</span></span>
floored value
</ol>
</dd>
<dt>
<a name = "floor"></a>
<strong>floor (x)</strong>
</dt>
<dd>
Same as Lua&rsquo;s <a href="https://www.lua.org/manual/5.1/manual.html#pdf-math.ceil">math.ceil</a>.
</ul>
</ul>
</ul>
</ul>
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">x</span>
<span class="types"><span class="type">number</span></span>
number to round
</li>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">number</span></span>
ceiled value
</ol>
</dd>
<dt>
<a name = "floor"></a>
<strong>floor (x)</strong>
</dt>
<dd>
Same as Lua&rsquo;s <a href="https://www.lua.org/manual/5.1/manual.html#pdf-math.abs">math.abs</a>.
</ul>
</ul>
</ul>
</ul>
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">x</span>
<span class="types"><span class="type">number</span></span>
number to absolute
</li>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">number</span></span>
absolute value
</ol>
</dd>
<dt>
<a name = "clamp"></a>
<strong>clamp (x, xmin, xmax)</strong>
</dt>
<dd>
Clamp x between xmin and xmax.
</ul>
</ul>
</ul>
</ul>
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">x</span>
<span class="types"><span class="type">number</span></span>
number clamp
</li>
<li><span class="parameter">xmin</span>
<span class="types"><span class="type">number</span></span>
minimal value
</li>
<li><span class="parameter">xmax</span>
<span class="types"><span class="type">number</span></span>
maximal value
</li>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">number</span></span>
clamped value
</ol>
</dd>
<dt>
<a name = "min"></a>
<strong>min (x, y, ...)</strong>
</dt>
<dd>
Returns the minimal value among all parameters.
</ul>
</ul>
</ul>
</ul>
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">x</span>
<span class="types"><span class="type">number</span></span>
first value
</li>
<li><span class="parameter">y</span>
<span class="types"><span class="type">number</span></span>
second value
</li>
<li><span class="parameter">...</span>
<span class="types"><span class="type">number</span></span>
other values
</li>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">number</span></span>
smallest value among the arguments
</ol>
</dd>
<dt>
<a name = "max"></a>
<strong>max (x, y, ...)</strong>
</dt>
<dd>
Returns the maximal value among all parameters.
</ul>
</ul>
</ul>
</ul>
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">x</span>
<span class="types"><span class="type">number</span></span>
first value
</li>
<li><span class="parameter">y</span>
<span class="types"><span class="type">number</span></span>
second value
</li>
<li><span class="parameter">...</span>
<span class="types"><span class="type">number</span></span>
other values
</li>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">number</span></span>
biggest value among the arguments
</ol>
</dd>
<dt>
<a name = "deadzone"></a>
<strong>deadzone (x, deadzone)</strong>
</dt>
<dd>
If x &lt; deadzone, returns 0; otherwise returns the value.
</ul>
</ul>
</ul>
</ul>
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">x</span>
<span class="types"><span class="type">number</span></span>
value
</li>
<li><span class="parameter">deadzone</span>
<span class="types"><span class="type">number</span></span>
deadzone
</li>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">number</span></span>
0 if x &lt; deadzone; x otherwise
</ol>
</dd>
<dt>
<a name = "normalize"></a>
<strong>normalize (x, y)</strong>
</dt>
<dd>
Returns a normalized version of the vector (x,y), i.e. &ldquo;clamp&rdquo; the returned x,y coordinates into a circle of radius 1.
Typically used to avoid faster movement on diagonals, as if both horizontal and vertical values are 1, the (1,1) vector has √2 magnitude, higher than the 1 magnitude of a purely vertical or horizontal movement.
</ul>
</ul>
</ul>
</ul>
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">x</span>
<span class="types"><span class="type">number</span></span>
value
</li>
<li><span class="parameter">y</span>
<span class="types"><span class="type">number</span></span>
value
</li>
</ul>
<h3>Returns:</h3>
<ol>
<li>
<span class="types"><span class="type">number</span></span>
clamped x value</li>
<li>
<span class="types"><span class="type">number</span></span>
clamped y value</li>
</ol>
</dd>
<dt>
<a name = "passive"></a>
<strong>passive (source)</strong>
</dt>
<dd>
Mark an input source as passive.
</ul>
</ul>
</ul>
</ul>
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">source</span>
<span class="types"><span class="type">InputSource</span></span>
input source to mark as passive
</li>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">InputSource</span></span>
the same input source
</ol>
</dd>
<dt>
<a name = "passive"></a>
<strong>passive (source)</strong>
</dt>
<dd>
Mark an input source as active.
Note that input sources are active by default in most cases.
</ul>
</ul>
</ul>
</ul>
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">source</span>
<span class="types"><span class="type">InputSource</span></span>
input source to mark as active
</li>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">InputSource</span></span>
the same input source
</ol>
</dd>
</dl>
<h2 class="section-header has-description"><a name="Input_objects"></a>Input objects </h2>
<div class="section-description">
Input methods. </p>
<p> Methods and attributes available on Input objects. See <a href="../modules/input.html#">input</a> to create such an object.
</div>
<dl class="function">
<dt>
<a name = "Input.config"></a>
<strong>Input.config</strong>
</dt>
<dd>
Input configuration table. </p>
<p> It can be used to recreate this input object later (by passing the table as an argument for the input constructor).
This table does not contain any userdata and should be easily serializable (e.g. to save custom input binding config).
This doesn&rsquo;t include input state, grab state, the event registry and the selected joystick since they may change often during runtime.</p>
<p> Can be changed anytime, but you will need to call <a href="../modules/input.html#Input:reload">reload</a> to apply changes.</p>
<p> See <a href="#Input_expressions">expressions</a> for an explanation on how to write input expressions.
</ul>
</ul>
</ul>
</ul>
<h3>Usage:</h3>
<ul>
<pre class="example">player.config = {
<span class="comment">-- list of input sources expressions: either a string, or a table to specify some arguments for the expression
</span> <span class="string">"key.a"</span>, <span class="string">"key.d - key.a"</span>, {<span class="string">"key.left + x"</span>, x=<span class="number">0.5</span>},
<span class="comment">-- children input: the table take the same fields as this
</span> jump = {...},
<span class="comment">-- The deadzone for analog inputs (e.g. joystick axes): if the input absolute value is strictly below this, it will be considered as 0. 0.05 by default.
</span> <span class="comment">-- This is applied automatically after the evaluation of input expressions.
</span> deadzone = <span class="number">0.05</span>,
<span class="comment">-- The pressed threshold: an input is considered down if above or equal to this value. 0.05 by default.
</span> <span class="comment">-- This is considered when determining if the input is pressed, odwn and released.
</span> threshold = <span class="number">0.05</span>,
<span class="comment">-- Dimension of the input (i.e. the number of values returned by this input). 1 by default.
</span> dimension = <span class="number">1</span>
}</pre>
</ul>
</dd>
<dt>
<a name = "Input.children"></a>
<strong>Input.children <sup><em>[read-only]</em></sup></strong>
</dt>
<dd>
List and map of children <a href="../modules/input.html#Input_objects">Input</a>s. </p>
<p> Takes the form <code>{[child1.name]=child1, [child2.name]=child2, child1, child2&hellip;}</code>.
Each child input is present both an element of this list and as the value associated with its name in the table.</p>
<p> Note that children are <em>also</em> set directly on the input object for easier access.
</ul>
</ul>
</ul>
</ul>
<h3>Usage:</h3>
<ul>
<pre class="example"><span class="keyword">local</span> player = input{ fire = <span class="string">"button.a"</span> }
<span class="keyword">local</span> fire = player.fire
<span class="comment">-- Is the same as:
</span><span class="keyword">local</span> fire = player.children.fire</pre>
</ul>
</dd>
<dt>
<a name = "Input.name"></a>
<strong>Input.name <sup><em>[read-only]</em></sup></strong>
</dt>
<dd>
Name of the input.
Defined on children inputs only.
</ul>
<h3>Type:</h3>
<ul>
<code>string</code>
</ul>
</ul>
</ul>
</dd>
<dt>
<a name = "Input.enabled"></a>
<strong>Input.enabled <sup><em>[read-only]</em></sup></strong>
</dt>
<dd>
<code>false</code> if the input is disabled, <code>true</code> otherwise.
If the input is disabled, its children are also disabled.
</ul>
</ul>
</ul>
</ul>
</dd>
<dt>
<a name = "Input.grabbed"></a>
<strong>Input.grabbed <sup><em>[read-only]</em></sup></strong>
</dt>
<dd>
<code>false</code> if the input is currently not grabbed, the grabbing <a href="../modules/input.html#Input_objects">Input</a> otherwise.
</ul>
</ul>
</ul>
</ul>
</dd>
<dt>
<a name = "Input.grabbing"></a>
<strong>Input.grabbing <sup><em>[read-only]</em></sup></strong>
</dt>
<dd>
<code>false</code> if the input is not grabbing another input, the <a href="../modules/input.html#Input_objects">Input</a> it is grabbing from otherwise.
</ul>
</ul>
</ul>
</ul>
</dd>
<dt>
<a name = "Input.event"></a>
<strong>Input.event</strong>
</dt>
<dd>
<p>Input event registry.
The following events are available:</p>
<ul>
<li><p><code>&quot;moved&quot;</code>: called when the input value change, with arguments <code>(new value, delta since last event)</code>. For inputs with dimension > 1, arguments are <code>(new value[1], new value[2], &hellip;, delta[1], delta[2], &hellip;)</code>.</p></li>
<li><p><code>&quot;pressed&quot;</code>: called when the input is pressed, with arguments <code>(1, new value, delta since last event)</code>. For inputs with dimension > 1, arguments are <code>(dimensions that was pressed, new value[1], new value[2], &hellip;, delta[1], delta[2], &hellip;)</code>.</p></li>
<li><p><code>&quot;released&quot;</code>: called when the input is released, with arguments <code>(1, new value, delta since last event)</code>. For inputs with dimension > 1, arguments are <code>(dimensions that was pressed, new value[1], new value[2], &hellip;, delta[1], delta[2], &hellip;)</code>.</p></li>
</ul>
</ul>
</ul>
</ul>
</ul>
</dd>
<dt>
<a name = "Input:update"></a>
<strong>Input:update ()</strong>
</dt>
<dd>
Update the input and its children.
Should be called every frame, typically <em>after</em> you've done all your input handling
(otherwise <a href="../modules/input.html#Input:pressed">pressed</a> and <a href="../modules/input.html#Input:released">released</a> may never return true and <a href="../modules/input.html#Input:delta">delta</a> might be wrong).</p>
<p> If the input is grabbed, will update the input that grabbed it instead.</p>
<p> (Note: this do not need to be called on inputs that are grabbing another input as the grabbed input will update it automatically)
</ul>
</ul>
</ul>
</ul>
</dd>
<dt>
<a name = "Input:clone"></a>
<strong>Input:clone ([copyState=false])</strong>
</dt>
<dd>
Create a new input object based on this input <a href="../modules/input.html#Input.config">config</a> data.
Unless <code>copyState</code> is set, the clone will only keep the <a href="../modules/input.html#Input.config">config</a> data and the input <a href="../modules/input.html#Input.name">name</a>; other state will be set to the default values.
</ul>
</ul>
</ul>
</ul>
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">copyState</span>
<span class="types"><span class="type">boolean</span></span>
if <code>true</code>, will copy the currrent state of the input into the clone. The input states includes the current input value, if it is enabled/disabled, and the current joystick; note that the grabbed state (i.e. the <a href="../modules/input.html#Input.grabbed">grabbed</a> and <a href="../modules/input.html#Input.grabbing">grabbing</a> fields) is not copied.
(<em>default</em> false)
</li>
</ul>
</dd>
<dt>
<a name = "Input:reload"></a>
<strong>Input:reload ()</strong>
</dt>
<dd>
Reload the input <a href="../modules/input.html#Input.config">config</a>, and do the same for its children.
</ul>
</ul>
</ul>
</ul>
</dd>
<dt>
<a name = "Input:disable"></a>
<strong>Input:disable ()</strong>
</dt>
<dd>
Disable the input and its children, preventing further updates and events.
The input can be reenabled using <a href="../modules/input.html#Input:enable">enable</a>.
</ul>
</ul>
</ul>
</ul>
</dd>
<dt>
<a name = "Input:enable"></a>
<strong>Input:enable ()</strong>
</dt>
<dd>
Enable the input and its children, allowing further updates and events.
The should be called after disabling the input using <a href="../modules/input.html#Input:disable">disable</a>.
</ul>
</ul>
</ul>
</ul>
</dd>
<dt>
<a name = "Input:onNextActiveSource"></a>
<strong>Input:onNextActiveSource (fn[, filter])</strong>
</dt>
<dd>
Will call <code>fn(source)</code> on the next activated source (including sources not currently used by this input).
Typically used to detect an input in your game input binding settings.
</ul>
</ul>
</ul>
</ul>
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">fn</span>
function that will be called on the next activated source matching the filter
</li>
<li><span class="parameter">filter</span>
list of string patterns that sources must start with (example <code>{&quot;button&quot;, &quot;key&quot;}</code> to only get buttons and key sources)
(<em>optional</em>)
</li>
</ul>
</dd>
<dt>
<a name = "Input:grab"></a>
<strong>Input:grab ()</strong>
</dt>
<dd>
Grab the input and its children and returns the resulting grabbing input. </p>
<p> Grabbed inputs are set to a neutral position and disabled (will no longer update) and will instead pass all new updates to the grabbing input.</p>
<p> This is typically used for contextual action or pause menus: by grabbing the player input, all the direct use of
this input in the game will stop (can&rsquo;t move caracter, &hellip;) and instead you can use the grabbing input to handle input in the pause menu.
To stop grabbing an input, you will need to call <a href="../modules/input.html#Input:release">release</a> on the grabbing input.</p>
<p> The grabbing input is created by cloning the current input and starts with the same state as the input when it was grabbed.
</ul>
</ul>
</ul>
</ul>
</dd>
<dt>
<a name = "Input:release"></a>
<strong>Input:release ()</strong>
</dt>
<dd>
Release an input that is currently grabbing another and its children.
The parent grabbed input will be re-enabled (will update again). This grabbing input will be reset to a neutral position and disabled when released.
</ul>
</ul>
</ul>
</ul>
</dd>
<dt>
<a name = "Input:neutralize"></a>
<strong>Input:neutralize ()</strong>
</dt>
<dd>
Set the state of this input and its children to a neutral position (i.e. value = 0 for every dimension).
</ul>
</ul>
</ul>
</ul>
</dd>
<dt>
<a name = "Input:set"></a>
<strong>Input:set (...)</strong>
</dt>
<dd>
Manually set the state of this input.
</ul>
</ul>
</ul>
</ul>
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">...</span>
</li>
</ul>
</dd>
<dt>
<a name = "Input:setJoystick"></a>
<strong>Input:setJoystick (joystick)</strong>
</dt>
<dd>
Set the joystick associated with this input.
This input will then ignore every other joystick.
Set joystick to <code>nil</code> to disable and get input from every connected joystick.
</ul>
</ul>
</ul>
</ul>
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">joystick</span>
LÖVE jostick object to associate
</li>
</ul>
</dd>
<dt>
<a name = "Input:getJoystick"></a>
<strong>Input:getJoystick ()</strong>
</dt>
<dd>
Returns the currently selected joystick.
</ul>
</ul>
</ul>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">joystick</span></span>
LÖVE jostick object
</ol>
</dd>
<dt>
<a name = "Input:down"></a>
<strong>Input:down ()</strong>
</dt>
<dd>
Returns <code>true</code> if the input is currently down, <code>false</code> otherwise.
</ul>
</ul>
</ul>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">boolean</span></span>
if input is down on at least one dimensions
</ol>
</dd>
<dt>
<a name = "Input:pressed"></a>
<strong>Input:pressed ()</strong>
</dt>
<dd>
Returns <code>true</code> if the input has just been pressed, <code>false</code> otherwise.
</ul>
</ul>
</ul>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">boolean</span></span>
if input has just been pressed on at least one dimensions
</ol>
</dd>
<dt>
<a name = "Input:released"></a>
<strong>Input:released ()</strong>
</dt>
<dd>
Returns <code>true</code> if the input has just been released, <code>false</code> otherwise.
</ul>
</ul>
</ul>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">boolean</span></span>
if input has just been released on at least one dimensions
</ol>
</dd>
<dt>
<a name = "Input:value"></a>
<strong>Input:value ()</strong>
</dt>
<dd>
Returns the current value of the input.
If dimension > 1, this will return several values, one per dimension.
</ul>
</ul>
</ul>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">number,...</span></span>
current value of the input for every dimension
</ol>
</dd>
<dt>
<a name = "Input:delta"></a>
<strong>Input:delta ()</strong>
</dt>
<dd>
Returns the delta value of the input since the last call to <a href="../modules/input.html#Input:update">update</a>.
If dimension > 1, this will return several values, one per dimension.
</ul>
</ul>
</ul>
</ul>
<h3>Returns:</h3>
<ol>
<span class="types"><span class="type">number,...</span></span>
delta of the input for every dimension
</ol>
</dd>
</dl>
<h2 class="section-header has-description"><a name="Input_sources"></a>Input sources </h2>
<div class="section-description">
Input sources are the initial source of input data; each input source can return a single number value.
They are identified by a Lua identifier name.
See <a href="#Input_expressions">expressions</a> on how to use them in expressions.</p>
<p> Input sources are provided for common input methods (keyboard, mouse, gamepad) by default; see below for a list of built-in input sources.</p>
<p> Additionally, you can define your own input sources, by emitting events in the SignalRegistry returned by <code>uqt.input.event</code>.
See the file <code>input/event.lua</code> to see a description of the events you will need to emit. The file also contains the definition
of the built-in input sources that you may use as an example.
</div>
<dl class="function">
<dt>
<a name = "key.X"></a>
<strong>key.X</strong>
</dt>
<dd>
Keyboard input: 1 if the key X is down, 0 otherwise.
X can be any of LÖVE&rsquo;s <a href="https://love2d.org/wiki/KeyConstant">KeyConstant</a>.
</ul>
</ul>
</ul>
</ul>
</dd>
<dt>
<a name = "scancode.X"></a>
<strong>scancode.X</strong>
</dt>
<dd>
Keyboard input: 1 if the key with scancode X is down, 0 otherwise.
X can be any of LÖVE&rsquo;s <a href="https://love2d.org/wiki/Scancode">Scancode</a>.
</ul>
</ul>
</ul>
</ul>
</dd>
<dt>
<a name = "text.X"></a>
<strong>text.X</strong>
</dt>
<dd>
Text input: 1 if the text X was entered, 0 otherwise.
X can be any text.
</ul>
</ul>
</ul>
</ul>
</dd>
<dt>
<a name = "mouse"></a>
<strong>mouse</strong>
</dt>
<dd>
Mouse input: <code>mouse[N]</code> is 1 if the mouse button is down, 0 otherwise.
N is either 1 for the primary mouse button, 2 for secondary or 3 for middle button.
</ul>
</ul>
</ul>
</ul>
<ul>
<li><span class="parameter">mouse</span>
<code>mouse[N]</code>
</li>
</ul>
</dd>
<dt>
<a name = "mouse.x"></a>
<strong>mouse.x</strong>
</dt>
<dd>
Mouse input: X position of the mouse cursor in the game window.
</ul>
</ul>
</ul>
</ul>
</dd>
<dt>
<a name = "mouse.y"></a>
<strong>mouse.y</strong>
</dt>
<dd>
Mouse input: Y position of the mouse cursor in the game window.
</ul>
</ul>
</ul>
</ul>
</dd>
<dt>
<a name = "mouse.dx"></a>
<strong>mouse.dx</strong>
</dt>
<dd>
Mouse input: latest X movement of the mouse cursor. </p>
<p> <code>mouse.dx.p</code> and <code>mouse.dx.n</code> will respectively only report movement in the positive or negative direction and return absolute value.
</ul>
</ul>
</ul>
</ul>
</dd>
<dt>
<a name = "mouse.dy"></a>
<strong>mouse.dy</strong>
</dt>
<dd>
Mouse input: latest Y movement of the mouse cursor. </p>
<p> <code>mouse.dy.p</code> and <code>mouse.dy.n</code> will respectively only report movement in the positive or negative direction and return absolute value.
</ul>
</ul>
</ul>
</ul>
</dd>
<dt>
<a name = "wheel.dx"></a>
<strong>wheel.dx</strong>
</dt>
<dd>
Mouse input: latest X movement of the mouse wheel. </p>
<p> <code>wheel.dx.p</code> and <code>wheel.dx.n</code> will respectively only report movement in the positive or negative direction and return absolute value.
</ul>
</ul>
</ul>
</ul>
</dd>
<dt>
<a name = "wheel.dy"></a>
<strong>wheel.dy</strong>
</dt>
<dd>
Mouse input: latest Y movement of the mouse wheel. </p>
<p> <code>wheel.dy.p</code> and <code>wheel.dy.n</code> will respectively only report movement in the positive or negative direction and return absolute value.
</ul>
</ul>
</ul>
</ul>
</dd>
<dt>
<a name = "button.X"></a>
<strong>button.X</strong>
</dt>
<dd>
Gamepad input: 1 if the button X is down, 0 otherwise.
X can be any of LÖVE&rsquo;s <a href="https://love2d.org/wiki/GamepadButton">GamepadButton</a>.
</ul>
</ul>
</ul>
</ul>
</dd>
<dt>
<a name = "axis.X"></a>
<strong>axis.X</strong>
</dt>
<dd>
Gamepad input: current value of the gamepad axis (between -1 and 1).
X can be any of LÖVE&rsquo;s <a href="https://love2d.org/wiki/GamepadAxis">GamepadAxis</a>.</p>
<p> <code>axis.X.p</code> and <code>axis.X.n</code> will respectively only report movement in the positive or negative direction and return absolute value.
</ul>
</ul>
</ul>
</ul>
</dd>
<dt>
<a name = "dt"></a>
<strong>dt</strong>
</dt>
<dd>
On new frame: current delta time value since last frame. Updated on each call to <code>love.update</code>.
Note that if this input source is present in an expression, the other input sources in the same expression will be set as passive by default.
</ul>
</ul>
</ul>
</ul>
<ul>
<li><span class="parameter">dt</span>
</li>
</ul>
</dd>
<dt>
<a name = "child.X"></a>
<strong>child.X</strong>
</dt>
<dd>
Children inputs: current value of a child input of the current input.
For child inputs of dimension 1.
Replace X with the name of the child input.</p>
<p> If the child input is of dimension at least 2, instead use <code>child.X[N]</code>, which gives the
current value of the Nth dimension of a child input of the current input.
Replace X with the name of the child input, and N with the index of the dimension you want.
</ul>
</ul>
</ul>
</ul>
</dd>
<dt>
<a name = "value"></a>
<strong>value</strong>
</dt>
<dd>
Current input: current value of the current input.
For inputs of dimension 1.</p>
<p> If the input is of dimension at least 2, instead use <code>value[N]</code>, which gives the
current value of the Nth dimension of the current input.
Replace N with the index of the dimension you want.</p>
<p> Note that is input is passive by default.
Think twice before marking it active as this may create a feedback loop (the input being updated will trigger it to be updated again, and so on).
</ul>
</ul>
</ul>
</ul>
<ul>
<li><span class="parameter">value</span>
</li>
</ul>
</dd>
</dl>
</div> <!-- id="content" -->
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
<i style="float:right;">Last updated 2022-10-13 00:23:58 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
</html>
View git blame Copy permalink