Generate SDF Fonts for Crisp UI Text

You do not need to install an external font generator for the supported Lenga workflow. The editor can generate a Lenga SDF font asset from a .ttf or .otf font file.

What This Covers

By the end of this guide, you will know how to:

• import a normal font file
• generate a Lenga .sdf-font.json font asset
• assign that generated font to a Text element
• tune SDF outline width and edge softness
• use the same SDF font from PHP

What SDF Means

SDF stands for signed distance field.

Instead of storing only the final pixels of each letter, an SDF atlas stores distance information around each glyph shape. Lenga's text shader uses that distance information to redraw the glyph edge cleanly at different sizes.

That is why SDF text is useful for:

• menu titles
• outlined HUD labels
• buttons that scale or animate
• text that needs a crisp outline
• game UI that should look clean at several resolutions

For ordinary small labels that never scale and do not need outlines, a normal .ttf or .otf font can still be fine.

The Full Workflow

The complete editor workflow is:

1. Put a .ttf or .otf font somewhere under your project's Assets folder.
2. In the Assets panel, find that font file.
3. Right-click the font.
4. Choose Generate SDF Font.
5. Lenga creates two files next to the font:
   • a generated SDF atlas image
   • a generated .sdf-font.json metadata file
6. Select a Text element in your scene.
7. In the Inspector, assign the generated .sdf-font.json file to the Font field.
8. Confirm Use SDF is enabled.
9. Adjust SDF Outline and SDF Softness until the text looks right.

That generated .sdf-font.json file is the asset you assign to UI text. The original .ttf or .otf file remains the source font.

Step 1: Add a Font to Your Project

Copy a font file into your project, for example:

Assets/Fonts/MenuTitle.ttf

After the editor refreshes the Assets panel, it should show up as a font asset.

Step 2: Generate the SDF Font Asset

Right-click the font in the Assets panel and choose:

Generate SDF Font

Lenga generates a new font metadata asset next to the source font. For example:

Assets/Fonts/MenuTitle.sdf-font.json

It also generates a companion atlas PNG next to that metadata file. You normally do not need to edit the atlas image by hand.

If a file with that name already exists, Lenga creates the next available name, such as:

Assets/Fonts/MenuTitle-2.sdf-font.json

Step 3: Assign It to a Text Element

Select a Text element in your scene.

In the Inspector:

1. Find the Font field.
2. Pick the generated .sdf-font.json asset, or drag it from the Assets panel onto the field.
3. Make sure Use SDF is checked.

When you assign an SDF font asset through the picker or by dragging it onto the field, Lenga turns Use SDF on for that text element.

If you later choose Default or assign a normal .ttf / .otf font, Lenga turns Use SDF off so the element goes back to the standard raster font path.

Step 4: Tune the Outline and Softness

The SDF-specific fields are:

• SDF Outline
• SDF Softness

SDF Outline controls how many pixels of outline are drawn around the text.

Use a small value for subtle HUD text:

SDF Outline: 1.0

Use a larger value for bold title text:

SDF Outline: 3.0

SDF Softness controls how sharp or soft the edge is.

Start with:

SDF Softness: 0.5

If the edge looks too hard or jagged, raise it slightly. If the text looks blurry, lower it.

Step 5: Use It from PHP

The PHP code belongs inside a Behaviour class attached to a scene GameObject, such as HUDController or MenuController.

The canvas does not need to live on that same GameObject. The script can find it through the active scene.

use Lenga\Engine\Core\Behaviour;
use Lenga\Engine\SceneManagement\Scene;
use Lenga\Engine\UI\Text;

final class MenuController extends Behaviour
{
    private ?Text $title = null;

    public function start(): void
    {
        $canvas = Scene::getActive()?->findCanvas('Canvas');
        $this->title = $canvas?->findTextByName('Title Text');

        if ($this->title !== null) {
            $this->title->fontPath = 'Assets/Fonts/MenuTitle.sdf-font.json';
            $this->title->useSdf = true;
            $this->title->sdfOutlineWidth = 3.0;
            $this->title->sdfSoftness = 0.5;
        }
    }
}

If you already have a Text reference from another Behaviour or helper method, you can set these properties directly on that reference. You only need the Scene::getActive()?->findCanvas(...) lookup when your code is starting from the scene and needs to find the UI element by name.

Standard Fonts Still Work

SDF fonts are opt-in.

If a Text element uses the default font or a normal .ttf / .otf font with Use SDF turned off, Lenga uses the standard raster font renderer.

That fallback is important because:

• quick prototypes do not need generated font assets
• simple labels can stay simple

Use SDF when you want sharper scalable text, stronger outlines, or a more polished UI presentation.

API Reference

For the PHP properties behind this workflow, see Text.