From 8ba99e63f4fa334972654909c552b81784274187 Mon Sep 17 00:00:00 2001
From: Eric Lewis <ericlewis777@gmail.com>
Date: Tue, 11 Aug 2026 04:10:47 -0400
Subject: [PATCH] Document that animated NobleSprites need setSize(), and that
 NobleSprite:draw() is a render callback.

Sprites whose view is a spritesheet/imagetable or a Noble.Animation do
not get their size set automatically (unlike image-based sprites, which
are auto-sized via setImage()), so they must call setSize() with the
frame dimensions or they will never be drawn. The spritesheet usage
examples now include the setSize() call, and Noble.Animation.new()
notes it as well. (upstream issue #83)

NobleSprite:draw() is now documented as the sprite draw callback
invoked by Graphics.sprite.update() in sprite-local coordinates, which
must not be called manually; use myNobleSprite.animation:draw(x, y) for
immediate-mode drawing, or setSize() plus add(x, y) for scene
placement. (upstream issue #91)

The generated HTML docs were hand-patched to match, since ldoc is not
available in this environment.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .docs/classes/NobleSprite.html     | 38 ++++++++++++++++++++++++++----
 .docs/modules/Noble.Animation.html |  4 +++-
 modules/Noble.Animation.lua        |  2 ++
 modules/NobleSprite.lua            | 14 +++++++++++
 4 files changed, 53 insertions(+), 5 deletions(-)

diff --git a/.docs/classes/NobleSprite.html b/.docs/classes/NobleSprite.html
index ab54f0b..d528b55 100644
--- a/.docs/classes/NobleSprite.html
+++ b/.docs/classes/NobleSprite.html
@@ -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>
@@ -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">
@@ -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>
@@ -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>
diff --git a/.docs/modules/Noble.Animation.html b/.docs/modules/Noble.Animation.html
index ab9fad8..5434d47 100644
--- a/.docs/modules/Noble.Animation.html
+++ b/.docs/modules/Noble.Animation.html
@@ -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">
diff --git a/modules/Noble.Animation.lua b/modules/Noble.Animation.lua
index 1e7e84e..f9d96ba 100644
--- a/modules/Noble.Animation.lua
+++ b/modules/Noble.Animation.lua
@@ -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
diff --git a/modules/NobleSprite.lua b/modules/NobleSprite.lua
index 4e929f4..08cc0ba 100644
--- a/modules/NobleSprite.lua
+++ b/modules/NobleSprite.lua
@@ -11,6 +11,8 @@ 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()
@@ -18,7 +20,10 @@ class("NobleSprite").extends(Graphics.sprite)
 --
 -- @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.
@@ -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.
@@ -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
 --
@@ -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()