Text

You may want to display Text in your game, this can be acheived with the Text, Font, and SpriteFont.

Text

Text is a prebuilt Graphic that can be used to draw text to the screen. Multiple lines of text are supported.

const game = new ex.Engine({...});
const text = new ex.Text({
    text: 'Some Text Drawn Here\nNext line'
});

const actor = new ex.Actor({
    pos: ex.vec(100, 100)
});
actor.graphics.use(text);

game.currentScene.add(actor);

Labels

Labels are a batteries included Actors with Text built and font built in.

const label = new ex.Label({
    text: 'Some text,
    pos: ex.vec(100, 100),
    font: new ex.Font({
        family: 'impact',
        size: 24,
        unit: ex.FontUnit.Px
    })
});

Font

A Font is a traditional system or loaded web font.

const font = new ex.Font({
  family: 'impact',
  size: 24,
  unit: ex.FontUnit.Px,
})

const text = new ex.Text({
  text: 'some text with a font',
  font: font,
})

It is recommended you load any font important to your game and not rely on any pre-installed system fonts, those will be different from computer to computer.

For example the google fonts loader is a common way to do this.

<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link
  href="https://fonts.googleapis.com/css2?family=Roboto:[email protected]&display=swap"
  rel="stylesheet"
/>
const font = new ex.Font({
  family: 'Roboto',
  size: 24,
  unit: ex.FontUnit.Px,
})

One potential issue with using web fonts is they won't render correctly until loaded see article for details.

async function waitForFontLoad(font, timeout = 2000, interval = 100) {
  return new Promise((resolve, reject) => {
    // repeatedly poll check
    const poller = setInterval(async () => {
      try {
        await document.fonts.load(font);
      } catch (err) {
        reject(err);
      }
      if (document.fonts.check(font)) {
        clearInterval(poller);
        resolve(true);
      }
    }, interval);
    setTimeout(() => clearInterval(poller), timeout);
  });
}

// Load font before game start
await waitForFontLoad('24px Roboto');

const game = new ex.Engine({...})
await game.start();

SpriteFont

Sometimes you want to use a custom font based on a sprite sheet of character glyphs

Custom pixel art glyphs

const image = new ex.ImageSource('./path/to/sprite-font.png')

const spriteSheet = SpriteSheet.fromImageSource({
  image: image,
  grid: {
    rows: 3,
    columns: 16,
    spriteWidth: 16,
    spriteHeight: 16,
  },
})

const spriteFont = new SpriteFont({
  alphabet: '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ,!\'&."?-()+ ',
  caseInsensitive: true,
  spriteSheet: this._spriteSheet,
  spacing: -6,
})

const text = new ex.Text({
  text: 'some text with a sprite font!',
  font: spriteFont,
})