🪄 phaser-tile-animator

🧱 A lightweight, dependency-free Phaser 3 plugin that animates Tiled tilesets directly inside your game — no need for custom frame logic or sprite hacks.

🚀 Features

• 🎨 Supports Tiled animated tiles out of the box (tileData.animation in exported JSON)
• ⚡ Optimized — updates only the tiles that actually animate (no per-frame scans)
• 🕹️ Easy API — just call this.tileAnimator.init(map)
• ⏯️ pause() / resume() / destroy() built-in
• 🧩 Works as a Scene Plugin — automatically integrates with Phaser’s lifecycle
• 🧠 Written in TypeScript — ships with full type definitions

📦 Installation

npm install phaser-tile-animator

You must already have Phaser 3 installed:

npm install phaser

🧰 Setup

Add the plugin to your Phaser game configuration:

import { TileAnimatorPlugin } from 'phaser-tile-animator'

const config: Phaser.Types.Core.GameConfig = {
  type: Phaser.AUTO,
  width: 800,
  height: 600,
  scene: [GameScene],
  plugins: {
    scene: [
      {
        key: 'TileAnimatorPlugin',
        plugin: TileAnimatorPlugin,
        mapping: 'tileAnimator' // accessible via this.tileAnimator
      }
    ]
  }
}

export default new Phaser.Game(config)

🎮 Usage

In your scene:

export class GameScene extends Phaser.Scene {
  create() {
    const map = this.make.tilemap({ key: 'map' })
    const tileset = map.addTilesetImage('beach', 'beach')
    map.createLayer('Ground', tileset, 0, 0)

    // 🎞️ Start tile animations
    this.tileAnimator.init(map)
    
    // 🎚️ Set animation framerate (default is 10 FPS)
    this.tileAnimator.setFrameRate(30) // 30 FPS for smooth animations
  }

  update() {
    // You can pause/resume animations anytime:
    this.tileAnimator.pause()
    this.tileAnimator.resume()
    
    // Or adjust framerate dynamically:
     this.tileAnimator.setFrameRate(60) // Speed up to 60 FPS
     this.tileAnimator.setFrameRate(5)  // Slow down to 5 FPS
  }
}

⚙️ API

| Method | Description | | ------------------------------------ | ------------------------------------------------------- | | init(map: Phaser.Tilemaps.Tilemap) | Reads Tiled animation data and starts animating tiles. | | pause() | Temporarily freezes all tile animations. | | resume() | Resumes paused animations. | | setFrameRate(fps: number) | Sets the absolute framerate for all animations (e.g., 10, 30, 60 FPS). | | getFrameRate() | Gets the current framerate in FPS. | | destroy() | Stops listening to scene updates and clears references. |

⚡ How It Works

TileAnimator reads tileData from each tileset (as exported by Tiled) and caches references to all tiles that need animation. Each frame, it updates only those tiles based on the durations defined in your .json map.

Performance: even large maps with hundreds of tiles animate smoothly, since each tile’s position is pre-cached at startup.

🧪 Example Tiled JSON snippet

"tileData" : {
  "8": {
    "animation": [
      { "duration": 350, "tileid": 8 },
      { "duration": 350, "tileid": 12 },
      { "duration": 350, "tileid": 16 }
    ]
  }
}

🧠 Tips

• Works best with embedded tilesets in your map JSON (via Map → Embed Tilesets in Tiled).
• Supports multiple tilesets automatically.
• Use pause() when showing menus or paused screens.
• Combine with global shaders or lighting for cool water/fire effects.

🧩 TypeScript Support

Full typings are included out of the box.

import { TileAnimator, TileAnimatorPlugin } from 'phaser-tile-animator'

📜 License

MIT © 2025 Matteo Franchini Made with ❤️ for the Phaser community.

🌟 Support

If you like the plugin, consider starring it on GitHub — it helps others discover it too!