Options
All
  • Public
  • Public/Protected
  • All
Menu

Class SpriteFont

Sprite fonts are a used in conjunction with a Label to specify a particular bitmap as a font. Note that some font features are not supported by Sprite fonts.

Generating the font sheet

You can use tools such as Bitmap Font Builder to generate a sprite sheet for you to load into Excalibur.

Creating a sprite font

Start with an image with a grid containing all the letters you want to support.

Once you load it into Excalibur using a Texture resource, you can create a SpriteFont using the constructor.

For example, here is a representation of a font sprite sheet for an uppercase alphabet with 4 columns and 7 rows:

ABCD
EFGH
IJKL
MNOP
QRST
UVWX
YZ

Each letter is 30x30 and after Z is a blank one to represent a space.

Then to create the SpriteFont:

var game = new ex.Engine();
var txFont = new ex.Texture("/assets/tx/font.png");
// load assets
var loader = new ex.Loader(txFont);

// start game
game.start(loader).then(function () {

  // create a font
  var font = new ex.SpriteFont(txFont, "ABCDEFGHIJKLMNOPQRSTUVWXYZ ", true, 4, 7, 30, 30);
  // create a label using this font
  var label = new ex.Label("Hello World", 0, 0, null, font);
  // display in-game
  game.add(label);
});

If you want to use a lowercase representation in the font, you can pass false for caseInsensitive and the matching will be case-sensitive. In our example, you would need another 7 rows of lowercase characters.

Font colors

When using sprite fonts with a Label, you can set the Label.color property to use different colors.

Known Issues

One font per Label
Issue #172

If you intend on changing colors or applying opacity effects, you have to use a new SpriteFont instance per Label.

Using opacity removes other effects
Issue #148

If you apply any custom effects to the sprites in a SpriteFont, including trying to use Label.color, they will be removed when modifying Label.opacity.

Hierarchy

Index

Constructors

constructor

  • new SpriteFont(image: Texture, alphabet: string, caseInsensitive: boolean, columns: number, rows: number, spWidth: number, spHeight: number): SpriteFont
  • Parameters

    • image: Texture

      The backing image texture to build the SpriteFont

    • alphabet: string

      A string representing all the characters in the image, in row major order.

    • caseInsensitive: boolean

      Indicate whether this font takes case into account

    • columns: number

      The number of columns of characters in the image

    • rows: number

      The number of rows of characters in the image

    • spWidth: number

      The width of each character in pixels

    • spHeight: number

      The height of each character in pixels

    Returns SpriteFont

Properties

Private _colorLookup

_colorLookup: object

Type declaration

Private _currentColor

_currentColor: Color = Color.Black.clone()

Private _currentOpacity

_currentOpacity: Number = 1

Private _shadowOffsetX

_shadowOffsetX: number = 5

Private _shadowOffsetY

_shadowOffsetY: number = 5

Private _spriteLookup

_spriteLookup: object

Type declaration

  • [key: string]: number

Private _sprites

_sprites: object

Type declaration

Private _textShadowColor

_textShadowColor: Color = Color.Black.clone()

Private _textShadowDirty

_textShadowDirty: boolean = true

Private _textShadowOn

_textShadowOn: boolean = false

Private _textShadowSprites

_textShadowSprites: object

Type declaration

Private alphabet

alphabet: string

A string representing all the characters in the image, in row major order.

Private caseInsensitive

caseInsensitive: boolean

Indicate whether this font takes case into account

image

image: Texture

The backing image texture to build the SpriteFont

spHeight

spHeight: number

The height of each character in pixels

spWidth

spWidth: number

The width of each character in pixels

sprites

sprites: Sprite[] = []

Methods

Private _parseOptions

draw

  • draw(ctx: CanvasRenderingContext2D, text: string, x: number, y: number, options: ISpriteFontOptions): void
  • Draws the current sprite font

    Parameters

    • ctx: CanvasRenderingContext2D
    • text: string
    • x: number
    • y: number
    • options: ISpriteFontOptions

    Returns void

getAnimationBetween

  • getAnimationBetween(engine: Engine, beginIndex: number, endIndex: number, speed: number): Animation
  • Create an animation from the this SpriteSheet by specifing the range of images with the beginning and ending index

    Parameters

    • engine: Engine

      Reference to the current game Engine

    • beginIndex: number

      The index to start taking frames

    • endIndex: number

      The index to stop taking frames

    • speed: number

      The number in milliseconds to display each frame in the animation

    Returns Animation

getAnimationByIndices

  • getAnimationByIndices(engine: Engine, indices: number[], speed: number): Animation
  • Create an animation from the this SpriteSheet by listing out the sprite indices. Sprites are organized in row major order in the SpriteSheet.

    Parameters

    • engine: Engine

      Reference to the current game Engine

    • indices: number[]

      An array of sprite indices to use in the animation

    • speed: number

      The number in milliseconds to display each frame in the animation

    Returns Animation

getAnimationForAll

  • Treat the entire SpriteSheet as one animation, organizing the frames in row major order.

    Parameters

    • engine: Engine

      Reference to the current game Engine

    • speed: number

      The number in milliseconds to display each frame the animation

    Returns Animation

getSprite

  • getSprite(index: number): Sprite
  • Retreive a specific sprite from the SpriteSheet by its index. Sprites are organized in row major order in the SpriteSheet.

    Parameters

    • index: number

      The index of the sprite

    Returns Sprite

getTextSprites

  • getTextSprites(): object
  • Returns a dictionary that maps each character in the alphabet to the appropriate Sprite.

    Returns object

setTextShadow

  • setTextShadow(offsetX: number, offsetY: number, shadowColor: Color): void
  • Sets the text shadow for sprite fonts

    Parameters

    • offsetX: number

      The x offset in pixels to place the shadow

    • offsetY: number

      The y offset in pixels to place the shadow

    • shadowColor: Color

      The color of the text shadow

    Returns void

useTextShadow

  • useTextShadow(on: boolean): void
  • Toggles text shadows on or off

    Parameters

    • on: boolean

    Returns void