FlixelFontRegistry

View source

class

org.flixelgdx.text.FlixelFontRegistry

public final class FlixelFontRegistry

A global registry for TrueType (.ttf/.otf) fonts that can be used with FlixelText.

Fonts are registered once with a unique string identifier and an asset path, then referenced by that identifier throughout the game. The registry caches FreeTypeFontGenerator instances internally so that multiple FlixelText objects sharing the same font ID reuse the same generator, avoiding redundant file parsing. Generated BitmapFont instances are also cached (keyed by font source and glyph parameters) so repeated FlixelText instances with the same settings share one texture-backed font. The built-in libGDX default bitmap font is cached per pixel size.

Usage

// Register fonts at startup (e.g. in your FlixelState.create()):
FlixelFontRegistry.register("pixel", Gdx.files.internal("fonts/pixel.ttf"));
FlixelFontRegistry.register("ui",    Gdx.files.internal("fonts/opensans.ttf"));

// Optionally set a global default so FlixelText objects use it automatically:
FlixelFontRegistry.setDefault("ui");

// Use in FlixelText:
FlixelText title = new FlixelText(0, 0, 0, "Hello!", 32);
title.setFont("pixel");

// Clean up when the game shuts down:
FlixelFontRegistry.dispose();

Lifecycle

FlixelFontRegistry.dispose() is called when the game shuts down (in FlixelGame.dispose()) to release all cached generators. Individual entries can be removed earlier with FlixelFontRegistry.unregister(String).

Methods

register(String, FileHandle)

public static void register(String id, FileHandle fontFile)

Registers a TrueType font under the given identifier. If an entry with the same ID already exists, it is replaced (and its cached generator is disposed of).

Parameters:

Name	Description
id	A unique identifier for this font (e.g. "pixel", "main", "bold").
fontFile	A libGDX FileHandle pointing to the .ttf or .otf asset.

Throws:

Type	Description
IllegalArgumentException	if id is null/empty or fontFile is null.

---

unregister(String)

public static void unregister(String id)

Removes a previously registered font and disposes of its cached generator. Does nothing if the ID is not registered. If the removed font was the default, the default is cleared.

Parameters:

Name	Description
id	The font identifier to remove.

---

has(String)

public static boolean has(String id)

Returns whether a font with the given ID is registered.

Parameters:

Name	Description
id	The font identifier to check.

Returns: true if the font is registered.

---

getFile(String)

public static FileHandle getFile(String id)

Returns the FileHandle for a registered font.

Parameters:

Name	Description
id	The font identifier.

Returns: The font's file handle.

Throws:

Type	Description
IllegalArgumentException	if the ID is not registered.

---

getGenerator(String)

public static FreeTypeFontGenerator getGenerator(String id)

Returns the cached FreeTypeFontGenerator for a registered font, creating it lazily on first access. The generator is owned by the registry and must not be disposed by the caller.

Parameters:

Name	Description
id	The font identifier.

Returns: The shared font generator.

Throws:

Type	Description
IllegalArgumentException	if the ID is not registered.

---

getRegisteredIds()

public static Set<String> getRegisteredIds()

Returns an unmodifiable view of all currently registered font IDs.

Returns: A set of registered font identifiers.

---

setDefault(String)

public static void setDefault(String id)

Sets the global default font that FlixelText will use when no explicit font is set via FlixelText.setFont(FileHandle) or FlixelText.setFont(String). Pass null to clear the default, which causes FlixelText to fall back to libGDX's built-in bitmap font.

Parameters:

Name	Description
id	The registered font ID to use as the default, or null to clear.

Throws:

Type	Description
IllegalArgumentException	if id is non-null but not registered.

---

getDefault()

public static String getDefault()

Returns the ID of the current default font, or null if none is set.

---

getDefaultGenerator()

public static FreeTypeFontGenerator getDefaultGenerator()

Returns the FreeTypeFontGenerator for the default font, or null if no default is set.

---

obtainDefaultBitmapFont(int)

public static BitmapFont obtainDefaultBitmapFont(int pixelSize)

Returns a shared libGDX-style default BitmapFont (packaged lsans-15, scaled) so the same path works on desktop, mobile, and web. Multiple callers asking for the same size reuse one font.

Lookup order:

• Gdx.files.internal (covers web/TeaVM, where the FlixelGDX TeaVM plugin copies lsans-15.fnt/lsans-15.png into the assets/ folder, and JVM/Android layouts that ship the font in assets/).
• Gdx.files.classpath (covers JVM, where flixelgdx-core bundles the font in its JAR resources).
• libGDX's built-in new BitmapFont() (JVM only, fails gracefully on web).

Each step is wrapped in a guard so a missing or unsupported lookup (for example, Gdx.files.classpath on TeaVM) does not crash the caller. If every fallback fails, the method returns null so debug code can keep running without a font.

Parameters:

Name	Description
pixelSize	The target font size in pixels (clamped to at least 1).

Returns: A cached bitmap font, or null if no default font could be loaded on the current platform. Do not BitmapFont.dispose() it; use FlixelFontRegistry.dispose() at shutdown.

---

obtainBitmapFontFromFreeType(String, FreeTypeFontGenerator, int, int)

public static BitmapFont obtainBitmapFontFromFreeType(String cacheKeyPrefix, FreeTypeFontGenerator generator, int size, int letterSpacing)

Returns a shared BitmapFont generated from the given FreeType generator with the supplied parameters. Equivalent requests reuse the same instance.

Parameters:

Name	Description
cacheKeyPrefix	A stable prefix for this font source (e.g. "reg:myId", "file:/path/font.ttf", "def:defaultId").
generator	The generator to use on cache miss (must match the prefix's source).
size	Pixel size.
letterSpacing	Horizontal spacing between characters.

Returns: A cached font; do not dispose from FlixelText it's released with the registry's FlixelFontRegistry.dispose() or when the corresponding font is FlixelFontRegistry.unregister(String).

---

freeTypeBitmapFontKey(String, int, int)

public static String freeTypeBitmapFontKey(String cacheKeyPrefix, int size, int letterSpacing)

Builds the cache key used by FlixelFontRegistry.obtainBitmapFontFromFreeType(...) for a given source prefix and glyph settings.

---

dispose()

public static void dispose()

Disposes all cached FreeTypeFontGenerator instances and clears the registry. This should be called when the game shuts down.

---