508 lines
22 KiB
HTML
508 lines
22 KiB
HTML
<!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>Noble Engine API reference</title>
|
|
<link rel="stylesheet" href="../ldoc.css" type="text/css" />
|
|
<link rel="icon" href="favicon.ico">
|
|
</head>
|
|
<body>
|
|
|
|
<div id="container">
|
|
|
|
<div id="main">
|
|
|
|
|
|
<!-- Menu -->
|
|
|
|
<div id="navigation">
|
|
<a href="../index.html"><div class="logo">
|
|
<h1>Noble Engine</h1>
|
|
</div></a>
|
|
|
|
<div class="nav-module">
|
|
<h2>Noble.Animation</h2>
|
|
<ul>
|
|
<h3>Setup </h3>
|
|
<ul>
|
|
<li><a href="#Noble.Animation.new">.new</a></li>
|
|
<li><a href="#animation:addState">animation:addState</a></li>
|
|
</ul>
|
|
<h3>Properties </h3>
|
|
<ul>
|
|
<li><a href="#animation.current">animation.current</a></li>
|
|
<li><a href="#animation.currentName">animation.currentName</a></li>
|
|
<li><a href="#animation.currentFrame">animation.currentFrame</a></li>
|
|
<li><a href="#animation.direction">animation.direction</a></li>
|
|
</ul>
|
|
<h3>Methods </h3>
|
|
<ul>
|
|
<li><a href="#animation:setState">animation:setState</a></li>
|
|
<li><a href="#animation:draw">animation:draw</a></li>
|
|
<li><a href="#animation:drawFrame">animation:drawFrame</a></li>
|
|
</ul>
|
|
<h3>Constants </h3>
|
|
<ul>
|
|
<li><a href="#Noble.Animation.DIRECTION_RIGHT">.DIRECTION_RIGHT</a></li>
|
|
<li><a href="#Noble.Animation.DIRECTION_LEFT">.DIRECTION_LEFT</a></li>
|
|
</ul>
|
|
</ul>
|
|
</div>
|
|
|
|
|
|
<div class="nav-modules">
|
|
<div class="nav-kind">
|
|
<h3>Modules</h3>
|
|
<ul>
|
|
<li><a href="../modules/Noble.html">Noble</a></li>
|
|
<li><span class="selected">Noble.Animation</span></li>
|
|
<li><a href="../modules/Noble.Bonk.html">Noble.Bonk</a></li>
|
|
<li><a href="../modules/Noble.GameData.html">Noble.GameData</a></li>
|
|
<li><a href="../modules/Noble.Input.html">Noble.Input</a></li>
|
|
<li><a href="../modules/Noble.Menu.html">Noble.Menu</a></li>
|
|
<li><a href="../modules/Noble.Settings.html">Noble.Settings</a></li>
|
|
<li><a href="../modules/Noble.Text.html">Noble.Text</a></li>
|
|
<li><a href="../modules/Noble.Transition.html">Noble.Transition</a></li>
|
|
<li><a href="../modules/Ease.html">Ease</a></li>
|
|
</ul>
|
|
</div>
|
|
<div class="nav-kind">
|
|
<h3>Classes</h3>
|
|
<ul>
|
|
<li><a href="../classes/NobleScene.html">NobleScene</a></li>
|
|
<li><a href="../classes/NobleSprite.html">NobleSprite</a></li>
|
|
</ul>
|
|
</div>
|
|
<div class="nav-kind">
|
|
<h3>Examples</h3>
|
|
<ul>
|
|
<li><a href="../examples/SceneTemplate.lua.html">SceneTemplate.lua</a></li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
|
|
</div>
|
|
|
|
<div id="content">
|
|
|
|
<h1>Noble.Animation</h1>
|
|
<p>Animation states using a spritesheet/imagetable.</p>
|
|
<p> Ideal for use with <a href="../classes/NobleSprite.html#">NobleSprite</a> objects. Suitable for other uses as well.</p>
|
|
|
|
<hr/>
|
|
|
|
<h2 class="section-header "><a name="Setup"></a>Setup </h2>
|
|
<!-- -->
|
|
<dl class="function">
|
|
<dt>
|
|
<a name = "Noble.Animation.new"></a>
|
|
<span class="item-name">Noble.Animation.new(__view)<span>
|
|
</dt>
|
|
<dd>
|
|
Create a new animation "state machine". This function is called automatically when creating a new <a href="../classes/NobleSprite.html#">NobleSprite</a>.
|
|
|
|
<h3>Parameters</h3>
|
|
<ul class="parameters">
|
|
<li><span class="parameter">__view</span>
|
|
<span class="types"><span class="type">string</span></span>
|
|
<br/>
|
|
This can be: the path to a spritesheet image file or an image table object (<code>Graphics.imagetable</code>). See Playdate SDK docs for imagetable file naming conventions.
|
|
</li>
|
|
</ul>
|
|
|
|
<h3>Returns</h3>
|
|
<ol>
|
|
|
|
<code>animation</code>, a new animation object.
|
|
</ol>
|
|
|
|
|
|
<h3>See</h3>
|
|
<ul>
|
|
<a href="../classes/NobleSprite.html#noblesprite:init">NobleSprite:init</a>
|
|
</ul>
|
|
|
|
<h3>Usage</h3>
|
|
<pre class="example"><span class="keyword">local</span> myHero = <span class="function-name">MyHero</span>(<span class="string">"path/to/spritesheet"</span>)</pre>
|
|
<pre class="example"><span class="comment">-- When extending NobleSprite (recommended), you don't call Noble.Animation.new(),
|
|
</span><span class="comment">-- but you do feed its __view argument into MySprite.super.init()...
|
|
</span>MyHero = {}
|
|
<span class="function-name">class</span>(<span class="string">"MyHero"</span>).<span class="function-name">extends</span>(NobleSprite)
|
|
|
|
<span class="keyword">function</span> MyHero:<span class="function-name">init</span>()
|
|
MyHero.super.<span class="function-name">init</span>(self, <span class="string">"assets/images/Hero"</span>)
|
|
<span class="comment">-- ...
|
|
</span> <span class="comment">-- A new NobleSprite creates a Noble.Animation object named "self.animation"
|
|
</span> self.animation:<span class="function-name">addState</span>(<span class="string">"idle"</span>, <span class="number">1</span>, <span class="number">30</span>)
|
|
self.animation:<span class="function-name">addState</span>(<span class="string">"jump"</span>, <span class="number">31</span>, <span class="number">34</span>, <span class="string">"float"</span>)
|
|
self.animation:<span class="function-name">addState</span>(<span class="string">"float"</span>, <span class="number">35</span>, <span class="number">45</span>)
|
|
self.animation:<span class="function-name">addState</span>(<span class="string">"turn"</span>, <span class="number">46</span>, <span class="number">55</span>, <span class="string">"idle"</span>)
|
|
self.animation:<span class="function-name">addState</span>(<span class="string">"walk"</span>, <span class="number">56</span>, <span class="number">65</span>)
|
|
<span class="comment">-- ...
|
|
</span><span class="keyword">end</span></pre>
|
|
<pre class="example"><span class="keyword">local</span> myAnimation = Noble.Animation.<span class="function-name">new</span>(<span class="string">"path/to/spritesheet"</span>)</pre>
|
|
<pre class="example"><span class="comment">-- When extending playdate.graphics.Sprite, Noble.Animation.new() must be called manually...
|
|
</span>MyHero = {}
|
|
<span class="function-name">class</span>(<span class="string">"MyHero"</span>).<span class="function-name">extends</span>(Graphics.sprite)
|
|
|
|
<span class="keyword">function</span> MyHero:<span class="function-name">init</span>()
|
|
MyHero.super.<span class="function-name">init</span>(self)
|
|
<span class="comment">-- ...
|
|
</span> self.animation = Noble.Animation.<span class="function-name">new</span>(<span class="string">"assets/images/Hero"</span>)
|
|
self.animation:<span class="function-name">addState</span>(<span class="string">"idle"</span>, <span class="number">1</span>, <span class="number">30</span>)
|
|
self.animation:<span class="function-name">addState</span>(<span class="string">"jump"</span>, <span class="number">31</span>, <span class="number">34</span>, <span class="string">"float"</span>)
|
|
self.animation:<span class="function-name">addState</span>(<span class="string">"float"</span>, <span class="number">35</span>, <span class="number">45</span>)
|
|
self.animation:<span class="function-name">addState</span>(<span class="string">"turn"</span>, <span class="number">46</span>, <span class="number">55</span>, <span class="string">"idle"</span>)
|
|
self.animation:<span class="function-name">addState</span>(<span class="string">"walk"</span>, <span class="number">56</span>, <span class="number">65</span>)
|
|
<span class="comment">-- ...
|
|
</span><span class="keyword">end</span></pre>
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "animation:addState"></a>
|
|
<span class="item-name">animation:addState(__name, __startFrame, __endFrame, __next[, __loop=true], __onComplete[, __frameDuration=1])<span>
|
|
</dt>
|
|
<dd>
|
|
Add an animation state. The first state added will be the default set for this animation.</p>
|
|
|
|
<p> <strong>NOTE:</strong> Added states are first-degree member objects of your Noble.Animation object, so do not use names of already existing methods/properties ("current", "draw", etc.).
|
|
|
|
<h3>Parameters</h3>
|
|
<ul class="parameters">
|
|
<li><span class="parameter">__name</span>
|
|
<span class="types"><span class="type">string</span></span>
|
|
<br/>
|
|
The name of the animation, this is also used as the key for the animation.
|
|
</li>
|
|
<li><span class="parameter">__startFrame</span>
|
|
<span class="types"><span class="type">integer</span></span>
|
|
<br/>
|
|
This is the first frame of this animation in the imagetable/spritesheet
|
|
</li>
|
|
<li><span class="parameter">__endFrame</span>
|
|
<span class="types"><span class="type">integer</span></span>
|
|
<br/>
|
|
This is the final frame of this animation in the imagetable/spritesheet
|
|
</li>
|
|
<li><span class="parameter">__next</span>
|
|
<span class="types"><span class="type">string</span></span>
|
|
<br/>
|
|
By default, animation states will loop, but if you want to sequence an animation, enter the name of the next state here.
|
|
</li>
|
|
<li><span class="parameter">__loop</span>
|
|
<span class="types"><span class="type">boolean</span></span>
|
|
<span class="default">= <span class="value">true</span> (default)</span>
|
|
<br/>
|
|
If you want a state to "freeze" on its final frame, instead of looping, enter <code>false</code> here.
|
|
</li>
|
|
<li><span class="parameter">__onComplete</span>
|
|
<br/>
|
|
This function will run when this animation is complete. Be careful when using this on a looping animation!
|
|
</li>
|
|
<li><span class="parameter">__frameDuration</span>
|
|
<span class="types"><span class="type">integer</span></span>
|
|
<span class="default">= <span class="value">1</span> (default)</span>
|
|
<br/>
|
|
This is the number of ticks between each frame in this animation. If not specified, it will be set to 1.
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
<h3>Usage</h3>
|
|
<pre class="example"><span class="comment">-- You can reference an animation's state's properties using bog-standard lua syntax:
|
|
</span>
|
|
animation.idle.startFrame <span class="comment">-- 30
|
|
</span>animation.walk.endFrame <span class="comment">-- 65
|
|
</span>animation.[<span class="string">"walk"</span>].endFrame <span class="comment">-- 65
|
|
</span>animation.jump.name <span class="comment">-- "jump"
|
|
</span>animation.[<span class="string">"jump"</span>].<span class="global">next</span> <span class="comment">-- "float"
|
|
</span>animation.idle.<span class="global">next</span> <span class="comment">-- nil</span></pre>
|
|
|
|
</dd>
|
|
</dl>
|
|
<h2 class="section-header "><a name="Properties"></a>Properties </h2>
|
|
<!-- -->
|
|
<dl class="function">
|
|
<dt>
|
|
<a name = "animation.current"></a>
|
|
<span class="item-name">animation.current<span>
|
|
</dt>
|
|
<dd>
|
|
The currently set animation state. </p>
|
|
|
|
<p> This is intended as <code>read-only</code>. You should not modify this property directly.
|
|
|
|
|
|
|
|
|
|
<h3>See</h3>
|
|
<ul>
|
|
<a href="../modules/Noble.Animation.html#animation:setState">setState</a>
|
|
</ul>
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "animation.currentName"></a>
|
|
<span class="item-name">animation.currentName<span>
|
|
</dt>
|
|
<dd>
|
|
The name of the current animation state. Calling this instead of <code>animation.current.name</code> is <em>just</em> a little faster.</p>
|
|
|
|
<p> This is intended as <code>read-only</code>. You should not modify this property directly.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "animation.currentFrame"></a>
|
|
<span class="item-name">animation.currentFrame<span>
|
|
</dt>
|
|
<dd>
|
|
The current frame of the animation. This is the index of the imagetable, not the frame of the current state.</p>
|
|
|
|
<p> Most of the time, you should not modify this directly, although you can if you're feeling saucy and are prepared for unpredictable results.
|
|
|
|
|
|
|
|
|
|
<h3>See</h3>
|
|
<ul>
|
|
<a href="../modules/Noble.Animation.html#animation:draw">draw</a>
|
|
</ul>
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "animation.direction"></a>
|
|
<span class="item-name">animation.direction<span>
|
|
</dt>
|
|
<dd>
|
|
This controls the flipping of the image when drawing. DIRECTION<em>RIGHT is unflipped, DIRECTION</em>LEFT is flipped on the X axis.
|
|
|
|
|
|
|
|
|
|
|
|
<h3>Usage</h3>
|
|
<pre class="example"><span class="keyword">function</span> MyHero:<span class="function-name">goLeft</span>()
|
|
self.animation.direction = Noble.Animation.DIRECTION_LEFT
|
|
<span class="comment">-- ...
|
|
</span><span class="keyword">end</span></pre>
|
|
|
|
</dd>
|
|
</dl>
|
|
<h2 class="section-header "><a name="Methods"></a>Methods </h2>
|
|
<!-- -->
|
|
<dl class="function">
|
|
<dt>
|
|
<a name = "animation:setState"></a>
|
|
<span class="item-name">animation:setState(__animationState[, __continuous=false], __unlessThisState)<span>
|
|
</dt>
|
|
<dd>
|
|
Sets the current animation state. This can be run in a object's <code>update</code> method because it only changes the animation state if the new state is different from the current one.
|
|
|
|
<h3>Parameters</h3>
|
|
<ul class="parameters">
|
|
<li><span class="parameter">__animationState</span>
|
|
<span class="types"><span class="type">string</span> or <span class="type">Noble.Animation</span></span>
|
|
<br/>
|
|
The name of the animation to set. You can pass the name of the state, or the object itself.
|
|
</li>
|
|
<li><span class="parameter">__continuous</span>
|
|
<span class="types"><span class="type">boolean</span></span>
|
|
<span class="default">= <span class="value">false</span> (default)</span>
|
|
<br/>
|
|
Set to true if your new state's frames line up with the previous one's, i.e.: two walk cycles but one is wearing a cute hat!
|
|
</li>
|
|
<li><span class="parameter">__unlessThisState</span>
|
|
<span class="types"><span class="type">string</span> or <span class="type">Noble.Animation</span></span>
|
|
<br/>
|
|
If this state is the current state, do not set the new one.
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
<h3>Usage</h3>
|
|
<pre class="example">animation:<span class="function-name">setState</span>(<span class="string">"walk"</span>)</pre>
|
|
<pre class="example">animation:<span class="function-name">setState</span>(animation.walk)</pre>
|
|
<pre class="example">animation:<span class="function-name">setState</span>(animation.walkNoHat)
|
|
<span class="comment">--
|
|
</span>animation:<span class="function-name">setState</span>(animation.walkYesHat, <span class="keyword">true</span>)</pre>
|
|
<pre class="example"><span class="keyword">function</span> MyHero:<span class="function-name">update</span>()
|
|
<span class="comment">-- Input
|
|
</span> <span class="comment">-- ...
|
|
</span>
|
|
<span class="comment">-- Physics/collisions
|
|
</span> <span class="comment">-- ...
|
|
</span>
|
|
<span class="comment">-- Animation states
|
|
</span> <span class="keyword">if</span> (grounded) <span class="keyword">then</span>
|
|
<span class="keyword">if</span> (turning) <span class="keyword">then</span>
|
|
self.animation:<span class="function-name">setState</span>(self.animation.turn)
|
|
<span class="keyword">elseif</span> (<span class="global">math</span>.<span class="function-name">abs</span>(self.velocity.x) > <span class="number">15</span>) <span class="keyword">then</span>
|
|
self.animation:<span class="function-name">setState</span>(self.animation.walk, <span class="keyword">false</span>, self.animation.turn)
|
|
<span class="keyword">else</span>
|
|
self.animation:<span class="function-name">setState</span>(self.animation.idle, <span class="keyword">false</span>, self.animation.turn)
|
|
<span class="keyword">end</span>
|
|
<span class="keyword">else</span>
|
|
self.animation:<span class="function-name">setState</span>(self.animation.jump, <span class="keyword">false</span>, self.animation.float)
|
|
<span class="keyword">end</span>
|
|
|
|
groundedLastFrame = grounded
|
|
<span class="keyword">end</span></pre>
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "animation:draw"></a>
|
|
<span class="item-name">animation:draw([__x=0[, __y=0[, __advance=true]]])<span>
|
|
</dt>
|
|
<dd>
|
|
Draw the current frame. </p>
|
|
|
|
<p> When attached to a NobleSprite, this is called by <code>NobleSprite:draw()</code> when added to a scene. For non-NobleSprite sprites, put this method inside your sprite's <code>draw()</code> method, or inside <a href="../classes/NobleScene.html#noblescene:update">NobleScene:update</a>.
|
|
|
|
<h3>Parameters</h3>
|
|
<ul class="parameters">
|
|
<li><span class="parameter">__x</span>
|
|
<span class="types"><span class="type">number</span></span>
|
|
<span class="default">= <span class="value">0</span> (default)</span>
|
|
<br/>
|
|
|
|
|
|
|
|
</li>
|
|
<li><span class="parameter">__y</span>
|
|
<span class="types"><span class="type">number</span></span>
|
|
<span class="default">= <span class="value">0</span> (default)</span>
|
|
<br/>
|
|
|
|
|
|
|
|
</li>
|
|
<li><span class="parameter">__advance</span>
|
|
<span class="types"><span class="type">boolean</span></span>
|
|
<span class="default">= <span class="value">true</span> (default)</span>
|
|
<br/>
|
|
Advances to the next frame after drawing this one. Noble.Animation is frame-based, not "delta time"-based, so its speed is dependent on your game's framerate.
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
<h3>Usage</h3>
|
|
<pre class="example"><span class="keyword">function</span> MySprite:<span class="function-name">draw</span>()
|
|
animation:<span class="function-name">draw</span>()
|
|
<span class="keyword">end</span></pre>
|
|
<pre class="example"><span class="keyword">function</span> MyScene:<span class="function-name">update</span>()
|
|
animation:<span class="function-name">draw</span>(<span class="number">100</span>,<span class="number">100</span>)
|
|
<span class="keyword">end</span></pre>
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "animation:drawFrame"></a>
|
|
<span class="item-name">animation:drawFrame(__frameNumber[, __stateName=self.currentName[, __x=0[, __y=0[, __direction=self.direction]]]])<span>
|
|
</dt>
|
|
<dd>
|
|
Sometimes, you just want to draw a specific frame.
|
|
Use this for objects or sprites that you want to control outside of update loops, such as score counters, flipbook-style objects that respond to player input, etc.
|
|
|
|
<h3>Parameters</h3>
|
|
<ul class="parameters">
|
|
<li><span class="parameter">__frameNumber</span>
|
|
<span class="types"><span class="type">integer</span></span>
|
|
<br/>
|
|
The frame to draw from the current state. This is not an imagetable index. Entering <code>1</code> will draw the selected state's <code>startFrame</code>.
|
|
</li>
|
|
<li><span class="parameter">__stateName</span>
|
|
<span class="types"><span class="type">string</span></span>
|
|
<span class="default">= <span class="value">self.currentName</span> (default)</span>
|
|
<br/>
|
|
The specific state to pull the __frameNumber from.
|
|
</li>
|
|
<li><span class="parameter">__x</span>
|
|
<span class="types"><span class="type">number</span></span>
|
|
<span class="default">= <span class="value">0</span> (default)</span>
|
|
<br/>
|
|
|
|
|
|
|
|
</li>
|
|
<li><span class="parameter">__y</span>
|
|
<span class="types"><span class="type">number</span></span>
|
|
<span class="default">= <span class="value">0</span> (default)</span>
|
|
<br/>
|
|
|
|
|
|
|
|
</li>
|
|
<li><span class="parameter">__direction</span>
|
|
<span class="default">= <span class="value">self.direction</span> (default)</span>
|
|
<br/>
|
|
Override the current direction.
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
</dl>
|
|
<h2 class="section-header "><a name="Constants"></a>Constants </h2>
|
|
<!-- -->
|
|
<dl class="function">
|
|
<dt>
|
|
<a name = "Noble.Animation.DIRECTION_RIGHT"></a>
|
|
<span class="item-name">Noble.Animation.DIRECTION_RIGHT<span>
|
|
</dt>
|
|
<dd>
|
|
A re-contextualized instance of <code>playdate.graphics.kImageUnflipped</code>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "Noble.Animation.DIRECTION_LEFT"></a>
|
|
<span class="item-name">Noble.Animation.DIRECTION_LEFT<span>
|
|
</dt>
|
|
<dd>
|
|
A re-contextualized instance of <code>playdate.graphics.kImageFlippedX</code>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
</dl>
|
|
|
|
|
|
</div> <!-- id="content" -->
|
|
|
|
</div> <!-- id="main" -->
|
|
|
|
<div id="about">
|
|
<span><a href="https://github.com/NobleRobot/NobleEngine">Noble Engine</a> by Mark LaCroix, <a href="https://noblerobot.com">Noble Robot</a></span>
|
|
<span style="float:right;">
|
|
Documentation created using <a href="https://github.com/stevedonovan/LDoc">LDoc 1.5.0</a>.
|
|
</span>
|
|
</div> <!-- id="about" -->
|
|
|
|
</div> <!-- id="container" -->
|
|
|
|
</body>
|
|
</html>
|
|
|