Skip to content

About

Deterministic Minecraft bitmap font glyph solver, lockfile compiler, and resource-pack font auditor CLI.

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

glyphsmith

build release web inspector license

glyphsmith turns PNG artwork, TrueType/OpenType fonts, and pixel coordinates into deterministic, lock-pinned Minecraft resource packs spanning 1.20.1..26.3 (format 97), solves composite 26.3 HUD/bossbar/actionbar negative-space layouts, generates exact 2D Euclidean Signed Distance Field (SDF) glyphs, optimizes kerning pairs and signed-digit shift runs, and audits single or stacked packs with OASIS SARIF v2.1.0 output. You say where the artwork goes; glyphsmith derives the provider height, the ascent, the transparent bottom padding required for that ascent to be legal at 1:1 scale, the client pixel advance, and the negative-space characters that place the glyph and restore the cursor.

Try the zero-upload client-side Browser 26.3 HUD Composer, 2D SDF Lab, Font Pack Auditor & Glyph Metric Solver directly in your browser.

$ glyphsmith build glyphs.yml
== myserver:ui -> pack
   ui.panel  U+F0016  176x64  h 64  a 13  adv 177
   hud.coin  U+F0017  9x9     h 9   a 8   adv 9
   shift glyphs cover 1..1024px in both directions

   ui.panel: \uDB80\uDC07\uDB80\uDC16\uDB80\uDC0F\uDB80\uDC0B\uDB80\uDC07\uDB80\uDC01
   hud.coin: \uDB80\uDC17

Wrote 2 glyphs to pack
Codepoints pinned in glyphs.lock.json
Strings in glyphs.snippets.txt

The panel in that run is aimed at the top-left corner of a container window. What came out is ascent: 13, height: 64, a leading 8px shift and a 169px shift afterwards to put the cursor back where the title expects it: six numbers that are usually found by editing a JSON file, restarting the client, squinting, and repeating.

Why this exists

Two rules in the client collide, and everything difficult about image glyphs comes out of that collision.

The first is a hard error: ascent may not be greater than height, and a font file that breaks it is rejected whole, taking every unrelated glyph in it down with it. The second is that height is not the height of your image: it is a render height, and the client divides it by the cell height to get the scale factor. Raising height to buy headroom for a larger ascent magnifies the texture.

The way out is to pad the source with transparent rows at the bottom, which grows the cell so height can grow with it at the same ratio. That is what ItemsAdder's documentation describes when it advises adding blank pixels on the bottom of an image to raise height without scaling. It is not a calculation you have to perform by hand, and glyphsmith solves it automatically.

The advance is the other half. The client measures it from your artwork (the rightmost column with any ink, scaled, rounded, plus one unconditional pixel), so a glyph's width is never what you declared and horizontal layout drifts by a pixel or two per glyph. glyphsmith reads the same pixels and emits the exact correction.

Why Minecraft Bitmap Glyphs Break and How glyphsmith Solves Them

Getting started

You need Java 21 or newer. Download glyphsmith-0.6.0.jar from Releases, then:

glyphsmith init                             # writes glyphs.yml and two PNGs to start from
glyphsmith build glyphs.yml --zip pack.zip  # writes pack/, pack.zip, glyphs.lock.json and glyphs.snippets.txt
glyphsmith layout hud.yml                   # solves composite 26.3 actionbar/bossbar/GUI negative-space layout
glyphsmith sdf art/hud.coin.png --spread 6  # generates O(W*H) 2D Euclidean SDF texture with Voronoi RGB dilation
glyphsmith audit pack.zip --strict          # audits every font provider, overlay, and PNG/TTF against client rules
glyphsmith ttf fonts/Inter-Variable.ttf     # extracts SFNT variable axes, cmap coverage, and GUI pixel kerning
glyphsmith opsz fonts/Inter-Variable.ttf    # compiles optical sizing alignments across Minecraft UI contexts
glyphsmith coverage fonts/Custom.ttf        # analyzes Unicode 16.0 plane coverage and script completeness
glyphsmith rasterize fonts/Custom.ttf A     # rasterizes glyph with horizontal 3x LCD sub-pixel RGB stripes
glyphsmith kern art/L.png art/T.png         # solves optical contour kerning and minimal signed-digit shift cost

init draws its own artwork, so the example builds offline on a clean checkout.

Composite 26.3 HUD Layout Solver & 2D Signed Distance Field Generator (v0.6.0)

  • Composite Multi-Layer HUD, Actionbar & Bossbar Layout Solver (glyphsmith layout): Solves inter-layer negative-space deltas across actionbar, bossbar (originY = -9, aligning y = 0 directly onto the 182x5 BossHealthOverlay bar), container-title (origin = 8, 6), title, subtitle, chat, and scoreboard contexts. Enforces zero-width cursor balancing (finalNetAdvancePx = 0) so centered overlays never shift horizontally when text changes, and schedules disjoint same-z layers via precedence-constrained Held-Karp dynamic programming (respecting z-index and 2D painter's occlusion) paired with signed-digit NAF shift compression.
  • Exact O(W * H) 2D Euclidean Signed Distance Field (SDF) Generator (glyphsmith sdf): Implements Felzenszwalb and Huttenlocher's separable lower-envelope parabola distance transform with 2D Voronoi nearest-seed RGB color dilation (preventing dark bilinear fringes on transparent skirts) and sub-pixel anti-aliased boundary contour refinement. Exports raw alpha-sdf or grayscale fields for custom rendertype_text.fsh core shaders and TextDisplay billboards, or analytically reconstructs multi-scale anti-aliased sprites with crisp vector outlines (--mode reconstruct --scale 2.0 --outline 1.5).
  • HUD & Sprite-Sheet Audit Diagnostics: Extends glyphsmith audit and OASIS SARIF v2.1.0 output with BITMAP_OPAQUE_BACKGROUND_BLEED, BITMAP_TRANSPARENT_CELL_COLLAPSE, and HUD_SHIFT_TABLE_GAP across 26 total rules.

Variable Font Optical Sizing, Unicode 16.0 Validator & Sub-Pixel Rasterizer (v0.5.0)

  • Variable Font Optical Sizing Axis Compiler (glyphsmith opsz): Compiles optical size (opsz) axis alignments and normalized design coordinates across 6 standard Minecraft UI contexts (chat 9pt, hotbar 8pt, tooltip 10pt, inventory 11pt, subtitle 16pt, title 24pt), calculates piecewise-linear avar warps, and generates size-matched provider configs with TTF_VARIABLE_OPSZ_MISMATCH audit rule.
  • Unicode 16.0 Plane Coverage Validator (glyphsmith coverage): Analyzes coverage across all 17 Unicode planes (BMP, SMP, SIP, TIP, SSP, Plane 15/16 PUAs) and standard script blocks, validating UTF-16 surrogate safety (UNICODE_SURROGATE_HAZARD), legacy bitmap plane boundaries (UNICODE_PLANE_UNSUPPORTED_PROVIDER), and essential script completeness (UNICODE_COVERAGE_GAP).
  • Sub-Pixel Glyph Rasterizer (glyphsmith rasterize): Renders TrueType glyphs with horizontal 3x LCD sub-pixel RGB stripes and gamma correction (default gamma 2.2) to prevent chat contrast thinning on dark backgrounds, exporting baseline-aligned Minecraft bitmap textures (ascent=7) and provider JSON.

TrueType / OpenType Variable Font Extraction & Kerning Pair Optimization (v0.4.0)

  • Binary SFNT & Variable Font Inspector (glyphsmith ttf): Parses uncompressed TrueType (.ttf), OpenType CFF (.otf), and TrueType Collection (.ttc) binaries offline (head, hhea, maxp, hmtx, name, cmap Formats 4 & 12, fvar, avar, STAT, kern, and GPOS LookupType 2 PairPos Formats 1 & 2). Flags wOFF/wOFF2 web containers that Minecraft FreeType rejects and warns on OpenType variable fonts whose fvar axes (wght, wdth, opsz, slnt) are pinned to default coordinates by TrueTypeGlyphProviderDefinition.
  • Optical Bitmap & OpenType Kerning Pair Optimizer (glyphsmith kern): Projects adjacent bitmap glyphs onto Minecraft's baseline pixel grid (top = 7 - ascent) to compute exact alpha-contour horizontal kerning shifts, and quantizes OpenType kern/GPOS design units to GUI pixels while pruning sub-pixel 0px pairs and extracting per-glyph right-bearing biases.
  • Signed-Digit Non-Adjacent Form (NAF) Minimal Shifts (compact_shifts: true / shift --compact): Uses dynamic programming over signed powers of two (+/-1 .. +/-2^k) to compress contiguous 1-bit shift runs (for example 255px = +256 - 1 in 2 shift glyphs instead of 8).
  • Format 97 Dual-Era Font Providers (1.20.1..26.3): Compiles filter: { uniform, jp }, ttf: providers, and era-scoped versions: 26.3 providers into overlays.entries (overlay_fmt_97) while keeping dual-era pack.mcmeta (pack_format, supported_formats: [15, 64], min_format, max_format: 97) compliant across both pre-1.21.9 and 26.3 clients.

Auditing resource packs and multi-pack stacks (glyphsmith audit)

Server resource packs merged from multiple plugins or stacked in load order often break silently on the client. glyphsmith audit inspects one or more resource pack directories or .zip archives (whether generated by glyphsmith, Oraxen, Nexo, ItemsAdder, BetterHud, or hand-written), resolves pack.mcmeta overlays.entries with base fallback, and validates every font definition across 26 rules:

  • BITMAP_ASCENT_EXCEEDS_HEIGHT (error): ascent > height in a bitmap provider, which causes the client to discard the entire font file.
  • BITMAP_INVALID_HEIGHT / BITMAP_MISSING_ASCENT (error): Non-positive height (<= 0) or missing ascent in a bitmap provider.
  • BITMAP_MISSING_TEXTURE (error): Missing or unreadable PNG texture referenced by "file" (checked across overlay and base assets).
  • BITMAP_IRREGULAR_GRID (error): Empty chars array or rows of unequal codepoint count.
  • BITMAP_CELL_EXCEEDS_ATLAS (error): Individual glyph cell larger than 256x256 source pixels (FontTexture atlas limit).
  • BITMAP_GRID_MISMATCH (warning): PNG dimensions not evenly divisible by grid column/row counts, causing right/bottom pixel truncation.
  • TTF_MISSING_FILE (error): Missing .ttf/.otf under assets/<ns>/font/ (with detection for files mistakenly placed under assets/<ns>/textures/).
  • TTF_UNSUPPORTED_CONTAINER (error): Web-compressed wOFF/wOFF2 font or corrupt/truncated SFNT tables rejected by FreeType.
  • TTF_INVALID_METRICS (error): Non-positive size or oversample, malformed shift tuple, or invalid skip field on a ttf provider.
  • TTF_VARIABLE_FONT_UNPINNED_AXES (warning): OpenType variable font with fvar axes that Minecraft FreeType pins to default coordinates, plus gvar byte overhead reporting.
  • TTF_EMPTY_CMAP (warning): ttf provider exposing zero usable Unicode codepoints after cmap and skip filtering.
  • UNIHEX_INVALID_PROVIDER (error): Missing hex_file archive or malformed size_overrides entries on a unihex provider.
  • PROVIDER_INVALID_FILTER (error): Provider filter declaring options outside FontOption.CODEC (uniform, jp) or non-boolean values.
  • PACK_MCMETA_FORMAT_CONFLICT / OVERLAY_FORMAT_CONFLICT (error): Format 97 (26.3) vs pre-minor (<= 64) pack.mcmeta and overlays.entries schema conflicts (such as supported_formats or legacy formats on modern >= 65 declarations).
  • SPACE_INVALID_ADVANCE / SPACE_INVALID_CODEPOINT_KEY (error): Quoted string, multi-codepoint key, or out-of-range advance value outside SpaceProvider Codec bounds [-8192, 8192].
  • REFERENCE_CYCLE / REFERENCE_MISSING_ID (error): Circular "type": "reference" chains (A -> B -> A) or malformed font identifiers.
  • REFERENCE_MISSING_TARGET (warning): Custom "reference" target font missing across the pack or stack.
  • OVERLAY_INVALID_DIRECTORY (error): Invalid or empty overlays.entries[].directory declared in pack.mcmeta.
  • TTF_VARIABLE_OPSZ_MISMATCH (warning): TrueType variable font render size deviates significantly from default optical size (opsz) without optical instantiation.
  • UNICODE_SURROGATE_HAZARD (error): Malformed, lone high or lone low UTF-16 surrogate (U+D800..U+DFFF) detected in font definition, risking JVM encoding exceptions.
  • UNICODE_PLANE_UNSUPPORTED_PROVIDER (warning): Bitmap provider declares non-BMP (Plane 1+) characters without format 97 / UTF-16 surrogate handling.
  • UNICODE_COVERAGE_GAP (warning): Essential script or language localization block missing glyph definitions.
  • CODEPOINT_SHADOWED / CROSS_PACK_CODEPOINT_COLLISION (warning): Intra-font or cross-pack codepoint overwrites in load order.
  • CODEPOINT_BMP_PUA_HAZARD (warning): Allocation inside BMP Private Use Area (U+E000..U+F8FF) where custom-item plugins collide.
  • BITMAP_OPAQUE_BACKGROUND_BLEED (warning): Bitmap provider PNG saved without an alpha channel, rendering solid background rectangles and inflating advance to cellWidth + 1.
  • BITMAP_TRANSPARENT_CELL_COLLAPSE (warning): Sprite sheet maps a non-space codepoint to a completely transparent cell, collapsing client advance to 1px and desynchronizing composite HUD layouts.
  • HUD_SHIFT_TABLE_GAP (warning): Negative-space shift table missing intermediate power-of-two steps or symmetric positive restore steps.
glyphsmith audit server-pack.zip --strict
glyphsmith audit base-ui.zip items-pack.zip hud-pack.zip --strict --json > stack-audit.json
glyphsmith audit server-pack.zip --sarif glyphsmith.sarif

CI lockfile verification, SARIF v2.1.0, and JSON output

Commit glyphs.lock.json alongside glyphs.yml. In pull request CI, pass --locked to guarantee that no glyph allocates unreviewed codepoints and no source PNG or solved metric drifted from the committed lockfile:

glyphsmith build glyphs.yml --locked --strict --json
glyphsmith plan art/hud.coin.png --at 0,-6 --json

GitHub Action & GitHub Code Scanning (SARIF)

- uses: SalyyS1/glyphsmith@v0.6.0
  with:
    args: build glyphs.yml --locked --strict

Audit stacked server packs and upload OASIS SARIF v2.1.0 results to GitHub Code Scanning:

- uses: SalyyS1/glyphsmith@v0.6.0
  id: font-audit
  with:
    args: audit build/base-pack.zip build/hud-pack.zip
    sarif: build/glyphsmith.sarif

- uses: github/codeql-action/upload-sarif@v3
  if: always()
  with:
    sarif_file: ${{ steps.font-audit.outputs.sarif-file }}

The spec file

namespace: myserver              # where the textures and ttf binaries live
font: myserver:ui                # the font id the glyphs go on
versions: 1.20.1..26.3           # what pack.mcmeta has to satisfy
codepoints: U+F0000              # where allocation starts
shifts: 1024                     # largest single shift step
compact_shifts: true             # optional signed-digit NAF minimal shift encoding

glyphs:
  ui.panel:
    image: art/ui.panel.png
    anchor: container-title       # coordinates are the window's own top-left corner
    at: [0, 0]

  hud.coin:
    image: art/hud.coin.png
    height: 9                     # or state the two numbers yourself
    ascent: 8
    filter:
      uniform: false              # optional GlyphProviderConditional filter

  hud.badge26:
    image: art/hud.badge26.png
    height: 10
    ascent: 8
    versions: 26.3                # automatically compiled into overlay_fmt_97

ttf:
  body.sans:
    file: fonts/Inter-Regular.ttf
    size: 11.0
    oversample: 2.0
    versions: 26.3

Give a glyph at and an anchor and the numbers are derived; give it height and ascent and they are passed through and checked. Mixing the two is an error, and unknown keys (ascnet: 8) are refused by name. See docs/spec.md for the full reference.

Working out one glyph (glyphsmith plan) and kerning (glyphsmith kern)

plan runs the solver without writing files:

$ glyphsmith plan art/hud.coin.png --at 0,-6
art/hud.coin.png  9x9, alpha yes
   ink        8px wide, 8px tall
   placement  0,-6 relative to wherever the text is drawn -> (0, -6) from the text origin
   height     13
   ascent     13   (top edge lands -6px below the text origin)
   padding    4px below, 0px right, added so the cell divides evenly and the ascent is legal
   cells      1 of 9x13px, scale 1.0
   advance    9 = 9px
   restore    -9px puts the cursor back where it started

Query commands for existing lockfiles and fonts:

glyphsmith string ui.panel --as minimessage    # print the string without rebuilding
glyphsmith shift --compact --as escape -- 255  # +256px and -1px in 2 shift glyphs instead of 8
glyphsmith ttf fonts/Inter-Variable.ttf --json # JSON report of fvar axes & quantized pixel kerning
glyphsmith kern art/L.png art/T.png --json     # JSON optical kerning & NAF shift cost report

What lands on disk

glyphsmith Deterministic Build Pipeline

pack/
  pack.mcmeta
  assets/myserver/font/ui.json                 # one space provider, then bitmap/ttf providers
  assets/myserver/textures/font/ui.panel.png   # your artwork, padded as needed
  overlay_fmt_97/                              # emitted automatically when era-scoped versions: are used
glyphs.lock.json                               # id -> codepoint, sha256, and solved metrics
glyphs.snippets.txt                            # every glyph as raw, escape, MiniMessage and JSON

Output is byte-stable for identical inputs: zip entries carry a fixed timestamp, files are written in sorted order, and codepoint allocation is append-only so existing signs, item lore, and database rows never change meaning.

Client font formulas

Property Vanilla client formula
cell size imageWidth / columns by imageHeight / rows, integer division (uneven division truncates remainder pixels)
scale height / cellHeight, so height is a render height and doubles as the scale factor
top edge 7 - ascent, in pixels from the text origin (ascent: 7 aligns with the baseline)
advance (int)(0.5 + inkWidth * scale) + 1, where inkWidth is one past the rightmost column with non-zero alpha
hard limit ascent > height rejects the entire font file
hard limit cells exceeding 256x256 source pixels fail atlas stitching and render as missing-glyph boxes

Codepoints and pack.mcmeta

Allocation defaults to Plane 15 (U+F0000, Supplementary Private Use Area A, 65,534 codepoints) rather than BMP Private Use Area (U+E000..U+F8FF), avoiding collisions with Oraxen, Nexo, and ItemsAdder default ranges.

For versions: 1.20.1..26.3, glyphsmith emits dual-era pack.mcmeta fields (pack_format, supported_formats, min_format, and max_format) satisfying both pre-1.21.9 (format <= 64) and modern minor-format rules (format >= 65, up to 26.3 format 97).

Building from source

./gradlew build --no-daemon    # runs JUnit 5 suite and builds build/libs/glyphsmith-0.6.0.jar

Related Minecraft Engineering Tools by Salyvn

  • packmerge: Deterministic multi-plugin Minecraft resource pack compiler for fonts, 1.21.4+ item models, sounds, lang files, and atlases.
  • packmigrate: Automated resource pack migrator across Minecraft format versions and 1.21.4+ item definitions.
  • shadersmith: Vanilla core-shader and post-effect pipeline validator and builder for Minecraft resource packs.
  • foliascan: Static bytecode analyzer with SARIF call-graph taint flows for Paper and Folia server plugins.
  • pluginscope: Plugin JAR dependency, shadow-relocation, and Paper/Spigot compatibility auditor.
  • serverdoctor: Live config, JVM flag, and crash/timings diagnostic CLI for Minecraft servers.
  • mcstage: Reproducible staging environment builder for Paper, Folia, and Velocity server networks.
  • minecraftkit: MCP server and engineering knowledge kit for Minecraft plugin and pack development.

Credits and Licence

See NOTICE for upstream references (unnamed/creative, Brikster/glyphs, AmberWat/NegativeSpaceFont). Independent project; not affiliated with Mojang or Microsoft. Licensed under Apache-2.0.

About

Deterministic Minecraft bitmap font glyph solver, lockfile compiler, and resource-pack font auditor CLI.

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages