EffectiveFontChar

A validated handle to one glyph slot in the generated resource pack: an opaque wrapper around a Supplementary Private Use Area codepoint (codePoint, planes 15–16, U+F0000 upward) that is guaranteed to map to a real, registered glyph. The supplementary PUA is used instead of the BMP PUA so glyphs never clash with the many resource packs that occupy U+E000+; SPUA-A is filled first, then SPUA-B (~131k slots).

Instances cannot be created from outside the framework — the constructor is internal and copy() follows it (@ConsistentCopyVisibility), so the token can't be forged by ordinary means. The only source is getNextFree, which auto-assigns the next free codepoint; callers never pick it themselves.

Because codepoints come from an in-memory counter, a glyph's codePoint is stable only within a single server session and may differ across restarts (it depends on allocation order). That is why the resource pack is regenerated on every start, so its font providers always match the current session. Never persist a raw glyph character (item lore saved in the world, books) — store a way to re-obtain the token instead.

Because it can only originate from a real registration, an EffectiveFontChar is a proof that its codePoint is a distinct, existing glyph. The codepoint is outside the BMP, so its text form (string, also returned by invoke) is a UTF-16 surrogate pair — embed it in chat/GUI text, lore or net.kyori.adventure.text.Components to draw the glyph.