A new FontConfig Application
has been added in version 10 to allow Gamemasters to configure custom fonts to use in their world. In order to provide the necessary functionality for this feature, the old CONFIG.fontFamilies
configuration variable has been deprecated in favor of an expanded CONFIG.fontDefinitions
configuration.
Declaring Fonts Programmatically
Previously, additional font families were added to the CONFIG.fontFamilies
array, and it was up to the package in question to load the actual font files that provided these fonts. When configuring CONFIG.fontDefinitions
, the core API will take care of loading fonts for you, using the FontFace API.
Anatomy of a Font Definition
The CONFIG.fontDefinitions
object holds font family definitions keyed by the font family name. Each definition has two properties:
editor
controls whether this font family is available for users to select in the UI, either in the rich text editor, or for notes and drawings.fonts
contains the actual configuration for loading the font with the FontFace API.
Configuring an OS-provided Font
A font definition entry that doesn't specify any font definitions will be considered provided by the individual user's OS.
CONFIG.fontDefinitions["Calibri"] = {
editor: true,
fonts: []
};
Configuring a Font Family
A single font definition entry may contain multiple fonts, each pointing to one or more URLs. If the font family has a different file for the bold and italic versions of the font, each of them should be included as part of the same definition.
CONFIG.fontDefinitions["Roboto"] = {
editor: true,
fonts: [
{urls: ["assets/fonts/Roboto.woff2"]},
{urls: ["assets/fonts/RobotoBold.woff2"], weight: 700},
{urls: ["assets/fonts/RobotoItalic.woff2"], style: "italic"}
]
};
Fallback URLs
Multiple URLs may be provided as part of the same font definition. The URLs are tried in-order, with the first one to successfully load being used.
CONFIG.fontDefinitions["Roboto"] = {
editor: true,
fonts: [
{
urls: [
"assets/fonts/Roboto.woff2",
"https://fonts.gstatic.com/s/roboto/v30/Roboto.woff2"
]
}
]
};
Loading Fonts
Font definitions added to CONFIG.fontDefinitions
before the setup
hook will be automatically loaded as part of world initialization. Font definitions may be loaded ad-hoc after the setup
hook by invoking FontConfig.loadFont
. Note that if there are drawings on the active scene that use a custom font that has not been loaded in the setup
hook, the behavior is undefined.
FontConfig.loadFont("Roboto", {
editor: true,
fonts: [{urls: "assets/fonts/Roboto.woff2"}]
});
Checking Font Availability
Checking if a font definition has successfully loaded and is available to users via the UI can be done by invoking FontConfig.getAvailableFonts()
, which will return an array of loaded font families.
More nuanced checks, such as determining if the bold weight of a particular font family is available specifically, or checking if a font family is available in the world in general, and not necessarily available to users via the UI, can be done with the general FontFaceSet API.
document.fonts.check("bold 1rem Roboto");