Skip to main content

​
Flexbox Layouts & Glyph Compilation

The GUI Extension implements a pure-Dart CSS Flexbox engine that auto-positions layers. The compiled output is a sequence of negative space Unicode characters that Minecraft’s typographic renderer interprets as pixel-precise positioning.

​
The Core Concept

​
How Minecraft Renders Text

Minecraft’s text renderer reads characters sequentially, left to right, on a single line. Each character advances the cursor by its pixel width. To create 2D layouts, we manipulate this cursor with invisible space characters:

​
Flexbox Properties

The Flexbox engine supports the full CSS Flexbox specification subset:

​
Container Properties

PropertyValuesDescription
directionrow, column, row-reverse, column-reverseMain axis direction
justifystart, end, center, space-between, space-around, space-evenlyMain axis alignment
alignstart, end, center, stretchCross axis alignment
wrapnowrap, wrap, wrap-reverseLine wrapping
rowGappixelsVertical gap between items
columnGappixelsHorizontal gap between items

​
Resolution Algorithm

​
Negative Space Font

The NegativeSpaceFont (AmberWat) maps pixel offsets to Unicode surrogate pairs: 
 Pixel offset → Unicode codepoint = 0xD0000 + offset

​
Space Ranges

CategoryRangeCodepoint Range
Positive integer1 to 8192 pixelsU+DB00 U+DC01 → U+DB08 U+DC00
Negative integer-1 to -8192 pixelsU+DAF8 U+DC00 → U+DAFF U+DFFF
FractionalRational /4800U+D8FB U+DD40 → U+D904 U+DEC0
Infinite negative-∞U+DAC0 U+DC01
Infinite positive+∞U+DB3F U+DFFF
New layerZ-fighting fixU+DAC0 U+DC00

​
The Compilation Algorithm

​
Magic Digits (Dynamic Text)

When a text layer contains PlaceholderAPI variables (e.g., %player_name%), its pixel width is unknown at design time. Magic Digits solve this with the Fibonacci sequence: 
Digit → Pixel width:
  9  →    1 px   (fib 1)
  8  →    3 px   (fib 2)
  7  →    8 px   (fib 3)
  6  →   21 px   (fib 5)
  5  →   55 px   (fib 7)
  4  →  144 px   (fib 9)
  3  →  377 px   (fib 11)
  2  →  987 px   (fib 13)
  1  → 2584 px   (fib 15)
  -  → -6765 px
The server evaluates the placeholder, measures the text width, then inserts the minimal combination of Magic Digits to absorb the offset. This preserves Flexbox alignment at runtime.

​
Example

Design-time: "Hello %player_name%!" (width unknown)
Runtime: player_name = "Steve" (measured: 45px)
          player_name = "Notch" (measured: 48px)

For Steve (45px):  insert "888888" (3+3+3+3+3+3 = 18px) + "777" (8+8+8 = 24px) = 42px + margin
For Notch (48px):  insert "777777" (8×6 = 48px)

​
Z-Fighting & newlayer

When two layers overlap at the same depth, Minecraft can’t determine which to render on top. This is Z-fighting. The compiler automatically detects overlapping layers at the same Y with intersecting X ranges and inserts newlayer when needed.

​
Font Provider Generation

Each unique Y position requires a separate font provider entry in default.json: 
{
  "providers": [
    {
      "type": "bitmap",
      "file": "typewriter:font/gui_0_16.png",
      "ascent": 0,
      "height": 16,
      "chars": ["", "", ""]
    },
    {
      "type": "bitmap",
      "file": "typewriter:font/gui_20_32.png",
      "ascent": 20,
      "height": 32,
      "chars": [""]
    }
  ]
}
  • ascent: Vertical offset from the text baseline. Higher values push the texture down
  • height: Scale of the glyph. Controls how tall it renders
  • chars: Unicode characters mapped to this texture sheet
  • file: Path to the PNG texture atlas inside the resource pack