Intro​

As your game grows, so does the complexity of its logic.

Enemies need to react to the player. Animations need to trigger damage. AI systems need to coordinate state changes. UI needs to update when something happens — but that “something” might come from anywhere.

One approach is direct calls:

ts
enemy.takeDamage(10);
enemy.die();
hud.updateHealth();
sound.play();
Copy

ts
enemy.takeDamage(10);
enemy.die();
hud.updateHealth();
sound.play();
Copy

This works… until it doesn’t.

Suddenly everything knows about everything else. A small change in one system ripples through your entire codebase. Reuse becomes difficult. Debugging becomes painful.

This is where event-driven architecture shines — and ExcaliburJS provides a powerful, flexible event system that can be used as a tool to connect different systems.

In this article, we’ll explore:

• What Excalibur’s event framework actually gives you
• Why publish/subscribe (pub/sub) patterns matter in games
• Practical, real-world use cases
• And how to model gameplay events, not just callbacks

Events are a tool. Any tool can help you solve a specific set of problems. As with any other tool, if you start applying this solution to the wrong problems, there are potential foot-guns. We will discuss this a bit.

What Is Pub/Sub (and Why It Fits Games So Well)​

At its core, Excalibur’s event system follows a publish/subscribe model:

• One system emits an event
• Zero or more systems listen for it
• The publisher has no knowledge of who’s listening — or if anyone is at all

This decoupling is incredibly valuable in games, where many systems often react to the same stimulus.

Benefits of Pub/Sub in Game Architecture​

1. Loose Coupling

   Your listening systems don't need to know about the emitter. For example: Your UI doesn’t need to know about combat math. They just react to events.

2. Semantic Meaning

   Events turn low-level mechanics into high-level intent:

   "collisionstart" → "enemySpotted"

   "frame" → "attackHit"

   hp <= 0" → "died"

3. Fan-Out by Default

   One event can trigger:

   • Sound
   • Visual effects
   • State changes
   • Analytics

   …without a single direct dependency.

4. Easier Iteration

   Want to add screen shake on hit? Just listen to an event — no refactors required.

Events in ExcaliburJS (A Quick Mental Model)​

Almost everything in Excalibur has an .events property:

• Actor
• Scene
• Engine
• Animation

And you can:

• Listen with .on(...)
• Remove with .off(...)
• Emit with .emit(...)
• Create your own typed event emitters

This makes Excalibur events ideal for gameplay signaling, not just engine hooks. The two HUGE benefits with using the emitter is built-in type safety and leverage native IDE tools like Intellisense with autocomplete. This is a big quality of life feature.

The Three Pillars of ExcaliburJS Events​

Excalibur’s event system is deceptively simple on the surface — but when used properly with TypeScript, it becomes a strongly-typed, scalable messaging system.

Everything builds on three pillars:

1. Event type definitions
2. Extending GameEvents
3. Const declaration event maps

Once you understand how these fit together, you can confidently model almost any gameplay interaction.

1. Event Type Definitions​

At the most basic level, Excalibur events are just named signals with payloads. We can use an event interface to map the semantic event names to the actual GameEvents that are emitted.

ts
interface DetectionEvents {
  targetDetected: TargetDetectedEvent,
  targetLost: TargetLostEvent,
}
Copy

ts
interface DetectionEvents {
  targetDetected: TargetDetectedEvent,
  targetLost: TargetLostEvent,
}
Copy

This event map answers two questions:

1. What events can be emitted?
2. Which events are mapped?

2. Extending GameEvents​

Then you define the specific events and their payloads.

ts
export class TargetDetectedEvent extends  ex.GameEvent<EnemyDetector> {
  constructor(public target: Actor) {
    super();
  }
}
export class TargetLostEvent extends  ex.GameEvent<EnemyDetector> {
  constructor(public target: Actor) {
    super();
  }
}
Copy

ts
export class TargetDetectedEvent extends  ex.GameEvent<EnemyDetector> {
  constructor(public target: Actor) {
    super();
  }
}
export class TargetLostEvent extends  ex.GameEvent<EnemyDetector> {
  constructor(public target: Actor) {
    super();
  }
}
Copy

3. Const Declaration (optional, but improves DevX)​

Declaring the events 'as const' provices replacing magic strings with enum-like behaviors.

ts
export const DetectionEvents = {
  targetDetected: "targetDetected",
  targetLost: "targetLost",
} as const;
Copy

ts
export const DetectionEvents = {
  targetDetected: "targetDetected",
  targetLost: "targetLost",
} as const;
Copy

The events are ready to use!

Using the events​

Here's how to use these as extensions of Actor events (one way to use them)

ts
export class EnemyDetector extends ex.Actor {
  public events = new  ex.EventEmitter<ex.ActorEvents & DetectionEvents>(); // this combines the native event actor events with your new custom events
  public onPostUpdate() {
    if (playerSeen) { // This is your local logic for finding the player
      this.events.emit(DetectionEvents.targetDetected, new TargetDetectedEvent(ActorThatWasSeen));  //pass the actor
    }
    if(previouslyDetectedPlayerGone){ // This is your local logic for when previously detected player leaves
      this.events.emit(DetectionEvents.targetLost, new TargetLostEvent(ActorThatWasSeen));  //pass the actor
    }
  }
}
Copy

ts
export class EnemyDetector extends ex.Actor {
  public events = new  ex.EventEmitter<ex.ActorEvents & DetectionEvents>(); // this combines the native event actor events with your new custom events
  public onPostUpdate() {
    if (playerSeen) { // This is your local logic for finding the player
      this.events.emit(DetectionEvents.targetDetected, new TargetDetectedEvent(ActorThatWasSeen));  //pass the actor
    }
    if(previouslyDetectedPlayerGone){ // This is your local logic for when previously detected player leaves
      this.events.emit(DetectionEvents.targetLost, new TargetLostEvent(ActorThatWasSeen));  //pass the actor
    }
  }
}
Copy

ts
// in the publisher
this.events.emit("typingComplete", this.currentStringText);   
// in the subscriber
this.events.on('typingComplete', (e)=>{...});  // e is this.currentStringText
Copy

ts
// in the publisher
this.events.emit("typingComplete", this.currentStringText);   
// in the subscriber
this.events.on('typingComplete', (e)=>{...});  // e is this.currentStringText
Copy

Common Gameplay Use Cases for Events​

Here are some use cases and game dev patterns where Excalibur’s event system really shines:

• Perception systems (vision, hearing, proximity)
• AI state transitions
• Combat pipelines (chaining attacks!!!)
• Animation timing
• UI synchronization
• Cross-entity communication (enemy alarms!!!)
• Designer-friendly extensibility

Let’s walk through three concrete examples.

Use Case 1: Line-of-Sight as an Actor Component​

Line-of-sight detection is a perfect example of continuous logic that should emit discrete events.

Instead of asking every frame: “Can I see the player?”

We want:

• "targetSeen"
• "targetLost"

The Pattern: Line-of-Sight Component​

Instead of baking events directly into the Actor, we can encapsulate behavior in a component:

The LineOfSightComponent handles math, raycasts, and visibility checks.

It emits semantic events like seen or lost.

Other systems (AI, UI, audio) can respond without knowing the implementation details.

Define your component​

ts
// 1. Define the interface
interface LineOfSightEvents {
  seen: LOSActorDetectedEvent;
  lost: LOSactorLostEvent;
}
// 2. Extend GameEvents 
class LOSActorDetectedEvent extends ex.GameEvent<LineOfSightComponent>{
  constructor(detectedActor: ex.Actor){
    ...
  }
}
class LOSactorLostEvent extends ex.GameEvent<LineOfSightComponent>{
  constructor(detectedActor: ex.Actor){
    ...
  }
}
// 3. Const Declaration
 const LineOfSightEvents = {
 seen: 'seen',
 lost: 'lost',
} as const;
// 4. Usage
 class LineOfSightComponent extends ex.Component{
  events = new ex.EventEmitter<LineOfSightEvents>
  constructor(){}
  onPreUpdate(){
    if(...){  // I see something
      this.events.emit(LineOfSightEvents.seen, new LOSActorDetectedEvent(whatIsaw));
    }
    if(...){ // I don't see it anymore
      this.events.emit(LineOfSightEvents.lost, new LOSactorLostEvent(whatIUsedToSee));
    } 
  }
}
// My Actor
class MyDetectionActor extends ex.Actor{
  LOS:LineOfSightComponent;
  constructor(){
    super(...);
    this.LOS = new LineOfSightComponent();
    this.addComponent(this.LOS);
  }
  onInitialization(){
    this.LOS.events.on('seen', this.handleSeen);
    this.LOS.events.on('lost', this.hanldeLost);
  }
  handleSeen(){...}
  handleLost(){...}
}
Copy

ts
// 1. Define the interface
interface LineOfSightEvents {
  seen: LOSActorDetectedEvent;
  lost: LOSactorLostEvent;
}
// 2. Extend GameEvents 
class LOSActorDetectedEvent extends ex.GameEvent<LineOfSightComponent>{
  constructor(detectedActor: ex.Actor){
    ...
  }
}
class LOSactorLostEvent extends ex.GameEvent<LineOfSightComponent>{
  constructor(detectedActor: ex.Actor){
    ...
  }
}
// 3. Const Declaration
 const LineOfSightEvents = {
 seen: 'seen',
 lost: 'lost',
} as const;
// 4. Usage
 class LineOfSightComponent extends ex.Component{
  events = new ex.EventEmitter<LineOfSightEvents>
  constructor(){}
  onPreUpdate(){
    if(...){  // I see something
      this.events.emit(LineOfSightEvents.seen, new LOSActorDetectedEvent(whatIsaw));
    }
    if(...){ // I don't see it anymore
      this.events.emit(LineOfSightEvents.lost, new LOSactorLostEvent(whatIUsedToSee));
    } 
  }
}
// My Actor
class MyDetectionActor extends ex.Actor{
  LOS:LineOfSightComponent;
  constructor(){
    super(...);
    this.LOS = new LineOfSightComponent();
    this.addComponent(this.LOS);
  }
  onInitialization(){
    this.LOS.events.on('seen', this.handleSeen);
    this.LOS.events.on('lost', this.hanldeLost);
  }
  handleSeen(){...}
  handleLost(){...}
}
Copy

Use Case 2: Finite State Machines via Events​

State machines often start simple — and quickly become tangled.

ts
if (state === "idle" && seesPlayer) {
  state = "chase";
}
Copy

ts
if (state === "idle" && seesPlayer) {
  state = "chase";
}
Copy

Now multiply that across:

• Combat
• Damage
• Stuns
• Animations
• Death

Event-Driven FSMs​

Instead of polling conditions, let events drive transitions:

ts
enemy.events.on("playerSeen", () => fsm.transition("chase"));
enemy.events.on("tookDamage", () => fsm.transition("alert"));
enemy.events.on("lostPlayer", () => fsm.transition("search"));
Copy

ts
enemy.events.on("playerSeen", () => fsm.transition("chase"));
enemy.events.on("tookDamage", () => fsm.transition("alert"));
enemy.events.on("lostPlayer", () => fsm.transition("search"));
Copy

The FSM:

• Doesn’t know about physics
• Doesn’t know about raycasts
• Only reacts to meaningful signals

This pattern scales exceptionally well games that have scaled in size.

Use Case 3: Child Actors as Sensors (Extending Actor Events)​

Excalibur Actors already emit collision events — but sometimes you want specialized detection zones.

Instead of overloading the main actor:

• Add a child actor
• Give it its own collider
• Translate physics events into gameplay events

We will quickly revisit the example given earlier, focusing on how to combine the events with the Native Actor emittor.

ts
export class EnemyDetector extends ex.Actor {
  ...
  // this combines the native event actor events with your new custom events
  public events = new ex.EventEmitter< ex.ActorEvents & DetectionEvents>(); 
  
  ...
}
Copy

ts
export class EnemyDetector extends ex.Actor {
  ...
  // this combines the native event actor events with your new custom events
  public events = new ex.EventEmitter< ex.ActorEvents & DetectionEvents>(); 
  
  ...
}
Copy

This demonstrates two powerful ideas:

1. Extending actor behavior without inheritance
2. Using child actors as modular sensors

It’s especially effective for:

• Stealth games
• Traps
• Trigger zones
• Area-based AI awareness

Footguns and Pitfalls​

To be objective in this info, let's call out where a pub/sub system can go wrong.

When Not to Use Pub/Sub (and Why)​

Event-driven architecture is powerful — but it’s not free.

Just because Excalibur makes events easy doesn’t mean everything should be an event. Overusing pub/sub can introduce subtle bugs, obscure control flow, and make your game harder to reason about.

Here are the most common drawbacks — and how to recognize when pub/sub is the wrong tool.

1. Hidden Control Flow​

Events obscure sequence of operations, you don't have exact control over when and what order things happen.

If you have direct callbacks, you are in complete control of execution, with events, you hand that off to the event system. You can lose traceabilty of who all is listening to the event, and in what specific order the events are reacted to.

You no longer know:

• Who is listening
• In what order handlers run
• What side effects will occur

This can make debugging harder — especially when behavior changes “magically.” Events like this are 'one-way' so if you need some acknowledgement from a receiver, then an event is probably not the best design choice.

2. Debugging Can Become Non-Local​

An event emitted in one file may trigger behavior across different systems and components:

• Actors
• Components
• Scenes
• UI
• Audio systems

This can make tracking down something that breaks more complicated.

3. Overcomplicating simple tasks​

If you are connecting two elements, an event bus may be overkill and add unnecessary comlexity.

When Events are the right tool​

Use events when:

• Multiple systems may react
• You’re translating engine mechanics into gameplay meaning
• You want extensibility without refactors
• You’re modeling state changes, not actions

Avoid events when:

• Order is critical
• Only one system will ever care
• The caller needs a return value
• The logic is simple and local

Summary​

In this article, we explored the ExcaliburJS events feature.

We started by explaining the fundamentals of pub/sub systems and breaking down the three pillars of Excalibur’s event system. From there, we applied those ideas to an ECS component, using a LineOfSightComponent as a concrete example, tying events to triggering a Finite State Machine, and extending the native Actor events that already exist.

This is where Excalibur’s event model shines.

It’s not a global pub/sub free-for-all. It’s a scoped, typed messaging system that encourages:

• Local reasoning
• Explicit contracts
• Testable gameplay units
• Scalable architecture as projects grow

Events work best when they represent meaningful state transitions, not every frame-by-frame detail. When used this way, they become natural boundaries between systems — and those boundaries are what keep game code flexible, understandable, and fun to work in.

Why ExcaliburJS​

Small plug for the engine that makes this all possible:

ExcaliburJS is a friendly, TypeScript 2D game engine for the web. It's free and open source (FOSS), well documented, and has a growing community of developers building great games.

The SpriteFusion plugin is just one example of how Excalibur's architecture makes complex features feel natural. If you're interested in 2D web game development, check it out!

Join the Discord community for questions and support.

Intro​

Every 2D gamedev knows the pain: you've got a beautiful tilemap, but now you need to add gameplay elements. Where do enemies spawn? Which tiles are collectibles? What triggers that secret door?

The traditional solution? Maintain separate data structures, coordinate systems, and hope they stay in sync with your map. It's tedious, error-prone, and breaks the moment you resize your level.

In this post, I'll show you how the SpriteFusion tile attributes feature changes the game. With the updated ExcaliburJS SpriteFusion plugin, you can now embed custom JSON data directly into your tilemap — keeping your logic and layout in perfect harmony.

What Are Tile Attributes?​

Tile attributes let you attach custom JSON data to any tile in your SpriteFusion map. Think of it as adding metadata that travels with your tiles.

Instead of manually tracking "enemy at position (10, 6)" in your code, you mark that tile in SpriteFusion:

json
{
  "id": "1",
  "x": 10,
  "y": 6,
  "attributes": { 
    "entity": "mushroom",
    "health": 50,
    "drops": ["coin", "powerup"]
  }
}
Copy

json
{
  "id": "1",
  "x": 10,
  "y": 6,
  "attributes": { 
    "entity": "mushroom",
    "health": 50,
    "drops": ["coin", "powerup"]
  }
}
Copy

When your game loads, the plugin reads this data and hands it to you — ready to spawn entities, configure behaviors, or drive game logic.

Why This Matters​

Before Tile Attributes​

The old workflow looked like this:

1. Design your map in SpriteFusion
2. Export as JSON
3. Open your code editor
4. Manually add entity spawn data with hardcoded coordinates
5. Test the game
6. Realize you need to move something
7. Update both the map AND your spawn coordinates
8. Repeat forever

Result: Two sources of truth that constantly drift apart.

With Tile Attributes​

The new workflow:

1. Design your map in SpriteFusion
2. Add attributes directly to tiles where you want entities/logic
3. Export as JSON
4. Let the plugin handle everything

Result: One source of truth. Change your map, and your game logic updates automatically.

How It Works in SpriteFusion​

As of October 2025, SpriteFusion added tile attributes to their editor. Here's how to use them:

1. Select a tile in your map
2. Open the Tile Attributes panel
3. Add your JSON data — any valid JSON object works
4. Export as JSON (not "save" — the plugin needs the JSON export)

Your exported JSON now includes an attributes field:

json
{
  "tileSize": 16,
  "mapWidth": 30,
  "mapHeight": 12,
  "layers": [
    {
      "name": "ObjectLayer",
      "tiles": [
        { "id": "0", "x": 25, "y": 3, "attributes": { "entity": "bottle" } },
        { "id": "1", "x": 10, "y": 6, "attributes": { "entity": "mushroom" } },
        { "id": "5", "x": 4, "y": 4, "attributes": { "entity": "knight" } }
      ],
      "collider": false
    }
  ]
}
Copy

json
{
  "tileSize": 16,
  "mapWidth": 30,
  "mapHeight": 12,
  "layers": [
    {
      "name": "ObjectLayer",
      "tiles": [
        { "id": "0", "x": 25, "y": 3, "attributes": { "entity": "bottle" } },
        { "id": "1", "x": 10, "y": 6, "attributes": { "entity": "mushroom" } },
        { "id": "5", "x": 4, "y": 4, "attributes": { "entity": "knight" } }
      ],
      "collider": false
    }
  ]
}
Copy

The Updated Plugin API​

The ExcaliburJS SpriteFusion plugin now supports two powerful features for working with tile attributes:

1. Attribute Callbacks​

Pass a callback function to process tile attributes as the map loads:

typescript
const attributeCallback = (attData: TileAttributeData) => {
  const { tileData, mapData } = attData;
  const { attributes, x, y, id } = tileData;
  
  // Spawn entities based on attribute data
  if (attributes.entity === 'mushroom') {
    const enemy = new Mushroom({
      pos: vec(x * mapData.tileSize, y * mapData.tileSize),
      health: attributes.health || 50
    });
    game.add(enemy);
  }
};
const spriteFusionMap = new SpriteFusionResource({
  mapPath: './map/map.json',
  spritesheetPath: './map/spritesheet.png',
  tileAttributeFactory: attributeCallback
});
Copy

typescript
const attributeCallback = (attData: TileAttributeData) => {
  const { tileData, mapData } = attData;
  const { attributes, x, y, id } = tileData;
  
  // Spawn entities based on attribute data
  if (attributes.entity === 'mushroom') {
    const enemy = new Mushroom({
      pos: vec(x * mapData.tileSize, y * mapData.tileSize),
      health: attributes.health || 50
    });
    game.add(enemy);
  }
};
const spriteFusionMap = new SpriteFusionResource({
  mapPath: './map/map.json',
  spritesheetPath: './map/spritesheet.png',
  tileAttributeFactory: attributeCallback
});
Copy

The callback receives:

• tileData: The specific tile's data including id, x, y, and attributes
• mapData: The full map configuration for context

2. Object Layers​

Sometimes you want a layer purely for data — no visual tiles, just positions and attributes. That's what object layers are for.

Mark layers as object layers, and the plugin will:

• ✅ Parse all tile attributes and call your callback
• ❌ Skip rendering the layer as a visual tilemap

typescript
const spriteFusionMap = new SpriteFusionResource({
  mapPath: './map/map.json',
  spritesheetPath: './map/spritesheet.png',
  tileAttributeFactory: attributeCallback,
  objectLayers: ['ObjectLayer', 'SpawnPoints', 'Triggers']
});
Copy

typescript
const spriteFusionMap = new SpriteFusionResource({
  mapPath: './map/map.json',
  spritesheetPath: './map/spritesheet.png',
  tileAttributeFactory: attributeCallback,
  objectLayers: ['ObjectLayer', 'SpawnPoints', 'Triggers']
});
Copy

This is perfect for:

• Enemy spawn points
• Item placement
• Trigger zones
• Waypoint paths
• Anything that needs position data without visual tiles

A Complete Example: Enemy Spawner​

Let's walk through a practical example. We'll create a tilemap with embedded enemy data and spawn them automatically.

Step 1: Design Your Map​

In SpriteFusion:

1. Create a layer called "Enemies"
2. Place tiles where you want enemies to spawn
3. Add attributes to each tile:

json
{ "entity": "goblin", "patrol": true, "range": 3 }
{ "entity": "slime", "speed": 2 }
Copy

json
{ "entity": "goblin", "patrol": true, "range": 3 }
{ "entity": "slime", "speed": 2 }
Copy

Step 2: Set Up Your Entities​

typescript
class Goblin extends ex.Actor {
  constructor(config: { pos: Vector, patrol?: boolean, range?: number }) {
    super({
      pos: config.pos,
      width: 16,
      height: 16,
      color: ex.Color.Green
    });
    
    if (config.patrol) {
      this.setupPatrol(config.range || 2);
    }
  }
  
  setupPatrol(range: number) {
    // Add patrol behavior
  }
}
class Slime extends ex.Actor {
  constructor(config: { pos: Vector, speed?: number }) {
    super({
      pos: config.pos,
      width: 16,
      height: 16,
      color: ex.Color.Blue,
      vel: vec(config.speed || 1, 0)
    });
  }
}
Copy

typescript
class Goblin extends ex.Actor {
  constructor(config: { pos: Vector, patrol?: boolean, range?: number }) {
    super({
      pos: config.pos,
      width: 16,
      height: 16,
      color: ex.Color.Green
    });
    
    if (config.patrol) {
      this.setupPatrol(config.range || 2);
    }
  }
  
  setupPatrol(range: number) {
    // Add patrol behavior
  }
}
class Slime extends ex.Actor {
  constructor(config: { pos: Vector, speed?: number }) {
    super({
      pos: config.pos,
      width: 16,
      height: 16,
      color: ex.Color.Blue,
      vel: vec(config.speed || 1, 0)
    });
  }
}
Copy

Step 3: Create Your Attribute Callback​

typescript
const spawnEntities = (attData: TileAttributeData) => {
  const { tileData, mapData } = attData;
  const { attributes, x, y } = tileData;
  
  // Calculate world position
  const worldPos = vec(
    x * mapData.tileSize + mapData.tileSize / 2,
    y * mapData.tileSize + mapData.tileSize / 2
  );
  
  // Spawn based on entity type
  let entity: ex.Actor | null = null;
  
  switch (attributes.entity) {
    case 'goblin':
      entity = new Goblin({
        pos: worldPos,
        patrol: attributes.patrol,
        range: attributes.range
      });
      break;
      
    case 'slime':
      entity = new Slime({
        pos: worldPos,
        speed: attributes.speed
      });
      break;
      
  }
  
  if (entity) {
    game.add(entity);
  }
};
Copy

typescript
const spawnEntities = (attData: TileAttributeData) => {
  const { tileData, mapData } = attData;
  const { attributes, x, y } = tileData;
  
  // Calculate world position
  const worldPos = vec(
    x * mapData.tileSize + mapData.tileSize / 2,
    y * mapData.tileSize + mapData.tileSize / 2
  );
  
  // Spawn based on entity type
  let entity: ex.Actor | null = null;
  
  switch (attributes.entity) {
    case 'goblin':
      entity = new Goblin({
        pos: worldPos,
        patrol: attributes.patrol,
        range: attributes.range
      });
      break;
      
    case 'slime':
      entity = new Slime({
        pos: worldPos,
        speed: attributes.speed
      });
      break;
      
  }
  
  if (entity) {
    game.add(entity);
  }
};
Copy

Step 4: Load Your Map​

typescript
const game = new ex.Engine({
  width: 800,
  height: 600
});
const spriteFusionMap = new SpriteFusionResource({
  mapPath: './map/dungeon.json',
  spritesheetPath: './map/spritesheet.png',
  tileAttributeFactory: spawnEntities,
  objectLayers: ['Enemies'] // Don't render this layer
});
const loader = new ex.Loader([spriteFusionMap]);
game.start(loader).then(() => {
  spriteFusionMap.addToScene(game.currentScene);
  // All enemies are now spawned with their custom data!
});
Copy

typescript
const game = new ex.Engine({
  width: 800,
  height: 600
});
const spriteFusionMap = new SpriteFusionResource({
  mapPath: './map/dungeon.json',
  spritesheetPath: './map/spritesheet.png',
  tileAttributeFactory: spawnEntities,
  objectLayers: ['Enemies'] // Don't render this layer
});
const loader = new ex.Loader([spriteFusionMap]);
game.start(loader).then(() => {
  spriteFusionMap.addToScene(game.currentScene);
  // All enemies are now spawned with their custom data!
});
Copy

Advanced Use Cases​

Tile attributes aren't just for spawning entities. Here are more ways to use them:

Interactive Tiles​

json
{
  "type": "door",
  "locked": true,
  "key": "brass_key",
  "destination": "level_2"
}
Copy

json
{
  "type": "door",
  "locked": true,
  "key": "brass_key",
  "destination": "level_2"
}
Copy

Environmental Effects​

json
{
  "hazard": "lava",
  "damage": 10,
  "interval": 1000
}
Copy

json
{
  "hazard": "lava",
  "damage": 10,
  "interval": 1000
}
Copy

Quest Markers​

json
{
  "npc": "merchant",
  "dialog": "quest_intro",
  "items": ["potion", "map"]
}
Copy

json
{
  "npc": "merchant",
  "dialog": "quest_intro",
  "items": ["potion", "map"]
}
Copy

Pathfinding Data​

json
{
  "node": true,
  "connections": [12, 45, 67],
  "cost": 2
}
Copy

json
{
  "node": true,
  "connections": [12, 45, 67],
  "cost": 2
}
Copy

Best Practices​

Keep Attributes Focused​

Don't overload attributes with everything. Use them for:

• ✅ Position-dependent data (spawn points, triggers)
• ✅ Configuration that should live with the map
• ❌ Complex game logic better suited for separate systems

Use Object Layers Wisely​

Visual layers and object layers serve different purposes:

• Visual layers: Render the tilemap, optionally include attributes
• Object layers: Pure data, no rendering

If a tile has both visual and data requirements, keep them on separate layers for clarity.

Validate Your Attributes​

The plugin passes whatever JSON is in SpriteFusion. Add validation:

typescript
const attributeCallback = (attData: TileAttributeData) => {
  const { attributes } = attData.tileData;
  
  if (!attributes.entity) {
    console.warn('Tile missing entity attribute:', attData);
    return;
  }
  
  // Safe to use attributes.entity now
};
Copy

typescript
const attributeCallback = (attData: TileAttributeData) => {
  const { attributes } = attData.tileData;
  
  if (!attributes.entity) {
    console.warn('Tile missing entity attribute:', attData);
    return;
  }
  
  // Safe to use attributes.entity now
};
Copy

Benefits of This Approach​

1. Single Source of Truth​

Your map IS your spawn data. No synchronization issues.

2. Designer-Friendly​

Level designers can place and configure entities without touching code.

3. Iteration Speed​

Move an enemy? Just drag the tile. Change stats? Update the attributes. Export and test.

4. Type Safety (with TypeScript)​

Define your attribute schemas:

typescript
interface EnemyAttributes {
  entity: 'goblin' | 'slime' | 'boss';
  health?: number;
  patrol?: boolean;
  range?: number;
}
const attributeCallback = (attData: TileAttributeData) => {
  const attrs = attData.tileData.attributes as EnemyAttributes;
  // TypeScript knows what's available
};
Copy

typescript
interface EnemyAttributes {
  entity: 'goblin' | 'slime' | 'boss';
  health?: number;
  patrol?: boolean;
  range?: number;
}
const attributeCallback = (attData: TileAttributeData) => {
  const attrs = attData.tileData.attributes as EnemyAttributes;
  // TypeScript knows what's available
};
Copy

Common Pitfalls​

Forgetting to Export as JSON​

SpriteFusion has both "Save" and "Export JSON" options. The plugin needs the JSON export, not the saved project file.

Mixing Visual and Data Responsibilities​

If your callback is making decisions based on tile graphics, you're coupling too tightly. Use attributes for data, tile IDs for visuals.

Overcomplicating Attributes​

Keep them simple. If you're nesting 5 levels deep in your JSON, consider moving that logic elsewhere.

Installation and Setup​

Get started in three steps:

1. Install the Plugin​

bash
npm install @excaliburjs/plugin-spritefusion
Copy

bash
npm install @excaliburjs/plugin-spritefusion
Copy

2. Create Your Map in SpriteFusion​

• Visit https://www.spritefusion.com/editor
• Design your map
• Add tile attributes where needed
• Export as JSON

3. Load in Excalibur​

typescript
import { SpriteFusionResource } from '@excaliburjs/plugin-spritefusion';
const map = new SpriteFusionResource({
  mapPath: './map/map.json',
  spritesheetPath: './map/spritesheet.png',
  tileAttributeFactory: yourCallback,
  objectLayers: ['DataLayer']
});
game.start(loader).then(() => {
  map.addToScene(game.currentScene);
});
Copy

typescript
import { SpriteFusionResource } from '@excaliburjs/plugin-spritefusion';
const map = new SpriteFusionResource({
  mapPath: './map/map.json',
  spritesheetPath: './map/spritesheet.png',
  tileAttributeFactory: yourCallback,
  objectLayers: ['DataLayer']
});
game.start(loader).then(() => {
  map.addToScene(game.currentScene);
});
Copy

Why ExcaliburJS​

Small plug for the engine that makes this all possible:

ExcaliburJS is a friendly, TypeScript 2D game engine for the web. It's free and open source (FOSS), well documented, and has a growing community of developers building great games.

The SpriteFusion plugin is just one example of how Excalibur's architecture makes complex features feel natural. If you're interested in 2D web game development, check it out!

Join the Discord community for questions and support.

Summary​

Tile attributes bridge the gap between level design and game logic. What used to require maintaining parallel data structures now happens automatically:

• Design once — add entities, triggers, and logic directly in SpriteFusion
• One source of truth — no more coordinate synchronization
• Iterate fast — move things in the editor, not the code

The updated ExcaliburJS SpriteFusion plugin makes this seamless with attribute callbacks and object layers. Your maps become more than just visuals — they're living configuration files for your game world.

Whether you're spawning enemies, placing collectibles, or defining trigger zones, tile attributes keep your workflow smooth and your codebase clean.

Resources​

• SpriteFusion Editor
• ExcaliburJS Documentation
• SpriteFusion Plugin Repository
• Excalibur Discord

Ready to embed game logic in your tilemaps? Give SpriteFusion attributes a try — your future self will thank you when you move that boss fight for the tenth time and everything just works.

Intro​

Autotiling is one of those topics every 2D gamedev bumps into sooner or later.
You want maps that look nice without hand-placing every edge and corner, but you don’t want to manage a monster tileset with 50+ variants just to blend one terrain type into another.

In this post, I’ll show you the dual Tilemap technique I use in ExcaliburJS with TypeScript.
This method cuts the needed art down to just 5 tiles, keeps your code simple, and separates gameplay logic from visual decoration.

Quick Review of Autotiling​

Autotiling is about automating which tile sprite to draw based on a tile’s neighbors.
Instead of painting every edge by hand, the engine checks surrounding cells and picks the right graphic.

The most common approaches:

• Blob / bitmask – looks at 8 neighbors; needs ~47–56 tiles.
• Marching Squares – 4-bit mask (N/E/S/W); needs 16 tiles.
• Wang tiles – edges/corners encode transitions; flexible, but still asset-heavy.

These work well but tend to require large tilesets and entangled rules.

My last dive into autotiling, Autotiling Technique, implemented a 47 tile tileset and bitmasking. While it worked and looked great, the algorithm forced me to do a lot of work mapping all the different bitmasks to the 47 tiles. It took a lot of manual effort.

Example from my last autotiling project:

Traditional Autotiling Techniques​

The classic techniques all share a common trade-off: flexibility vs. asset count.

• Blob / Bitmask (47+ tiles)
  Each neighbor contributes to a binary mask (8 bits → 256 possibilities).
  Many cases overlap visually, so artists usually trim down to ~47 unique tiles.
  This means dozens of sprites to draw and maintain.

• Marching Squares (16 tiles)
  Simpler 4-bit system that only considers N/E/S/W.
  It’s easier to code, but you still need 16 distinct tiles.

• Wang Tiles
  Encode transitions on edges or corners. Very elegant mathematically, but each terrain type still multiplies your tile count.

These all work — but if you only want a clean outline between Ground and Void, they’re overkill.

What is the problem?​

A ton of art​

When I implemented a 47-tile bitmask system, the art looked great — but the cost was high:

• Artist time: drawing 47 tiles for every new biome or terrain type.
• Mapping complexity: bitmask → tile index lookups are tedious and brittle.
• Coupling: logic and visuals are glued together; small rule changes break the whole set.

This complexity grows fast when you add multiple terrain types (grass, sand, snow, etc.).

The Ambiguous Tile​

Visual: Part of the tile shows one terrain (e.g., grass), while the rest shows another (e.g., soil/ground).

Gameplay/Logic: The walkable area is determined by the world Tilemap (logic map), not the graphic overlay. So even if half the tile visually looks like grass, the character might still be able to walk over it if the underlying tile is marked as walkable ground.This leads to a detail that the game developer must manage: is the tile walkable or usable?

Benefits of a dual Tilemap solution​

Instead of one giant Tilemap that does everything, we split the work:

• World Tilemap (logic)
  Just 2 states and one tile: the background tile. This is the world Tilemap and is used for game logic. For this demonstration we are manage the states of soil or grass.

• Graphics Tilemap (overlay)
  Only 5 tiles: Edge, InnerCorner, OuterCorner, Filled, or Opposite Corners
  These can be rotated and stacked to create all the shapes we need.

Total: 6 tiles, the background tile plus 5 different grass tiles.

Removal of the ambiguous tile​

With the offset 2nd Tilemap, we can better align the mesh textures to the actual world tiles, removing the ambiguous tile problem stated earlier.

Why this is powerful​

• Tiny tileset (easy for artists).
• Composable overlays (T-junctions, crosses, islands all “just work”).
• Separation of concerns (logic map stays clean).
• No Ambiguous Tiles

A walk through the algorithm​

For my demonstration, I created two Excalibur (Ex) Tilemaps. One I called worldMap and the other meshMap.

Getting started and setup​

ts
const worldMap = new TileMap({
  columns: 10,
  rows: 10,
  tileWidth: 16,
  tileHeight: 16,
});
// Note: the meshMap needs to 'overlap' the world map by one tile, you'll see what later
const meshMap = new TileMap({
  columns: 11,
  rows: 11,
  tileWidth: 16,
  tileHeight: 16,
});
// Position the Tilemaps
worldMap.pos = vec(0, 0);
worldMap.z = 0;
// Note: the mesh Tilemap's position is half a tile offset; this is important
meshMap.pos = vec(-8, -8);
meshMap.z = 1;
// Load Assets and add Tilemaps to game
await game.start(loader);
game.add(worldMap);
game.add(meshMap);
//move camera and center on the Tilemap
game.currentScene.camera.pos = vec(16 * 5, 16 * 5);
game.currentScene.camera.zoom = 1.25;
Copy

ts
const worldMap = new TileMap({
  columns: 10,
  rows: 10,
  tileWidth: 16,
  tileHeight: 16,
});
// Note: the meshMap needs to 'overlap' the world map by one tile, you'll see what later
const meshMap = new TileMap({
  columns: 11,
  rows: 11,
  tileWidth: 16,
  tileHeight: 16,
});
// Position the Tilemaps
worldMap.pos = vec(0, 0);
worldMap.z = 0;
// Note: the mesh Tilemap's position is half a tile offset; this is important
meshMap.pos = vec(-8, -8);
meshMap.z = 1;
// Load Assets and add Tilemaps to game
await game.start(loader);
game.add(worldMap);
game.add(meshMap);
//move camera and center on the Tilemap
game.currentScene.camera.pos = vec(16 * 5, 16 * 5);
game.currentScene.camera.zoom = 1.25;
Copy

Assets​

The tileset i'm using has 6 tiles, the first is the 'base' soil tile that covers the world Tilemap. The next 5 are the 5 tiles needed for this autotiling technique. For the purposes of this demonstration I included a light border around the soil tile so the end result can more readily show how the Tilemaps line up.

Initializing Tile State​

I loop through all the tiles initially to setup the intial state for each Tilemap.

ts
// Instead of using a TypeScript enum, I like to define my tile states as a const object with string literal values
const TileState = {
  soil: "soil",
  grass: "grass",
} as const;
// Setup the world map state
for (const tile of worldMap.tiles) {
  tile.addGraphic(tileSS.getSprite(0, 0)); //  This sets the default 'soil' tile from the spritesheet
  tile.data.set("state", TileState.soil); //  This is setting the data store of each tile to 'soil'
}
// Setup the Mesh map state
for (const tile of meshMap.tiles) {
  tile.data.set("worldNeighbors", getWorldNeighbors(tile)); // Each tile in the meshMap needs to know its corresponding 'worldMap' neighbors, 4 for each tile (TL, TR, BL, BR)
  tile.data.set("meshTile", null); // which index of the spritesheet do I access
  tile.data.set("rotation", 0); // how do I rotate the graphic
}
Copy

ts
// Instead of using a TypeScript enum, I like to define my tile states as a const object with string literal values
const TileState = {
  soil: "soil",
  grass: "grass",
} as const;
// Setup the world map state
for (const tile of worldMap.tiles) {
  tile.addGraphic(tileSS.getSprite(0, 0)); //  This sets the default 'soil' tile from the spritesheet
  tile.data.set("state", TileState.soil); //  This is setting the data store of each tile to 'soil'
}
// Setup the Mesh map state
for (const tile of meshMap.tiles) {
  tile.data.set("worldNeighbors", getWorldNeighbors(tile)); // Each tile in the meshMap needs to know its corresponding 'worldMap' neighbors, 4 for each tile (TL, TR, BL, BR)
  tile.data.set("meshTile", null); // which index of the spritesheet do I access
  tile.data.set("rotation", 0); // how do I rotate the graphic
}
Copy

Storing the neighbor data​

ts
type TileList = {
  TL: Tile | undefined;
  TR: Tile | undefined;
  BL: Tile | undefined;
  BR: Tile | undefined;
};
const getWorldNeighbors = (currentMeshTile: Tile): TileList => {
  let TL: Tile | undefined = undefined;
  let TR: Tile | undefined = undefined;
  let BL: Tile | undefined = undefined;
  let BR: Tile | undefined = undefined;
  // get vectors of four corners
  const topLefMeshTile = currentMeshTile.pos.clone();
  const topRightMeshTile = currentMeshTile.pos.clone().add(vec(16, 0));
  const bottomLeftMeshTile = currentMeshTile.pos.clone().add(vec(0, 16));
  const bottomRightMeshTile = currentMeshTile.pos.clone().add(vec(16, 16));
  // for each corner, find mesh tile that contains that position
  TL = worldMap.tiles.find(tile => topLefMeshTile.equals(tile.center));
  TR = worldMap.tiles.find(tile => topRightMeshTile.equals(tile.center));
  BL = worldMap.tiles.find(tile => bottomLeftMeshTile.equals(tile.center));
  BR = worldMap.tiles.find(tile => bottomRightMeshTile.equals(tile.center));
  return { TL, TR, BL, BR };
};
Copy

ts
type TileList = {
  TL: Tile | undefined;
  TR: Tile | undefined;
  BL: Tile | undefined;
  BR: Tile | undefined;
};
const getWorldNeighbors = (currentMeshTile: Tile): TileList => {
  let TL: Tile | undefined = undefined;
  let TR: Tile | undefined = undefined;
  let BL: Tile | undefined = undefined;
  let BR: Tile | undefined = undefined;
  // get vectors of four corners
  const topLefMeshTile = currentMeshTile.pos.clone();
  const topRightMeshTile = currentMeshTile.pos.clone().add(vec(16, 0));
  const bottomLeftMeshTile = currentMeshTile.pos.clone().add(vec(0, 16));
  const bottomRightMeshTile = currentMeshTile.pos.clone().add(vec(16, 16));
  // for each corner, find mesh tile that contains that position
  TL = worldMap.tiles.find(tile => topLefMeshTile.equals(tile.center));
  TR = worldMap.tiles.find(tile => topRightMeshTile.equals(tile.center));
  BL = worldMap.tiles.find(tile => bottomLeftMeshTile.equals(tile.center));
  BR = worldMap.tiles.find(tile => bottomRightMeshTile.equals(tile.center));
  return { TL, TR, BL, BR };
};
Copy

It is important to understand how I approached storing the tile map data. My disclaimer: there is more than one right way to do this, and I'm certain there are more optimum means. This is simply my approach.

Not every tile will have 4 neighbors, if you consider the edge of the worldMap, there may only be one or two neighbors available which is why I allow undefined values for the tile positions as well. The majority of the tiles can/will be surrounded by 4 world tiles. The fact that the mesh Tilemap is offset by half of the tilesize, means that the corners of the mesh tile land on the centers of the four neighbors, and I use this to my advantage.

Managing the mouse input​

While not specific to Tilemapping, controlling the mouse properly to set the worldMap tile states is important. When I click and drag the mouse, what I'm doing is using the mouse pointer positions to set/clear the world tile state. I use the Left Mouse Button (LMB) to set 'grass' state, and use the Right Mouse Button to clear the 'grass' state to 'soil'.

ts
let isDragging = false;
let lastTile: Tile | null = null;
let activeButton: PointerButton | null = null;
game.input.pointers.primary.on("down", e => {
  if (e.button !== PointerButton.Left && e.button !== PointerButton.Right) return; // ignore other buttons
  activeButton = e.button;
  isDragging = true;
  lastTile = null; // reset so first tile definitely triggers
  setTileState(game.input.pointers.primary.lastWorldPos, activeButton);
});
game.input.pointers.primary.on("up", e => {
  isDragging = false;
  lastTile = null;
  activeButton = null;
});
game.input.pointers.primary.on("move", e => {
  if (isDragging && activeButton) {
    setTileState(game.input.pointers.primary.lastWorldPos, activeButton); // <---- this manages the click and drag 'drawing' of tiles
  }
});
Copy

ts
let isDragging = false;
let lastTile: Tile | null = null;
let activeButton: PointerButton | null = null;
game.input.pointers.primary.on("down", e => {
  if (e.button !== PointerButton.Left && e.button !== PointerButton.Right) return; // ignore other buttons
  activeButton = e.button;
  isDragging = true;
  lastTile = null; // reset so first tile definitely triggers
  setTileState(game.input.pointers.primary.lastWorldPos, activeButton);
});
game.input.pointers.primary.on("up", e => {
  isDragging = false;
  lastTile = null;
  activeButton = null;
});
game.input.pointers.primary.on("move", e => {
  if (isDragging && activeButton) {
    setTileState(game.input.pointers.primary.lastWorldPos, activeButton); // <---- this manages the click and drag 'drawing' of tiles
  }
});
Copy

Changing Tile State​

ts
const setTileState = (pPos: Vector, buttonState: PointerButton) => {
  // get tile coords
  const tx = Math.floor(pPos.x / worldMap.tileWidth);
  const ty = Math.floor(pPos.y / worldMap.tileHeight);
  // if tile coords are 'inside' the worldmap
  if (tx >= 0 && tx < worldMap.columns && ty >= 0 && ty < worldMap.rows) {
    // if we moved to a new tile
    if (lastTile !== worldMap.getTile(tx, ty)) {
      const state = buttonState === PointerButton.Left ? TileState.grass : TileState.soil;
      worldMap.getTile(tx, ty)!.data.set("state", state);
      lastTile = worldMap.getTile(tx, ty);
    }
  }
  //update the mesh data and redraw
  updateMeshMap();
  redrawMeshTileMap();
};
Copy

ts
const setTileState = (pPos: Vector, buttonState: PointerButton) => {
  // get tile coords
  const tx = Math.floor(pPos.x / worldMap.tileWidth);
  const ty = Math.floor(pPos.y / worldMap.tileHeight);
  // if tile coords are 'inside' the worldmap
  if (tx >= 0 && tx < worldMap.columns && ty >= 0 && ty < worldMap.rows) {
    // if we moved to a new tile
    if (lastTile !== worldMap.getTile(tx, ty)) {
      const state = buttonState === PointerButton.Left ? TileState.grass : TileState.soil;
      worldMap.getTile(tx, ty)!.data.set("state", state);
      lastTile = worldMap.getTile(tx, ty);
    }
  }
  //update the mesh data and redraw
  updateMeshMap();
  redrawMeshTileMap();
};
Copy

As the mouse moves with the LMB or RMB held down, the setTileState method is being called with the position and button state details. This method uses this data to set the worldMap tile states appropriately. Then redraws the Tilemap.

The Magic, selecting which tile and how to rotate​

For this section, this is where one had to sit down and consider how each tile is drawn. This is my approach;

1. Loop over world neighbors and 'count' grass tiles
2. For each 'combination' of grass tiles, select the tile index
3. For the couple of tiles where rotation is important, figure out 'where' the grass tiles are located

Let us walk through the code:

ts
const updateMeshMap = () => {
  for (const tile of meshMap.tiles) {
    // get the predetermined neighbor references
    const worldNeighbors = tile.data.get("worldNeighbors");
    const { spriteIndex, rotation } = calculateMeshSprite(worldNeighbors); // call the function that returns the index and rotation structure
    // if no tile data needed, clear out the mesh data
    if (spriteIndex === null || rotation === null) {
      tile.data.delete("meshTile");
      tile.data.delete("rotation");
      continue;
    }
    // set the mesh data appropriately
    tile.data.set("meshTile", spriteIndex);
    tile.data.set("rotation", toRadians(rotation)); // this is where the rotation is converted to Radians for proper graphic rotation
  }
};
Copy

ts
const updateMeshMap = () => {
  for (const tile of meshMap.tiles) {
    // get the predetermined neighbor references
    const worldNeighbors = tile.data.get("worldNeighbors");
    const { spriteIndex, rotation } = calculateMeshSprite(worldNeighbors); // call the function that returns the index and rotation structure
    // if no tile data needed, clear out the mesh data
    if (spriteIndex === null || rotation === null) {
      tile.data.delete("meshTile");
      tile.data.delete("rotation");
      continue;
    }
    // set the mesh data appropriately
    tile.data.set("meshTile", spriteIndex);
    tile.data.set("rotation", toRadians(rotation)); // this is where the rotation is converted to Radians for proper graphic rotation
  }
};
Copy

This is a straightforward utility method that loops through each tile and sets the data appropriately, there's still one more magical method to dive into.

ts
const calculateMeshSprite = (neighbors: TileList): { spriteIndex: number | null; rotation: number | null } => {
  // 1. Count the grass tiles
  let grassCount = 0;
  Object.values(neighbors).forEach(tile => {
    if (!tile) return;
    if (tile.data.get("state") === TileState.grass) {
      grassCount++;
    }
  });
  // based on grasstile count, make a decision
  let spriteIndex = 0;
  let rotation = 0;
  let isTLGrass = neighbors.TL?.data.get("state") === TileState.grass;
  let isTRGrass = neighbors.TR?.data.get("state") === TileState.grass;
  let isBLGrass = neighbors.BL?.data.get("state") === TileState.grass;
  let isBRGrass = neighbors.BR?.data.get("state") === TileState.grass;
  ...
Copy

ts
const calculateMeshSprite = (neighbors: TileList): { spriteIndex: number | null; rotation: number | null } => {
  // 1. Count the grass tiles
  let grassCount = 0;
  Object.values(neighbors).forEach(tile => {
    if (!tile) return;
    if (tile.data.get("state") === TileState.grass) {
      grassCount++;
    }
  });
  // based on grasstile count, make a decision
  let spriteIndex = 0;
  let rotation = 0;
  let isTLGrass = neighbors.TL?.data.get("state") === TileState.grass;
  let isTRGrass = neighbors.TR?.data.get("state") === TileState.grass;
  let isBLGrass = neighbors.BL?.data.get("state") === TileState.grass;
  let isBRGrass = neighbors.BR?.data.get("state") === TileState.grass;
  ...
Copy

So far in this function we've looped through the neighbors object and counted the grass tiles. Also, I've setup some helper flags for assisting with orientation.

ts
  ...
  // No grass, return the nullish state
  if (grassCount === 0) return { spriteIndex: null, rotation: null };
  // one grass square, use the sprite with just a corner piece, index 1
  else if (grassCount === 1) {
    spriteIndex = 1;
    //rotate the tile based on which of the corners is grass
    if (isTLGrass) {
      rotation = 180;
    } else if (isTRGrass) {
      rotation = -90;
    } else if (isBLGrass) {
      rotation = 90;
    } else if (isBRGrass) {
      rotation = 0;
    }
  }
  ...
Copy

ts
  ...
  // No grass, return the nullish state
  if (grassCount === 0) return { spriteIndex: null, rotation: null };
  // one grass square, use the sprite with just a corner piece, index 1
  else if (grassCount === 1) {
    spriteIndex = 1;
    //rotate the tile based on which of the corners is grass
    if (isTLGrass) {
      rotation = 180;
    } else if (isTRGrass) {
      rotation = -90;
    } else if (isBLGrass) {
      rotation = 90;
    } else if (isBRGrass) {
      rotation = 0;
    }
  }
  ...
Copy

The grassCount: 0 scenario is super simple, return nulls so that nothing is drawn. But let us look into the grassCount:1 quick to get an ideas of what we are working with.

We can use the utility flags for us to set the appropriate rotations, and you can see this pattern show up in the next two scenarios as well. I won't draw the permutations but the commens walk you through each situation.

Below both 2 grass tile and 3 grass tile scenarios. The 3 grass tile scenario it just seemed easier to me to track which tile was not a grass tile.

ts
...
// two of the neighbors are grass, that could be two different tile indexes possibly
else if (grassCount === 2) {
  // are they next to each other or cattycorner?
  // first four are when they are next to each other
  if (isTLGrass && isTRGrass) {
    spriteIndex = 2;
    rotation = -90;
  } else if (isTLGrass && isBLGrass) {
    spriteIndex = 2;
    rotation = 180;
  } else if (isTRGrass && isBRGrass) {
    spriteIndex = 2;
    rotation = 0;
  } else if (isBLGrass && isBRGrass) {
    spriteIndex = 2;
    rotation = 90;
  }
  // next two are the 2 catty corner conditions
  else if (isTLGrass && isBRGrass) {
    spriteIndex = 3;
    rotation = 90;
  } else if (isTRGrass && isBLGrass) {
    spriteIndex = 3;
    rotation = 0;
  }
}
// three grass, one soil, let's track the soil tile, its just easier
else if (grassCount === 3) {
  spriteIndex = 4;
  // to note, we're specifically looking for the tile that's NOT grass
  if (!isTLGrass) {
    rotation = 0;
  } else if (!isTRGrass) {
    rotation = 90;
  } else if (!isBLGrass) {
    rotation = -90;
  } else if (!isBRGrass) {
    rotation = 180;
  }
}
// all grass tiles, rotation is irrelevant
else if (grassCount === 4) spriteIndex = 5;
return { spriteIndex, rotation };
};
Copy

ts
...
// two of the neighbors are grass, that could be two different tile indexes possibly
else if (grassCount === 2) {
  // are they next to each other or cattycorner?
  // first four are when they are next to each other
  if (isTLGrass && isTRGrass) {
    spriteIndex = 2;
    rotation = -90;
  } else if (isTLGrass && isBLGrass) {
    spriteIndex = 2;
    rotation = 180;
  } else if (isTRGrass && isBRGrass) {
    spriteIndex = 2;
    rotation = 0;
  } else if (isBLGrass && isBRGrass) {
    spriteIndex = 2;
    rotation = 90;
  }
  // next two are the 2 catty corner conditions
  else if (isTLGrass && isBRGrass) {
    spriteIndex = 3;
    rotation = 90;
  } else if (isTRGrass && isBLGrass) {
    spriteIndex = 3;
    rotation = 0;
  }
}
// three grass, one soil, let's track the soil tile, its just easier
else if (grassCount === 3) {
  spriteIndex = 4;
  // to note, we're specifically looking for the tile that's NOT grass
  if (!isTLGrass) {
    rotation = 0;
  } else if (!isTRGrass) {
    rotation = 90;
  } else if (!isBLGrass) {
    rotation = -90;
  } else if (!isBRGrass) {
    rotation = 180;
  }
}
// all grass tiles, rotation is irrelevant
else if (grassCount === 4) spriteIndex = 5;
return { spriteIndex, rotation };
};
Copy

Final section, drawing​

ts
const redrawMeshTileMap = () => {
  let tileindex = 0;
  for (const tile of meshMap.tiles) {
    // clear current tile graphics
    tile.clearGraphics();
    //grab sprite index and rotation
    const spriteIndex = tile.data.get("meshTile");
    const rotation = tile.data.get("rotation");
    tileindex++;
    // no sprite data, move on to next tile
    if (!spriteIndex) continue;
    // if there is tile data, grab appropriate sprite, and rotate it
    let sprite = tileSS.getSprite(spriteIndex, 0);
    let spritecopy = sprite.clone(); // <------ if you don't create a copy of the sprite, you'll end up rotating ALL of them in the Tilemap
    spritecopy.rotation = rotation;
    tile.addGraphic(spritecopy); // draw the graphic
  }
};
Copy

ts
const redrawMeshTileMap = () => {
  let tileindex = 0;
  for (const tile of meshMap.tiles) {
    // clear current tile graphics
    tile.clearGraphics();
    //grab sprite index and rotation
    const spriteIndex = tile.data.get("meshTile");
    const rotation = tile.data.get("rotation");
    tileindex++;
    // no sprite data, move on to next tile
    if (!spriteIndex) continue;
    // if there is tile data, grab appropriate sprite, and rotate it
    let sprite = tileSS.getSprite(spriteIndex, 0);
    let spritecopy = sprite.clone(); // <------ if you don't create a copy of the sprite, you'll end up rotating ALL of them in the Tilemap
    spritecopy.rotation = rotation;
    tile.addGraphic(spritecopy); // draw the graphic
  }
};
Copy

The final thing left to do is simply managing the 'drawing' of the graphics to each tile location. We do this by looping through the mesh tiles, and if there is data present, redraw it to the tile.

The Demo​

I place a small and quick demo application out on Itch.io. This demo can give you the sense of how smoothly this works, it is almost magical!

Link to demo: Link

Link to Source: link

Why Excalibur​

Small Plug...

ExcaliburJS is a friendly, TypeScript 2D game engine that can produce games for the web. It is free and open source (FOSS), well documented, and has a growing, healthy community of gamedevs working with it and supporting each other. There is a great discord channel for it JOIN HERE, for questions and inquiries. Check it out!!!

Summary​

Autotiling is one of those problems that looks simple but can quickly balloon into complexity — traditional methods often demand dozens of tiles and intricate bitmask rules.

By splitting responsibilities between two Tilemaps, we drastically simplify the workflow:

• World map handles logic with just 2 states (soil, grass) and a base tile graphic.
• Graphics map overlays visuals with only 5 tiles.
• Total: 5 tiles instead of 47+.

The dual Tilemap method keeps your code clean, your art requirements minimal, and your system flexible for new biomes or mechanics.

If you want to dig into the details, check out the demo on Itch.io and the source on GitHub.
It’s a simple idea that pays off big when your worlds start to grow.

For more information​

This information was learned via a few YouTube videos, which I recommend if you want to dive deeper.

• ThinMatrix video on Terrain Generation
• Jess::Codes, Draw Fewer Tiles - by using a Dual-Grid system!
• Oskar Stålberg - Beyond Townscapers

Tap, click, or keypress to add more fireworks:

In 2024 a lot happened for Excalibur! We had 3 big releases v0.28.x, v0.29.x, and v0.30.x! Join the newsletter to make sure you don't miss a thing!

2 new core conributers: Matt Jennings & Justin Young

Thriving discord with lots of cool games being built 😍

RECORD number of outside code contributions to Excalibur! Everyone that's commented, made an issue, discussion, or commited to a repo!

We are at 1.9k stars on github and growing, give us a star!

AND We have GitHub Sponsors & Patreons! Many thanks!

• 2 x Anonymous
• Ribsom
• PlanetCraft
• AdamE
• Latanya
• Feremabraz
• MRJP-Consulting

Highlights​

Development Build & EcmaScript Modules​

We now ship a excalibur.development.js, which provides additional debug information about issues that you would probably not want to ship to a production game. This provides a better development experience for our devs helping them find bugs faster.

Additionally we ship both an UMD and ESM bundle in Excalibur for modern bunders, the ESM build drastically reduces bundle sizes for folks.

Quick Start​

A big boost to productivity is the new Excalibur CLI for quickly scaffolding games in your favorite bundler technology or even vanilla JavaScript! This tool pulls all our open source template repos from github.

sh
npx create-excalibur@latest
Copy

sh
npx create-excalibur@latest
Copy

This tool was built by contributor Manu Hernandez, big thanks to him for donating his time and building this great tool!

Accomplishments & Cool Stuff​

You might notice a pattern here but Justin (aka Mookie) has been an MVP this year

Goal Oriented Action Planning by Justin Young

Wave Function Collapse by Justin Young

Dev.to Web Game Challenge Winner Justin Young

Demo Reel Games people are making in Excalibur

Performance​

We've really turned the screws on performance in excalibur with v0.30.x being roughly 2-3 times faster than v0.29.x, both in the physics and the graphics! A lot of this was achieved through new data structures, and removing allocations from the hot loop using arena style object pools.

Check out the Excalibur Bunnymark for raw draw performance!

In the physics realm we switched to a new spatial data structure "SparseHashGrid" that seems to yield better performance than our "DynamicAABBTree" previously, especially for large numbers of colliders. Autsider666 really helped dig into this collision performance endeavor, check out his Idle Survivors. We can support many 100s of collisions at once!

Debugging​

We have new debug drawing API you can use anywhere in your game to debug.

typescript
ex.Debug.drawRay(ray: Ray, options?: { distance?: number, color?: Color })
ex.Debug.drawBounds(boundingBox: BoundingBox, options?: { color?: Color })
ex.Debug.drawCircle(center: Vector, radius: number, options?: ...)
ex.Debug.drawPolygon(points: Vector[], options?: { color?: Color })
ex.Debug.drawText(text: string, pos: Vector)
ex.Debug.drawLine(start: Vector, end: Vector, options?: LineGraphicsOptions)
ex.Debug.drawLines(points: Vector[], options?: LineGraphicsOptions)
ex.Debug.drawPoint(point: Vector, options?: PointGraphicsOptions)
Copy

typescript
ex.Debug.drawRay(ray: Ray, options?: { distance?: number, color?: Color })
ex.Debug.drawBounds(boundingBox: BoundingBox, options?: { color?: Color })
ex.Debug.drawCircle(center: Vector, radius: number, options?: ...)
ex.Debug.drawPolygon(points: Vector[], options?: { color?: Color })
ex.Debug.drawText(text: string, pos: Vector)
ex.Debug.drawLine(start: Vector, end: Vector, options?: LineGraphicsOptions)
ex.Debug.drawLines(points: Vector[], options?: LineGraphicsOptions)
ex.Debug.drawPoint(point: Vector, options?: PointGraphicsOptions)
Copy

typescript
onPreUpdate(engine: ex.Engine, elapsedMs: number): void {
    this.vel = ex.Vector.Zero;
    this.graphics.use('down-idle');
    if (engine.input.keyboard.isHeld(ex.Keys.ArrowRight)) { ... }
    if (engine.input.keyboard.isHeld(ex.Keys.ArrowLeft)) { ... }
    if (engine.input.keyboard.isHeld(ex.Keys.ArrowUp)) { ... }
    if (engine.input.keyboard.isHeld(ex.Keys.ArrowDown)) { ... }
    ex.Debug.drawRay(
      new ex.Ray(this.pos, this.vel),
      { distance: 100, color: ex.Color.Red }
    );
}
Copy

typescript
onPreUpdate(engine: ex.Engine, elapsedMs: number): void {
    this.vel = ex.Vector.Zero;
    this.graphics.use('down-idle');
    if (engine.input.keyboard.isHeld(ex.Keys.ArrowRight)) { ... }
    if (engine.input.keyboard.isHeld(ex.Keys.ArrowLeft)) { ... }
    if (engine.input.keyboard.isHeld(ex.Keys.ArrowUp)) { ... }
    if (engine.input.keyboard.isHeld(ex.Keys.ArrowDown)) { ... }
    ex.Debug.drawRay(
      new ex.Ray(this.pos, this.vel),
      { distance: 100, color: ex.Color.Red }
    );
}
Copy

We now have a chrome & firefox extension to help debug your games in the browser. (This is a great place to contribute to open source! We have a LONG wish list for the plugin)

Big thanks to Adam Due Hansen for adding recent fixes that allow debug settings to be saved across browser refresh!

ECS (Entity Component System)​

Simplified Custom System implementations

• Systems are passed an ECS world as a default constructor
• Systems can use any number of queries

typescript
import * as ex from 'excalibur';
export class MySystem extends ex.System {
  static priority = ex.SystemPriority.Average;
  public readonly systemType = ex.SystemType.Draw;
  query: Query<typeof ex.TransformComponent | typeof ex.GraphicsComponent>;
  constructor(public world: ex.World) {
    super();
    this.query = this.world.query([ex.TransformComponent, ex.GraphicsComponent]);
  }
  public update(elapsed: number): void {
    // TODO implement system using query(s)
  }
}
Copy

typescript
import * as ex from 'excalibur';
export class MySystem extends ex.System {
  static priority = ex.SystemPriority.Average;
  public readonly systemType = ex.SystemType.Draw;
  query: Query<typeof ex.TransformComponent | typeof ex.GraphicsComponent>;
  constructor(public world: ex.World) {
    super();
    this.query = this.world.query([ex.TransformComponent, ex.GraphicsComponent]);
  }
  public update(elapsed: number): void {
    // TODO implement system using query(s)
  }
}
Copy

New Tag Queries

• New simplified way to query entities ex.World.query([MyComponentA, MyComponentB])
• New way to query for tags on entities ex.World.queryTags(['A', 'B'])

Coroutines​

These are a powerful tool for doing computation over time, and one of the best examples of that is animation. Coroutines are create for complex behavior and animations over time. They read very linearly for doing complex sequences over time compared to another approach where you might set flags and track timing in a class.

You can do lots of cool things in the body of coroutines in excalibur:

typescript
ex.coroutine(function*() {
  ...
  yield 100; // wait 100ms
  yield; // wait to next frame
  yield Promsie.resolve(); // wait for promise
  yield* ex.coroutine(function* () { ..}); // wait for nested coroutine
});
Copy