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.
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.
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 costinit draws its own artwork, so the example builds offline on a clean checkout.
- Composite Multi-Layer HUD, Actionbar & Bossbar Layout Solver (
glyphsmith layout): Solves inter-layer negative-space deltas acrossactionbar,bossbar(originY = -9, aligningy = 0directly onto the 182x5BossHealthOverlaybar),container-title(origin = 8, 6),title,subtitle,chat, andscoreboardcontexts. 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 rawalpha-sdforgrayscalefields for customrendertype_text.fshcore shaders andTextDisplaybillboards, 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 auditand OASIS SARIF v2.1.0 output withBITMAP_OPAQUE_BACKGROUND_BLEED,BITMAP_TRANSPARENT_CELL_COLLAPSE, andHUD_SHIFT_TABLE_GAPacross 26 total rules.
- 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 withTTF_VARIABLE_OPSZ_MISMATCHaudit 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.
- 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,cmapFormats 4 & 12,fvar,avar,STAT,kern, andGPOSLookupType 2 PairPos Formats 1 & 2). FlagswOFF/wOFF2web containers that Minecraft FreeType rejects and warns on OpenType variable fonts whosefvaraxes (wght,wdth,opsz,slnt) are pinned to default coordinates byTrueTypeGlyphProviderDefinition. - 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 OpenTypekern/GPOSdesign units to GUI pixels while pruning sub-pixel0pxpairs 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 example255px = +256 - 1in 2 shift glyphs instead of 8). - Format 97 Dual-Era Font Providers (
1.20.1..26.3): Compilesfilter: { uniform, jp },ttf:providers, and era-scopedversions: 26.3providers intooverlays.entries(overlay_fmt_97) while keeping dual-erapack.mcmeta(pack_format,supported_formats: [15, 64],min_format,max_format: 97) compliant across both pre-1.21.9 and 26.3 clients.
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 > heightin abitmapprovider, which causes the client to discard the entire font file.BITMAP_INVALID_HEIGHT/BITMAP_MISSING_ASCENT(error): Non-positiveheight(<= 0) or missingascentin abitmapprovider.BITMAP_MISSING_TEXTURE(error): Missing or unreadable PNG texture referenced by"file"(checked across overlay and base assets).BITMAP_IRREGULAR_GRID(error): Emptycharsarray or rows of unequal codepoint count.BITMAP_CELL_EXCEEDS_ATLAS(error): Individual glyph cell larger than256x256source pixels (FontTextureatlas 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/.otfunderassets/<ns>/font/(with detection for files mistakenly placed underassets/<ns>/textures/).TTF_UNSUPPORTED_CONTAINER(error): Web-compressedwOFF/wOFF2font or corrupt/truncated SFNT tables rejected by FreeType.TTF_INVALID_METRICS(error): Non-positivesizeoroversample, malformedshifttuple, or invalidskipfield on attfprovider.TTF_VARIABLE_FONT_UNPINNED_AXES(warning): OpenType variable font withfvaraxes that Minecraft FreeType pins to default coordinates, plusgvarbyte overhead reporting.TTF_EMPTY_CMAP(warning):ttfprovider exposing zero usable Unicode codepoints aftercmapandskipfiltering.UNIHEX_INVALID_PROVIDER(error): Missinghex_filearchive or malformedsize_overridesentries on aunihexprovider.PROVIDER_INVALID_FILTER(error): Providerfilterdeclaring options outsideFontOption.CODEC(uniform,jp) or non-boolean values.PACK_MCMETA_FORMAT_CONFLICT/OVERLAY_FORMAT_CONFLICT(error): Format 97 (26.3) vs pre-minor (<= 64)pack.mcmetaandoverlays.entriesschema conflicts (such assupported_formatsor legacyformatson modern>= 65declarations).SPACE_INVALID_ADVANCE/SPACE_INVALID_CODEPOINT_KEY(error): Quoted string, multi-codepoint key, or out-of-range advance value outsideSpaceProviderCodec 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 emptyoverlays.entries[].directorydeclared inpack.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 tocellWidth + 1.BITMAP_TRANSPARENT_CELL_COLLAPSE(warning): Sprite sheet maps a non-space codepoint to a completely transparent cell, collapsing client advance to1pxand 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.sarifCommit 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- uses: SalyyS1/glyphsmith@v0.6.0
with:
args: build glyphs.yml --locked --strictAudit 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 }}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.3Give 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.
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 reportpack/
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.
| 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 |
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).
./gradlew build --no-daemon # runs JUnit 5 suite and builds build/libs/glyphsmith-0.6.0.jar- 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.
See NOTICE for upstream references (unnamed/creative, Brikster/glyphs, AmberWat/NegativeSpaceFont). Independent project; not affiliated with Mojang or Microsoft. Licensed under Apache-2.0.