You may want to display Text in your game, this can be achieved with the Text, Font, and SpriteFont.
Excalibur currently supports 2 different types of text out of the box. We generally recommend using HTML where you can for UI, because it's really good at that!
You should use a SpriteFont when you really care about how the look and feel of the glyphs. For example, if you have a pixel art game and not having anti-aliased text is important to you you should use a SpriteFont. If you specifically don't want blurry text at lower game resolutions you should use a SpriteFont.
You should use a Font if you want to leverage CSS fonts and want smoothed text or emojis to display. Font works best at higher game resolutions.
Text is a raster graphic that can be used to draw text to the screen, all of the normal things that can be done with rasters and graphics can be done with text.
Text supports both normal OS/web fonts and Sprite fonts.
Example
var text = new ex.Text({
text: 'This is raster text ❤️',
font: new ex.Font({ size: 30 }),
})
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);
Text also supports word wrapping, this can be done by setting the maxWidth
property on the text options.
const text = new ex.Text({
text: 'Some Text Drawn Here\nNext line'
maxWidth: 200 // pixels
});
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,
}),
})
A Font is a traditional system or loaded web font.
Possible font options
export interface FontOptions {
size?: number
unit?: FontUnit
family?: string
style?: FontStyle
bold?: boolean
textAlign?: TextAlign
baseAlign?: BaseAlign
direction?: Direction
shadow?: {
blur?: number
offset?: Vector
color?: Color
}
}
var text = new ex.Text({
text: 'This is raster text ❤️',
font: new ex.Font({
size: 30,
unit: FontUnit.Px,
family: 'sans-serif',
style: FontStyle.Normal,
bold: false,
textAlign: TextAlign.Left,
baseAlign: BaseAlign.Alphabetic,
direction: Direction.LeftToRight,
shadow: {
blur: 2,
offset: ex.Vec(2, 2),
color: ex.Color.Black,
};
})
});
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:wght@100&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();
Sometimes you want to use a custom font based on a sprite sheet of character 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: spriteSheet,
spacing: -6,
})
const text = new ex.Text({
text: 'some text with a sprite font!',
font: spriteFont,
})
Sometimes you want to use text of your own creation from a spritesheet,
const spriteFontSheet = ex.SpriteSheet.fromImageSource({
image: spriteFontImage,
grid: {
rows: 3,
columns: 16,
spriteWidth: 16,
spriteHeight: 16
}
});
const spriteFont = new ex.SpriteFont({
alphabet: '0123456789abcdefghijklmnopqrstuvwxyz,!\'&."?- ',
caseInsensitive: true,
spriteSheet: spriteFontSheet
});
});
const text = new ex.Text({
text: 'This is sprite font text!!',
font: spriteFont
});