Excalibur.js Documentation

Excalibur is a free, open-source 2D game engine written in TypeScript for creating HTML5 canvas games. It handles boilerplate engine code and provides cross-platform targeting. It is licensed under the 2-clause BSD license, making it suitable for commercial projects.

Key resources:

• User Documentation: https://excaliburjs.com/docs
• API Reference: https://excaliburjs.com/docs/
• Samples: http://excaliburjs.com/samples/
• Community: GitHub Discussions

The Excalibur API is considered largely stable. The development focus leading up to the v1.0 announcement includes:

• Adding final feature sets.
• Light refactoring.
• Cleaning up edge case bugs.

The Graph module provides a data structure for managing nodes and edges. It supports directed and undirected edges, weighted edges, and spatial positioning for nodes. You can use it to perform graph traversals (BFS, DFS) and pathfinding (Dijkstra, A*).

import { Graph } from 'excalibur';

// Create an empty graph of strings
const graph = new Graph<string>();

The ExcaliburGraphicsContext is an abstraction over the underlying drawing mechanism used to display images and graphics. While it is recommended to use ex.Graphics objects with Actors or Entities, you can draw directly to the ExcaliburGraphicsContext for custom rendering needs.

By default, Excalibur uses WebGL. It can fallback to a 2D Canvas implementation if WebGL is unsupported or hardware acceleration is unavailable. Note that certain features like custom renderers and post processors do not work with the Canvas 2D implementation.

In Excalibur's Entity Component System (ECS), Queries are the mechanism used to filter the World for specific subsets of entities.

There are two primary types of queries:

1. Component Queries: Filter entities based on the presence of specific component types. These are typically used by Systems to find entities they need to process.
2. Tag Queries: Filter entities based on string tags. This is a lightweight way to flag entities for logic (like status effects or AI states) without the overhead of a full component.

Lifecycle: Queries are not static; they update automatically as part of the World update cycle, ensuring that as entities gain or lose components/tags, the query results remain accurate.

A GraphicsGroup is a specialized graphic used to compose multiple graphics into a single unit. It draws its members in relation to one another, allowing you to treat a collection of sprites, text, shapes, or animations as a single entity.

When creating a GraphicsGroup, you provide a list of members. Each member consists of a graphic and an offset (a Vector) defining its position relative to the group's origin.

const group = new ex.GraphicsGroup({
  useAnchor: false, // position group from the top left
  members: [
    {
      graphic: newSprite,
      offset: ex.vec(0, 0),
    },
    {
      graphic: newSprite,
      offset: ex.vec(50, 0),
    },
    {
      graphic: text,
      offset: ex.vec(100, 20),
    },
  ],
})

Because the documentation uses MDX, you can import and use React components directly inside your Markdown content. This allows for highly interactive documentation pages.

export const Highlight = ({children, color}) => (
  <span
    style={{
      backgroundColor: color,
      borderRadius: '20px',
      color: '#fff',
      padding: '10px',
      cursor: 'pointer',
    }}
    onClick={() => {
      alert(`You clicked the color ${color} with label ${children}`)
    }}>
    {children}
  </span>
);

This is <Highlight color="#25c2a0">Docusaurus green</Highlight> !

Because both Parallel Actions and ActionSequences are treated as single actions, they can be nested and composed to create complex game automations. You can run multiple sequences in parallel, or run a parallel group within a sequence.

Example: Running two sequences in parallel:

actor.actions.parallel([
  actor.actions.runAction(attackSequence),
  actor.actions.runAction(glowSequence)
]);

Example: Repeating parallel actions using repeatForever:

let prlAction1 = new ex.ParallelActions([
  new ex.MoveBy(player, 150, 0, 110),
  new ex.ScaleTo(player, 2, 2, 1, 1),
]);

let prlAction2 = new ex.ParallelActions([
  new ex.MoveBy(player, -150, 0, 110),
  new ex.ScaleTo(player, 1, 1, 1, 1),
]);

player.actions.repeatForever((ctx) => {
  ctx.runAction(prlAction1);
  ctx.runAction(prlAction2);
});

Instead of assembling game logic in the main entry point, extend ex.Scene and use its onInitialize() method to act as a 'Composition Root'. This is where you should instantiate and add your actors, tilemaps, and other game components to the scene.

class MyLevel extends ex.Scene {

  onInitialize() {
     const myActor1 = new ex.Actor({...});
     this.add(myActor1);

     const map = new ex.TileMap({...});
     this.add(map);
  }
}