Copyright 2017-2022 Moddable Tech, Inc.
Revised: January 7, 2022
Moddable uses the BMFont format for fonts
The Moddable SDK supports any input character (up to 4-byte UTF-8 values) making it possible to render the glyphs for any language written with glyphs having a Unicode representation.
Each font asset consists of a (.png) glyph file and a corresponding font metrics file (.fnt) saved in BMFont Binary format.
This allows anti-aliased or non-anti-aliased font sets to be generated as desired. The Poco renderer in the Moddable SDK does not implement a font scaler. Consequently, each required font size/weight must be generated and included as an asset in the application.
BMFont allows an arbitrary number of glyphs in the font. Moddable supports non-contiguous glyph ranges allowing the developer or graphic designer to create an efficient font asset with just the characters needed for the application. This can significantly reduce asset storage size.
Fonts are generated in black. This allows the Moddable SDK build tools to create alpha masks of the characters. To render the fonts in color, applications apply styles.
There are many tools available for converting TrueType and OpenType fonts on the BMFont format. The Moddable team often uses Glyph Designer (macOS). Another good options is the fontbm command line tool by Vladimir Gamalyan. Instructions for using both are provided below.
Select font and weight. Set font color to black and no outline.
Using the character selection tool select needed characters.
Export .png glyph and .fnt font metrics files in the BMFont Binary format.
To use fontbm, you must first install it on your system. For Windows users, a binary is available for download. Instructions are provided for macOS and Linux users must currently build it from source code following the instructions.
Once you have fontbm, you may use it from the command line to generate the .fnt and .png files needed to add fonts to the Moddable SDK.
There is experimental support in the Moddable SDK project manifest.json file to invoke fontbm automatically as needed as part of building a project. This makes it much easier to use different fonts and font sizes in your projects. To use fontbm support in mcconfig
or mcrun
, you must first set the environment variable FONTBM
to the path to the fontbm executable to allow the Moddable SDK build tools to find fontbm.
Adding TrueType fonts to a manifest is similar to adding pre-built BMFonts. Here's what a compressed BMFont looks like in the manifest:
"resources":{
"*-mask": [
"$(MODDABLE)/examples/assets/fonts/OpenSans-Regular-20"
]
}
To use a TrueType font, it looks like this:
"resources": {
"*-mask": [
{
"source": "$(MODDABLE)/tools/xsbug/fonts/OpenSans-Regular",
"size": 20
}
]
}
This generates two resources, OpenSans-Regular-20.fnt
and OpenSans-Regular-20-alpha.bmp
. The size
property is required: there is no default size.
Similarly, a pre-built uncompressed BMFont looks like this:
"resources":{
"*-alpha": [
"$(MODDABLE)/examples/assets/fonts/OpenSans-Regular-24"
]
}
To use a TrueType font, it looks like this:
"resources": {
"*-alpha": [
{
"source": "$(MODDABLE)/tools/xsbug/fonts/OpenSans-Regular",
"size": 24
}
]
}
This generates one resource, OpenSans-Regular-20.bm4
.
Often the name of a TrueType font file isn't exactly how you want to name your font resources. The name
property allows you specify a name to be used instead:
"resources": {
"*-mask": [
{
"source": "$(MODDABLE)/tools/xsbug/fonts/segoe",
"size": 22,
"name": "Segoe-Regular"
}
]
}
This generates one resource, Segoe-Regular-22.bm4
.
By default, the font output by the conversion process includes Unicode characters from 32 to 127 (inclusive). There are three properties you can use to override this behavior: characters
, blocks
, and localization
. If more than one of these properties is present, all the characters they select are included.
The characters
property is a string that indicates which characters to include. This example include only the characters used to display decimal numbers:
"resources": {
"*-mask": [
{
"source": "$(MODDABLE)/tools/xsbug/fonts/OpenSans-Regular",
"size": 72,
"characters": "0123456789-+.e"
}
]
}
The blocks
property is an array of Unicode block names. These are a convenient way to include groups of characters. For example, here blocks is used to include Basic Latin 1 and Cyrillic characters:
"resources": {
"*-mask": [
{
"source": "$(MODDABLE)/tools/xsbug/fonts/OpenSans-Regular",
"size": 24,
"blocks": ["Basic Latin", "Cyrillic"],
}
]
}
The Piu user interface framework has built-in support for localization. As part of building the localization maps for a Piu, the mclocal
tool also generates a list of all characters used in the localization table. This list can be used to select the glyphs included in a font by setting the localization
property to true
:
"resources": {
"*-mask": [
{
"source": "$(MODDABLE)/tools/xsbug/fonts/OpenSans-Regular",
"size": 24,
"localization": true
}
]
}
By default, kerning tables are not output. Kerning is enabled by setting the kern
property to true
:
"resources": {
"*-mask": [
{
"source": "$(MODDABLE)/tools/xsbug/fonts/OpenSans-Regular",
"size": 24,
"kern": true
}
]
}
The Poco renderer does not kern by default in order to maximize performance. Kerning support is be enabled in the manifest with the following setting:
"defines": {
"cfe": {
"kern": true
}
}
By default, the glyphs output are anti-aliased. Monochrome output can be generated (perfect for 1-bit displays like Moddable Three) by setting the monochrome
property to true
:
"resources": {
"*-mask": [
{
"source": "$(MODDABLE)/tools/xsbug/fonts/OpenSans-Regular",
"size": 24,
"monochrome": true
}
]
}