Options
All
  • Public
  • Public/Protected
  • All
Menu

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(config: SpriteFontArgs): SpriteFont
  • new SpriteFont(image: Texture, alphabet: string, caseInsensitive: boolean, columns: number, rows: number, spWidth: number, spHeight: number): SpriteFont

Properties

columns

columns: number = 0

image

image: Texture = null

rows

rows: number = 0

spHeight

spHeight: number = 0

spWidth

spWidth: number = 0

spacing

spacing: number = 0

sprites

sprites: Sprite[] = []

Methods

draw

  • draw(ctx: CanvasRenderingContext2D, text: string, x: number, y: number, options: SpriteFontOptions): 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 (inclusive) and ending (exclusive) index For example getAnimationBetween(engine, 0, 5, 200) returns an animation with 5 frames.

    Parameters

    • engine: Engine

      Reference to the current game Engine

    • beginIndex: number

      The index to start taking frames (inclusive)

    • endIndex: number

      The index to stop taking frames (exclusive)

    • speed: number

      The number in milliseconds to display each frame in the animation

    Returns Animation

getAnimationByCoords

  • Get an animation with bespoke sprite coordinates. This is useful if the SpriteSheet is packed and not a uniform width or height. The resulting Animation will have the height and width of the largest dimension (width, height) from among the sprite coordinates

    Parameters

    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

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