fpv/source/libraries/noble/.docs/classes/NobleScene.html

486 lines
16 KiB
HTML
Raw Normal View History

2024-06-01 16:52:11 +03:00
<!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>NobleScene</h2>
<ul>
<h3>Properties </h3>
<ul>
<li><a href="#noblescene.name">noblescene.name</a></li>
<li><a href="#noblescene.backgroundColor">noblescene.backgroundColor</a></li>
</ul>
<h3>Tables </h3>
<ul>
<li><a href="#noblescene.inputHandler">noblescene.inputHandler</a></li>
<li><a href="#noblescene.sprites">noblescene.sprites</a></li>
</ul>
<h3>Methods</h3>
<ul>
<li><a href="#noblescene:addSprite">noblescene:addSprite</a></li>
<li><a href="#noblescene:removeSprite">noblescene:removeSprite</a></li>
</ul>
<h3>Callbacks </h3>
<ul>
<li><a href="#noblescene:init">noblescene:init</a></li>
<li><a href="#noblescene:enter">noblescene:enter</a></li>
<li><a href="#noblescene:start">noblescene:start</a></li>
<li><a href="#noblescene:update">noblescene:update</a></li>
<li><a href="#noblescene:drawBackground">noblescene:drawBackground</a></li>
<li><a href="#noblescene:exit">noblescene:exit</a></li>
<li><a href="#noblescene:finish">noblescene:finish</a></li>
<li><a href="#noblescene:pause">noblescene:pause</a></li>
<li><a href="#noblescene:resume">noblescene:resume</a></li>
</ul>
</ul>
</div>
<div class="nav-modules">
<div class="nav-kind">
<h3>Classes</h3>
<ul>
<li><span class="selected">NobleScene</span></li>
<li><a href="../classes/NobleSprite.html">NobleSprite</a></li>
</ul>
</div>
<div class="nav-kind">
<h3>Modules</h3>
<ul>
<li><a href="../modules/Noble.html">Noble</a></li>
<li><a href="../modules/Noble.Animation.html">Noble.Animation</a></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>Examples</h3>
<ul>
<li><a href="../examples/SceneTemplate.lua.html">SceneTemplate.lua</a></li>
</ul>
</div>
</div>
</div>
<div id="content">
<h1>NobleScene</h1>
<p>An abstract scene class.</p>
<p> Do not copy this file as a template for your scenes. Instead, your scenes will extend this class.
See <a href="../examples/SceneTemplate.lua.html">templates/SceneTemplate.lua</a> for a blank scene that you can copy and modify for your own scenes.
If you are using <a href="http://github.com/NobleRobot/NobleEngine-ProjectTemplate">NobleEngine-ProjectTemplate</a>,
see <code>scenes/ExampleScene.lua</code> for an implementation example.</p>
<h3>Usage</h3>
<pre class="example">YourSceneName = {}
class(&quot;YourSceneName&quot;).extends(NobleScene)
local scene = YourSceneName
</pre>
<hr/>
<h2 class="section-header "><a name="Properties"></a>Properties </h2>
<!-- -->
<dl class="function">
<dt>
<a name = "noblescene.name"></a>
<span class="item-name">noblescene.name<span>
</dt>
<dd>
The name of this scene. Optional.
If you do not set this value, it will take on the scene's <code>className</code>.
</dd>
<dt>
<a name = "noblescene.backgroundColor"></a>
<span class="item-name">noblescene.backgroundColor<span>
</dt>
<dd>
This is the background color of this scene.
</dd>
</dl>
<h2 class="section-header "><a name="Tables"></a>Tables </h2>
<!-- -->
<dl class="function">
<dt>
<a name = "noblescene.inputHandler"></a>
<span class="item-name">noblescene.inputHandler<span>
</dt>
<dd>
All scenes have a default inputHandler which is made active when the scene starts.
If you do not define your scene's <a href="../classes/NobleScene.html#noblescene.inputHandler">inputHandler</a>, it is <code>nil</code> and input is disabled when this scene
starts.
<h3>See</h3>
<ul>
<a href="../modules/Noble.Input.html#Noble.Input.setHandler">Noble.Input.setHandler</a>
</ul>
<h3>Usage</h3>
<pre class="example">YourSceneName.inputHandler = {
AButtonDown = <span class="keyword">function</span>()
// Your code here
<span class="keyword">end</span>,
AButtonHold = <span class="keyword">function</span>()
// Your code here
<span class="keyword">end</span>,
<span class="comment">-- ...
</span> <span class="comment">-- ...
</span>}
<span class="comment">-- OR...
</span><span class="comment">-- Use a non-scene-specific inputHandler, defined elsewhere.
</span>YourSceneName.inputHandler = somePreviouslyDefinedInputHandler
<span class="comment">-- OR...
</span><span class="comment">-- Reuse another scene's inputHandler.
</span>YourSceneName.inputHandler = SomeOtherSceneName.inputHandler</pre>
</dd>
<dt>
<a name = "noblescene.sprites"></a>
<span class="item-name">noblescene.sprites<span>
</dt>
<dd>
When you add a sprite to your scene, it is put in this table so the scene can keep track of it. </p>
<p> This is intended as <code>read-only</code>. You should not modify this table directly.
<h3>See</h3>
<ul>
<a href="../classes/NobleScene.html#noblescene:addSprite">addSprite</a>
</ul>
</dd>
</dl>
<h2 class="section-header "><a name="Methods"></a>Methods</h2>
<!-- -->
<dl class="function">
<dt>
<a name = "noblescene:addSprite"></a>
<span class="item-name">noblescene:addSprite(__sprite)<span>
</dt>
<dd>
Use this to add sprites to your scene instead of <code>playdate.graphics.sprite:add()</code>. </p>
<p> If your sprite is a <a href="../classes/NobleSprite.html#">NobleSprite</a>, using <code>NobleSprite:add()</code> will also call this method.</p>
<p> Sprites added with this method that are tracked by the scene. Any not manually removed before transitioning to another scene are automatically removed in <a href="../classes/NobleScene.html#noblescene:finish">finish</a>.
<h3>Parameters</h3>
<ul class="parameters">
<li><span class="parameter">__sprite</span>
<span class="types"><span class="type">playdate.graphics.sprite</span></span>
<br/>
The sprite to add to the scene.
</li>
</ul>
<h3>See</h3>
<ul>
<li><a href="../classes/NobleSprite.html#noblesprite:add">NobleSprite:add</a></li>
<li><a href="../classes/NobleScene.html#noblescene:removeSprite">removeSprite</a></li>
</ul>
</dd>
<dt>
<a name = "noblescene:removeSprite"></a>
<span class="item-name">noblescene:removeSprite(__sprite)<span>
</dt>
<dd>
Use this to remove sprites from your scene instead of <code>playdate.graphics.sprite:remove()</code>. </p>
<p> If your sprite is a <a href="../classes/NobleSprite.html#">NobleSprite</a>, using <code>NobleSprite:remove()</code> will also call this method.</p>
<p> Sprites not manually removed before transitioning to another scene are automatically removed in <a href="../classes/NobleScene.html#noblescene:finish">finish</a>.
<h3>Parameters</h3>
<ul class="parameters">
<li><span class="parameter">__sprite</span>
<span class="types"><span class="type">playdate.graphics.sprite</span></span>
<br/>
The sprite to add to the scene.
</li>
</ul>
<h3>See</h3>
<ul>
<li><a href="../classes/NobleSprite.html#noblesprite:remove">NobleSprite:remove</a></li>
<li><a href="../classes/NobleScene.html#noblescene:addSprite">addSprite</a></li>
</ul>
</dd>
</dl>
<h2 class="section-header "><a name="Callbacks"></a>Callbacks </h2>
<!-- -->
<dl class="function">
<dt>
<a name = "noblescene:init"></a>
<span class="item-name">noblescene:init()<span>
</dt>
<dd>
Implement this in your scene if you have code to run when your scene's object is created.
<h3>Usage</h3>
<pre class="example"><span class="keyword">function</span> YourSceneName:<span class="function-name">init</span>()
YourSceneName.super.<span class="function-name">init</span>(self)
<span class="comment">--[Your code here]--
</span><span class="keyword">end</span></pre>
</dd>
<dt>
<a name = "noblescene:enter"></a>
<span class="item-name">noblescene:enter()<span>
</dt>
<dd>
Implement if you want to run code as the transition to this scene begins, such as UI animation, triggers, etc.
<h3>Usage</h3>
<pre class="example"><span class="keyword">function</span> YourSceneName:<span class="function-name">enter</span>()
YourSceneName.super.<span class="function-name">enter</span>(self)
<span class="comment">--[Your code here]--
</span><span class="keyword">end</span></pre>
</dd>
<dt>
<a name = "noblescene:start"></a>
<span class="item-name">noblescene:start()<span>
</dt>
<dd>
Implement if you have code to run once the transition to this scene is complete. This method signifies the full activation of a scene. If this scene's <a href="../classes/NobleScene.html#noblescene.inputHandler">inputHandler</a> is defined, it is enabled now.
<h3>See</h3>
<ul>
<a href="../classes/NobleScene.html#noblescene.inputHandler">inputHandler</a>
</ul>
<h3>Usage</h3>
<pre class="example"><span class="keyword">function</span> YourSceneName:<span class="function-name">start</span>()
YourSceneName.super.<span class="function-name">start</span>(self)
<span class="comment">--[Your code here]--
</span><span class="keyword">end</span></pre>
</dd>
<dt>
<a name = "noblescene:update"></a>
<span class="item-name">noblescene:update()<span>
</dt>
<dd>
Implement to run scene-specific code on every frame while this scene is active.
<strong>NOTE:</strong> you may use coroutine.yield() here, because it only runs inside of playdate.update(), which is a coroutine.
<h3>Usage</h3>
<pre class="example"><span class="keyword">function</span> YourSceneName:<span class="function-name">update</span>()
YourSceneName.super.<span class="function-name">update</span>(self)
<span class="comment">--[Your code here]--
</span><span class="keyword">end</span></pre>
</dd>
<dt>
<a name = "noblescene:drawBackground"></a>
<span class="item-name">noblescene:drawBackground(__x, __y, __width, __height)<span>
</dt>
<dd>
Implement this function to draw background visual elements in your scene.
This runs when the engine need to redraw a background area.
By default it runs every frame and fills the background with self.backgroundColor. All arguments are optional.
Use <code>Graphics.sprite.setAlwaysRedraw(false)</code> after <code>Noble.new()</code> to optimize partial redraw.
<h3>Parameters</h3>
<ul class="parameters">
<li><span class="parameter">__x</span>
<br/>
</li>
<li><span class="parameter">__y</span>
<br/>
</li>
<li><span class="parameter">__width</span>
<br/>
</li>
<li><span class="parameter">__height</span>
<br/>
</li>
</ul>
<h3>Usage</h3>
<pre class="example"><span class="keyword">function</span> YourSceneName:<span class="function-name">drawBackground</span>(__x, __y, __width, __height)
YourSceneName.super.<span class="function-name">drawBackground</span>(self) <span class="comment">-- optional, invokes default behavior.
</span> <span class="comment">--[Your code here]--
</span><span class="keyword">end</span></pre>
</dd>
<dt>
<a name = "noblescene:exit"></a>
<span class="item-name">noblescene:exit()<span>
</dt>
<dd>
Implement this in your scene if you have "goodbye" code to run when a transition to another scene
begins, such as UI animation, saving to disk, etc.
<h3>Usage</h3>
<pre class="example"><span class="keyword">function</span> YourSceneName:<span class="function-name">exit</span>()
YourSceneName.super.<span class="function-name">exit</span>(self)
<span class="comment">--[Your code here]--
</span><span class="keyword">end</span></pre>
</dd>
<dt>
<a name = "noblescene:finish"></a>
<span class="item-name">noblescene:finish()<span>
</dt>
<dd>
Implement this in your scene if you have code to run when a transition to another scene
is complete, such as resetting variables.
<h3>Usage</h3>
<pre class="example"><span class="keyword">function</span> YourSceneName:<span class="function-name">finish</span>()
YourSceneName.super.<span class="function-name">finish</span>(self)
<span class="comment">--[Your code here]--
</span><span class="keyword">end</span></pre>
</dd>
<dt>
<a name = "noblescene:pause"></a>
<span class="item-name">noblescene:pause()<span>
</dt>
<dd>
<code>pause()</code> / <code>resume()</code></p>
<p> Implement one or both of these in your scene if you want something to happen when the game is paused/unpaused
by the system. The Playdate SDK does not require you to write pause logic, but these are useful if you want a
custom menu image (see Playdate SDK for more details), want to obscure game elements to prevent players from
cheating in a time-sensitive game, want to count the number of times the player pauses the game, etc.
<h3>Usage</h3>
<pre class="example"><span class="keyword">function</span> YourSceneName:<span class="function-name">pause</span>()
YourSceneName.super.<span class="function-name">pause</span>(self)
<span class="comment">--[Your code here]--
</span><span class="keyword">end</span></pre>
</dd>
<dt>
<a name = "noblescene:resume"></a>
<span class="item-name">noblescene:resume()<span>
</dt>
<dd>
<span></span>
<h3>Usage</h3>
<pre class="example"><span class="keyword">function</span> YourSceneName:<span class="function-name">resume</span>()
YourSceneName.super.<span class="function-name">resume</span>(self)
<span class="comment">--[Your code here]--
</span><span class="keyword">end</span></pre>
</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>