Skip to content

Document that animated NobleSprites need setSize(), and that NobleSprite:draw() is a render callback #97

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ericlewis wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Document that animated NobleSprites need setSize(), and that NobleSprite:draw() is a render callback #97

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 34 additions & 4 deletions .docs/classes/NobleSprite.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ <h3>Fields</h3>
<h3>Methods</h3>
<ul>
<li><a href="#noblesprite:init">noblesprite:init</a></li>
<li><a href="#noblesprite:draw">noblesprite:draw</a></li>
<li><a href="#noblesprite:play">noblesprite:play</a></li>
<li><a href="#noblesprite:pause">noblesprite:pause</a></li>
<li><a href="#noblesprite:stop">noblesprite:stop</a></li>
Expand Down Expand Up @@ -112,7 +113,9 @@ <h2 class="section-header "><a name="Methods"></a>Methods</h2>
<span class="item-name">noblesprite:init([__view[, __viewIsSpritesheet=false[, __singleState=false[, __singleStateLoop=true]]]])<span>
</dt>
<dd>
Do not call an "init" method directly. Use <code>NobleSprite()</code> (see usage examples).
Do not call an "init" method directly. Use <code>NobleSprite()</code> (see usage examples).</p>

<p> <strong>NOTE:</strong> When <code>__view</code> is the path to an image file, or a <code>Graphics.image</code> object, the sprite's size is set automatically via <code>setImage()</code>. When <code>__view</code> is the path to a spritesheet/imagetable file, or a <a href="../modules/Noble.Animation.html#">Noble.Animation</a> object, the sprite's size is <em>not</em> set automatically. You must call <code>setSize(width, height)</code> with the dimensions of a single animation frame, or the sprite will never be drawn.

<h3>Parameters</h3>
<ul class="parameters">
Expand Down Expand Up @@ -152,13 +155,17 @@ <h3>See</h3>

<h3>Usage</h3>
<pre class="example"><span class="comment">-- Provide a spritesheet image file to create a new <a href="../modules/Noble.Animation.html#">Noble.Animation</a> for a NobleSprite's view.
</span>myNobleSprite = <span class="function-name">NobleSprite</span>(<span class="string">"path/to/spritesheet"</span>, <span class="keyword">true</span>)</pre>
</span><span class="comment">-- Sprites with animation views do not have their size set automatically,
</span><span class="comment">-- so call setSize() with the dimensions of a single frame.
</span>myNobleSprite = <span class="function-name">NobleSprite</span>(<span class="string">"path/to/spritesheet"</span>, <span class="keyword">true</span>)
myNobleSprite:<span class="function-name">setSize</span>(<span class="number">32</span>, <span class="number">32</span>)</pre>
<pre class="example"><span class="comment">-- Provide an image file to create a new <code>Graphics.image</code> for a NobleSprite's view.
</span>myNobleSprite = <span class="function-name">NobleSprite</span>(<span class="string">"path/to/image"</span>)</pre>
<pre class="example"><span class="comment">-- Use an existing <a href="../modules/Noble.Animation.html#">Noble.Animation</a> for a NobleSprite's view.
</span> <span class="keyword">local</span> myAnimation = Noble.Animation.<span class="function-name">new</span>(<span class="string">"path/to/spritesheet"</span>)
myAnimation:<span class="function-name">addState</span>(<span class="string">"default"</span>, <span class="number">1</span>, animation.imageTable:<span class="function-name">getLength</span>(), <span class="keyword">nil</span>, <span class="keyword">true</span>)
myNobleSprite = <span class="function-name">NobleSprite</span>(myAnimation)</pre>
myNobleSprite = <span class="function-name">NobleSprite</span>(myAnimation)
myNobleSprite:<span class="function-name">setSize</span>(<span class="number">32</span>, <span class="number">32</span>) <span class="comment">-- The dimensions of a single frame.</span></pre>
<pre class="example"><span class="comment">-- Use an existing <code>Graphics.image</code> object for a NobleSprite's view.
</span> <span class="keyword">local</span> myImage = Graphics.image.<span class="function-name">new</span>(<span class="string">"path/to/image"</span>)
myNobleSprite = <span class="function-name">NobleSprite</span>(myImage)</pre>
Expand All @@ -170,12 +177,35 @@ <h3>Usage</h3>

<span class="keyword">function</span> MyCustomSprite:<span class="function-name">init</span>(__x, __y, __anotherFunArgument)
MyCustomSprite.super.<span class="function-name">init</span>(self, <span class="string">"path/to/spritesheet"</span>, <span class="keyword">true</span>)
<span class="comment">-- Etc. etc.
self:<span class="function-name">setSize</span>(<span class="number">32</span>, <span class="number">32</span>) <span class="comment">-- The dimensions of a single frame.
</span> <span class="comment">-- Etc. etc.
</span><span class="keyword">end</span>

<span class="comment">-- MyNobleScene.lua
</span>myNobleSprite = <span class="function-name">MyCustomSprite</span>(<span class="number">100</span>, <span class="number">100</span>, <span class="string">"Fun!"</span>)</pre>

</dd>
<dt>
<a name = "noblesprite:draw"></a>
<span class="item-name">noblesprite:draw()<span>
</dt>
<dd>
Do not call this method directly.</p>

<p> This method is the sprite's draw callback (see <code>playdate.graphics.sprite:draw()</code> in the Playdate SDK), which is invoked by <code>Graphics.sprite.update()</code> whenever this sprite is marked dirty. It runs in sprite-local coordinates, where (0, 0) is the top-left corner of the sprite's bounds, so calling it manually will not draw this sprite at its position in the scene.</p>

<p> To draw an animation directly to the screen without adding a sprite to the scene ("immediate mode"), use <code>myNobleSprite.animation:draw(x, y)</code> instead. To place an animated NobleSprite in a scene, use <code>setSize()</code> and <code>add(x, y)</code>.




<h3>See</h3>
<ul>
<li><a href="../modules/Noble.Animation.html#animation:draw">Noble.Animation:draw</a></li>
<li><a href="../classes/NobleSprite.html#noblesprite:add">NobleSprite:add</a></li>
</ul>


</dd>
<dt>
<a name = "noblesprite:play"></a>
Expand Down
4 changes: 3 additions & 1 deletion .docs/modules/Noble.Animation.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,7 +99,9 @@ <h2 class="section-header "><a name="Setup"></a>Setup </h2>
<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>.
Create a new animation "state machine". This function is called automatically when creating a new <a href="../classes/NobleSprite.html#">NobleSprite</a>.</p>

<p> <strong>NOTE:</strong> When using a <a href="../modules/Noble.Animation.html#">Noble.Animation</a> as the view for a <a href="../classes/NobleSprite.html#">NobleSprite</a>, the sprite's size is not set automatically; call the sprite's <code>setSize()</code> method with the dimensions of a single animation frame.

<h3>Parameters</h3>
<ul class="parameters">
Expand Down
2 changes: 2 additions & 0 deletions modules/Noble.Animation.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ Noble.Animation = {}
-- @section setup

--- Create a new animation "state machine". This function is called automatically when creating a new `NobleSprite`.
--
-- <strong>NOTE:</strong> When using a `Noble.Animation` as the view for a `NobleSprite`, the sprite's size is not set automatically; call the sprite's `setSize()` method with the dimensions of a single animation frame.
-- @string __view This can be: the path to a spritesheet image file or an image table object (`Graphics.imagetable`). See Playdate SDK docs for imagetable file naming conventions.
-- @return `animation`, a new animation object.
-- @usage
Expand Down
14 changes: 14 additions & 0 deletions modules/NobleSprite.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,14 +11,19 @@ NobleSprite = {}
class("NobleSprite").extends(Graphics.sprite)

--- Do not call an "init" method directly. Use `NobleSprite()` (see usage examples).
--
-- <strong>NOTE:</strong> When `__view` is the path to an image file, or a `Graphics.image` object, the sprite's size is set automatically via `setImage()`. When `__view` is the path to a spritesheet/imagetable file, or a `Noble.Animation` object, the sprite's size is <em>not</em> set automatically. You must call `setSize(width, height)` with the dimensions of a single animation frame, or the sprite will never be drawn.
-- @string[opt] __view This can be: the path to an image or spritesheet image file, an image object (`Graphics.image`) or an animation object (`Noble.Animation`)
-- @bool[opt=false] __viewIsSpritesheet Set this to `true` to indicate that `__view` is a spritesheet. Will only be considered if `__view` is a string path to an image.
-- @bool[opt=false] __singleState If this sprite has just one animation, set this to true. It saves you from having to use Noble.Animation.addState()
-- @bool[opt=true] __singleStateLoop If using a single state animation, should it loop?
--
-- @usage
-- -- Provide a spritesheet image file to create a new `Noble.Animation` for a NobleSprite's view.
-- -- Sprites with animation views do not have their size set automatically,
-- -- so call setSize() with the dimensions of a single frame.
-- myNobleSprite = NobleSprite("path/to/spritesheet", true)
-- myNobleSprite:setSize(32, 32)
--
-- @usage
-- -- Provide an image file to create a new `Graphics.image` for a NobleSprite's view.
Expand All @@ -29,6 +34,7 @@ class("NobleSprite").extends(Graphics.sprite)
-- local myAnimation = Noble.Animation.new("path/to/spritesheet")
-- myAnimation:addState("default", 1, animation.imageTable:getLength(), nil, true)
-- myNobleSprite = NobleSprite(myAnimation)
-- myNobleSprite:setSize(32, 32) -- The dimensions of a single frame.
--
-- @usage
-- -- Use an existing `Graphics.image` object for a NobleSprite's view.
Expand All @@ -44,6 +50,7 @@ class("NobleSprite").extends(Graphics.sprite)
--
-- function MyCustomSprite:init(__x, __y, __anotherFunArgument)
-- MyCustomSprite.super.init(self, "path/to/spritesheet", true)
-- self:setSize(32, 32) -- The dimensions of a single frame.
-- -- Etc. etc.
-- end
--
Expand Down Expand Up @@ -97,6 +104,13 @@ function NobleSprite:init(__view, __viewIsSpritesheet, __singleState, __singleSt

end

--- Do not call this method directly.
--
-- This method is the sprite's draw callback (see `playdate.graphics.sprite:draw()` in the Playdate SDK), which is invoked by `Graphics.sprite.update()` whenever this sprite is marked dirty. It runs in sprite-local coordinates, where (0, 0) is the top-left corner of the sprite's bounds, so calling it manually will not draw this sprite at its position in the scene.
--
-- To draw an animation directly to the screen without adding a sprite to the scene ("immediate mode"), use `myNobleSprite.animation:draw(x, y)` instead. To place an animated NobleSprite in a scene, use `setSize()` and `add(x, y)`.
-- @see Noble.Animation:draw
-- @see NobleSprite:add
function NobleSprite:draw()
if (self.animation ~= nil) then
self.animation:draw()
Expand Down