Skip to content

Generate a font atlas

Tick UI renders text from MSDF (multi-channel signed distance field) atlases: a PNG that packs every glyph and a JSON file that records each glyph's metrics. The Font Atlas Generator window bakes these two files from a .ttf or .otf, applies the correct texture import settings, and can register the result on a GUIResourceProvider for you.

The output of this page — an atlas Texture and a Metrics JSON — is exactly what Add a custom font expects as input.

Install msdf-atlas-gen

The window does not bake glyphs itself; it drives the external msdf-atlas-gen command-line tool, which is not bundled with the package. Install it once before generating:

  1. Download a release for your platform from the msdf-atlas-gen releases page (the window's Download... button opens this page).
  2. Either place the executable on your system PATH, or note its location to point the window at it directly in the next section.

Generate an atlas

To generate an atlas:

  1. Open the window. From the menu bar, choose Tools > Tick UI > Font Atlas Generator.
  2. Confirm the tool is found. The msdf-atlas-gen section reports whether the executable was located. It checks a saved override first, then your PATH. If the status box is yellow, click Locate... and select the executable, or install it on PATH and click Re-probe PATH. Clear override forgets a previously located path and returns to PATH probing.
  3. Choose the source font. Click Browse... next to Source and select a .ttf, .otf, or .ttc. The Lookup name field auto-fills from the file name, lowercased. This name is the string you later pass to ui.Text(...), so keep it short and stable (roboto_mono, for example).
  4. Choose the output directory. Click Browse... next to Output directory. Atlases are written to <output directory>/<lookup name>/. Choose a folder inside Assets/ or Packages/ so Unity imports the results — the window warns when the path lies outside both and auto-populate is enabled.
  5. Set the sizes. Enter Min, Max, and Step. The window generates one atlas per size in that range and previews the result in the Will generate row (for example 20, 28, 36, 44, 52). Generating several sizes keeps text crisp across a range of on-screen scales.
  6. Set the atlas parameters. Dimensions is the square atlas size in pixels (512 is a sound default). Pixel range is the signed-distance spread, default 8. Increase Dimensions if a larger size cannot fit all glyphs.
  7. Generate. Click Generate. The button is enabled once the tool, font, lookup name, output directory, and at least one size are all valid. A cancelable progress bar runs the tool per size. When it finishes, the Last run output box and the Console report how many atlases were produced and any per-size tool output.

Each size produces two files in the output folder:

<lookup name>/<lookup name>_<size>_msdf.png
<lookup name>/<lookup name>_<size>_msdf.json

The window sets the import settings on every generated PNG automatically — linear (not sRGB), mipmaps disabled, uncompressed, alpha from input — so the MSDF text shader samples the distance field correctly.

Register the atlas automatically

To skip the manual provider step in Add a custom font:

  1. In the Provider section, drag your GUIResourceProvider asset into the Target field.
  2. Leave Append after generation ticked.

On a successful generation the window appends one Fonts entry per atlas — pairing the PNG Texture with the JSON Metrics Path — and skips entries the provider already holds. Leave Target empty to produce the files only and wire them up by hand later.

Auto-populate requires the output directory to be inside Assets/ or Packages/, because the provider references imported assets rather than loose files.

Pitfalls

The Generate button stays disabled. : One required field is unset or invalid: the tool was not found, the source font path does not exist, the lookup name or output directory is empty, or the size range produces no sizes. The disabled button enables as soon as all are valid.

The tool is not found even though it is installed. : It is not on PATH. Click Locate... and select the executable directly, which saves an override for future runs.

Auto-populate did nothing. : The output directory is outside Assets/ and Packages/, so Unity did not import the generated files. Regenerate into a folder under the project, or add the entries manually.

A size renders blank or clipped. : The glyphs did not fit the atlas at that size. Increase Dimensions and regenerate.

Additional resources