<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0"><channel><title><![CDATA[Arbnor's Sprite Notes]]></title><description><![CDATA[Arbnor's Sprite Notes]]></description><link>https://arbnor.hashnode.dev</link><generator>RSS for Node</generator><lastBuildDate>Fri, 20 Nov 2026 16:49:20 GMT</lastBuildDate><atom:link href="https://arbnor.hashnode.dev/rss.xml" rel="self" type="application/rss+xml"/><language><![CDATA[en]]></language><ttl>60</ttl><item><title><![CDATA[Six Phaser 3 sprite animation bugs and how to fix them]]></title><description><![CDATA[Fixes for six common Phaser 3 sprite animation bugs: empty animations, missing textures, frame timing, pivots, restarting attacks and blurry pixels.]]></description><link>https://arbnor.hashnode.dev/six-phaser-3-sprite-animation-bugs-and-how-to-fix-them</link><guid isPermaLink="true">https://arbnor.hashnode.dev/six-phaser-3-sprite-animation-bugs-and-how-to-fix-them</guid><category><![CDATA[phaser]]></category><category><![CDATA[GameDev]]></category><category><![CDATA[JavaScript]]></category><dc:creator><![CDATA[Arbnor Avarello]]></dc:creator><pubDate>Fri, 06 Nov 2026 06:32:32 GMT</pubDate><content:encoded><![CDATA[<p>Most Phaser 3 sprite animation problems come down to a few causes. Here they are with their fixes, tested on Phaser <code>3.90.0</code> with a JSON Hash atlas (one PNG plus one JSON per animation, frames of 256 × 256, 8 per row).</p>
<h2>1. The animation is empty: <code>Frame "idle-00" not found</code></h2>
<pre><code class="language-js">this.anims.create({
  key: 'idle',
  frames: this.anims.generateFrameNames('knight-idle', { prefix: 'idle-', start: 0, end: 15, zeroPad: 2 }),
  frameRate: 8,
  repeat: -1,
});
</code></pre>
<p>If the frames in the JSON are called <code>moss-knight-idle-00</code>, this prefix matches nothing. <code>generateFrameNames</code> then returns an empty list without throwing an error, and the console logs <code>Frame "idle-00" not found in texture "knight-idle"</code> once per frame.</p>
<p><strong>Fix:</strong> print the names Phaser actually loaded, and copy the prefix from that list:</p>
<pre><code class="language-js">console.log(this.textures.get('knight-idle').getFrameNames());
</code></pre>
<p>Check <code>zeroPad</code> and <code>end</code> while you're at it. A 16-frame idle ends at <code>15</code>, not <code>16</code>.</p>
<h2>2. Only a green box with a slash appears</h2>
<p>That box is Phaser's missing-texture placeholder: the PNG or the JSON returned a 404. Two things cause most of these:</p>
<ul>
<li><strong>Paths are relative to the page, not to the script.</strong> <code>assets/knight.png</code> resolves against <code>index.html</code>.</li>
<li><code>file://</code> <strong>blocks the JSON request.</strong> Serve the folder over HTTP (<code>python -m http.server</code> is enough) instead of double-clicking the HTML file.</li>
</ul>
<p>The network tab shows which file failed.</p>
<h2>3. Every frame plays for the same time, even though the JSON says otherwise</h2>
<p>Exporters often write a per-frame <code>duration</code> in milliseconds, so an attack can hold its wind-up longer than the swing. Phaser keeps unknown frame fields in <code>customData</code> and ignores them during playback. <code>frameRate</code> then gives every frame the same time.</p>
<p><strong>Fix:</strong> pass each frame's duration yourself:</p>
<pre><code class="language-js">const tex = this.textures.get('knight-attack');
this.anims.create({
  key: 'attack',
  frames: tex.getFrameNames().sort().map((frame) =&gt; ({
    key: 'knight-attack',
    frame,
    duration: tex.get(frame).customData?.duration,
  })),
  repeat: 0,
});
</code></pre>
<p>Don't override <code>frameRate</code> in <code>play()</code> for this animation: on 3.90, a <code>play()</code> frame rate that differs from the animation's own makes Phaser skip the per-frame values. The meaning of a per-frame <code>duration</code> also changed across 3.x. Up to 3.70 it is added on top of the base frame time; from 3.80 it replaces it. On an older version, subtract the base time from each value.</p>
<p><code>getFrameNames()</code> does not guarantee any order. With zero-padded names, <code>.sort()</code> puts them back in sequence. With unpadded names (<code>-1</code>, <code>-10</code>, <code>-2</code>) a string sort scrambles them, so pad the names when you export or sort numerically.</p>
<h2>4. The feet sink into the ground or float, and <code>setOrigin</code> doesn't help</h2>
<pre><code class="language-js">this.knight = this.add.sprite(256, groundY, 'knight-idle', 'moss-knight-idle-00');
this.knight.setOrigin(0.5, 1); // looks right... until the first frame change
</code></pre>
<p>If the atlas has a <code>pivot</code> field, Phaser sets the origin from that pivot every time the frame changes. In my test the origin was <code>0.5, 1</code> for the first frame only, then <code>0.5, 0.875</code> for the rest of the animation, which is exactly the pivot in the JSON.</p>
<p><strong>Fix:</strong> don't fight it. Treat the pivot as the foot point and put the sprite's y on the ground line. If your sheets have empty space below the feet, change the pivot in the data, not the origin in code. Give every animation of a character the same pivot, and switching from idle to attack won't make the feet jump.</p>
<h2>5. The attack restarts or never finishes</h2>
<pre><code class="language-js">this.input.keyboard.on('keydown-SPACE', () =&gt; this.knight.play('attack'));
</code></pre>
<p>Every key press (and key repeat) restarts the attack from frame 0, so mashing space shows only the first two frames. Nothing ever returns to idle either.</p>
<p><strong>Fix:</strong> guard the one-shot action and go back to idle when it completes:</p>
<pre><code class="language-js">this.knight.on(Phaser.Animations.Events.ANIMATION_COMPLETE, (anim) =&gt; {
  if (anim.key === 'attack') this.knight.play('idle');
});

this.input.keyboard.on('keydown-SPACE', () =&gt; {
  if (this.knight.anims.currentAnim?.key !== 'attack') this.knight.play('attack');
});
</code></pre>
<p><code>ANIMATION_COMPLETE</code> never fires for loops (<code>repeat: -1</code>), so idle and walk are unaffected. <code>play(key, true)</code> ignores the call when that animation is already running, so <code>this.knight.play('attack', true)</code> is another way to stop the restarts; it's also the usual call for loops in an update loop. Skip <code>.chain('idle')</code> inside the key handler: every press queues another entry.</p>
<h2>6. Pixel art is blurry, or shimmers when it moves</h2>
<p>Phaser smooths textures when it scales them. For pixel art, turn that off in the game config:</p>
<pre><code class="language-js">new Phaser.Game({
  type: Phaser.AUTO,
  width: 512,
  height: 320,
  render: { pixelArt: true, roundPixels: true },
  scene: Demo,
});
</code></pre>
<p><code>pixelArt</code> switches to nearest-neighbour filtering. <code>roundPixels</code> snaps sprites to whole pixels, so a slow camera pan stops shimmering. Leave both off for painted, high-resolution sprites; there, smoothing looks better.</p>
<h2>Bonus: an idle that looks fake</h2>
<p>This one isn't a code bug. A "breathing" idle made by scaling one frame up and down by a few percent looks fine as a thumbnail and fake in a game, because the whole body pulses, feet included. A real idle moves the chest and shoulders while the feet stay planted. I shipped the scaled kind in a sample pack first and replaced it with a 16-frame idle that moves.</p>
<hr />
<p>I make SpriteCanvas, an AI sprite sheet generator, and these bugs came up while testing its exports in Phaser. The longer walkthrough, with loading, every animation and the full scene, is on its docs: <a href="https://spritecanvas.com/docs/phaser-sprite-sheet-animation/">Phaser sprite sheet animation</a>. The knight in the examples is from a <a href="https://spritecanvas.itch.io/free-cc0-fantasy-sprite-sheets">free CC0 pack on itch.io</a> (AI-generated art).</p>
]]></content:encoded></item></channel></rss>