Creating a custom font in Defold means converting your font file into a format the engine can use, then building a font resource that points to it
Defold works with TrueType fonts (.ttf files) and bitmap fonts. The fastest route is to use a TrueType font you already have or download from a site like Google Fonts, then create a .font resource file that tells Defold where to find it and how to render it. Defold handles the conversion to a bitmap at build time, so you do not need external tools for most projects.
If you need more control — specific character sets, exact pixel sizes, or fonts that render at unusual scales — you can pre-render a bitmap font using a tool like BMFont or Shoebox, then point your Defold font resource to that bitmap instead. This guide covers both paths, starting with the simpler TrueType method.
Key Takeaways
- TrueType fonts (.ttf) are the easiest starting point: place the file in your project, create a .font resource, and Defold converts it automatically at build time.
- Your .font resource file needs to point to the font file, set a size in pixels, and optionally specify which characters to include.
- Bitmap fonts give you pixel-perfect control but require a pre-rendered image and a descriptor file that maps characters to positions on that image.
- Text that uses your custom font must reference the .font resource by its path, the same way you reference sprites or other assets.
- Font rendering respects the material assigned to the text object, so you can tint, scale, or apply effects the same way you would to any other visual element.
Setting up a TrueType font in Defold
Start by placing your .ttf file somewhere in your project. A common structure is to create a fonts folder at the root level, then put your font files there. For example: fonts/my_font.ttf. You can use any font you own or have permission to use — Google Fonts, Adobe Fonts, or fonts you have designed yourself all work.
Next, create a new file with the .font extension in the same folder or nearby. Name it something that matches your font — my_font.font is clear. Open this file in your text editor (Defold's editor will open it as plain text). The file needs three pieces of information: the path to your TrueType file, the size you want it rendered at, and optionally which characters to include.
Here is the basic structure:
tile_set: "fonts/my_font.ttf" size: 32
The tile_set line points to your .ttf file. The size is the height in pixels — 32 means each character will be rendered at 32 pixels tall. Save the file. Defold will process this at build time and create a bitmap version of your font automatically.
Using your custom font in a text object
Once your .font resource exists, you can use it in a text object. Create a new .go (game object) file or open an existing one. Add a text component by creating a .script file or by adding a text node in the editor if you are using a collection.
In your text object or script, set the font property to the path of your .font file. If your font is at fonts/my_font.font, the reference looks like this:
go.set("#text", "font", "fonts/my_font")
The text will now render using your custom font. The size you set in the .font file determines the base size, but you can scale the text object itself larger or smaller without losing quality — Defold scales the rendered bitmap, not the original font.
Controlling which characters are included
By default, Defold includes a basic set of ASCII characters (letters, numbers, punctuation). If your game uses characters outside this range — accented letters, symbols, or characters from other languages — you need to tell Defold to include them. Add an extra_characters line to your .font file.
For example, if you need accented characters for French or Spanish:
tile_set: "fonts/my_font.ttf" size: 32 extra_characters: "àâäéèêëïîôöùûüœæçÀÂÄÉÈÊËÏÎÔÖÙÛÜŒÆÇ"
List every character you need, including spaces if you want them explicitly defined. This keeps your font file smaller by not rendering characters you will never display. If you are unsure what you need, you can include a broad range — just be aware that more characters mean a larger bitmap and slightly longer build times.
For emoji or very large character sets, this approach becomes impractical. That is when a pre-rendered bitmap font is the better choice.
Creating a bitmap font for more control
A bitmap font is an image file (usually .png) where each character is drawn at a specific pixel location, plus a descriptor file that tells Defold where to find each character on that image. This method takes more setup but gives you exact control over how characters look and render.
Use a tool like BMFont (free, Windows and Mac) or Shoebox (free, Windows) to generate the bitmap and descriptor. Open your TrueType font in the tool, set the size and style you want, and export. You will get a .png image and a descriptor file — usually in .fnt format (BMFont's text format) or .xml.
Defold expects the descriptor in a specific format. If your tool exports BMFont's text format (.fnt), you can use it directly. If it exports .xml or another format, you may need to convert it or use a different tool. Check the Defold documentation for supported formats — as of recent versions, BMFont's text format is the most straightforward.
Setting up a bitmap font resource
Place your .png image and .fnt descriptor file in your fonts folder. Create a new .font file and point it to the descriptor instead of a TrueType file:
tile_set: "fonts/my_bitmap_font.fnt"
That is all you need. Defold reads the .fnt file to learn where each character lives on the .png, and renders them directly. No size conversion happens — the characters render at exactly the pixel size you drew them at in BMFont.
If you need the text larger or smaller, scale the text object in your game. Scaling a bitmap font can make it look blocky at large sizes, so if you know you will need multiple sizes, generate separate bitmap fonts for each size and swap between them.
Troubleshooting common font problems
If your text appears as boxes or does not show up at all, the most common cause is a wrong path in your .font file. Double-check that the tile_set line points to the correct file relative to your project root. Paths are case-sensitive on Mac and Linux, so fonts/MyFont.ttf is different from fonts/myfont.ttf.
If your TrueType font renders but looks wrong — characters are cut off, spacing is broken, or glyphs are missing — the font file itself may have issues. Try a different font to confirm. Some fonts have unusual metrics or incomplete character sets. Google Fonts and Adobe Fonts are reliable sources.
If you are using a bitmap font and characters appear in the wrong place or are stretched, check that your .fnt descriptor file matches the .png image. If you edited the image after generating the descriptor, the character positions will be wrong. Regenerate both together.
For performance, remember that each unique font size creates a separate bitmap at build time. If you use the same font at sizes 16, 32, and 64, Defold builds three separate bitmaps. Reusing sizes where possible keeps your build smaller.
Applying materials and effects to custom fonts
Your custom font respects the material assigned to the text object, just like any other visual element. By default, text uses a standard material that renders the bitmap with a tint color. You can change the tint by setting the text color in your script:
go.set("#text", "tint", vmath.vector4(1, 0, 0, 1))
This sets the text to red. You can also create a custom material for your text — for example, to add a glow, shadow, or outline effect. Assign the material to the text component the same way you would to a sprite. The font rendering pipeline is the same as any other bitmap, so any material that works on sprites will work on text.
Keep in mind that effects like outlines or shadows need extra space around each character in your bitmap. If you are using a pre-rendered bitmap font and want an outline effect, you need to either generate the font with the outline already drawn, or use a material-based approach that does not require extra pixels.
Frequently Asked Questions
Can I use web fonts or fonts from my system in Defold?
Web fonts like Google Fonts work fine — download the .ttf file and place it in your project. System fonts also work, but it is better to include the font file in your project so the game looks the same on every machine. If you rely on a system font and it is not installed on a player's computer, Defold will fall back to a default, and your text will look different.
What happens if I change the font size after I build?
Changing the size in your .font file requires a rebuild. Defold generates the bitmap at build time, so editing the file and running the game without rebuilding will not change anything. Always rebuild after editing a .font resource.
Can I use the same font at different sizes in my game?
Yes, but create separate .font resources for each size. For example, fonts/my_font_16.font with size 16 and fonts/my_font_32.font with size 32. Text objects can reference whichever one you need. This is more efficient than scaling a single bitmap up and down.
Do bitmap fonts work on all platforms Defold supports?
Yes. Bitmap fonts are just images and descriptor files, so they work on desktop, mobile, and web. TrueType fonts also work on all platforms — Defold converts them to bitmaps at build time, so the final game contains the same bitmap on every platform.
What if my custom font does not have a bold or italic version?
Create separate .font resources for each style. Download or design a bold version of your font, place it in your project, and create a my_font_bold.font resource pointing to it. Switch between them in your script depending on what style you need. Defold does not synthesize bold or italic from a regular font.