🖥️Custom GUIs & HUDs
On Java, custom GUIs comes down to two things, and Scaffolding reproduces both on Bedrock:
Custom GUIs are a glyph (a unicode character defined in a font file) placed in the title of a custom inventory.
HUD overrides are replaced vanilla HUD textures, such as the hearts, hotbar or armor bar.
Scaffolding reads these straight from the pack's fonts and textures, so it is not tied to any one plugin's glyph setup. Conversion is automatic in the common case.
Alignment is approximate
Bedrock and Java lay their screens out differently, and Bedrock gives far less control over placement. The automatic conversion gets most screens close, but it is not guaranteed pixel-perfect, and some GUIs can show larger inconsistencies. Simple, chest-based screens convert best; dense or heavily custom layouts are the most likely to need a manual nudge.
Anything the automatic placement gets wrong can be corrected by hand, see Tweaking a GUI manually.
Custom GUI backgrounds
A custom inventory background on Java is a tall glyph placed in the container's title. Bedrock has no title glyph, so Scaffolding takes that glyph's texture and draws it onto the Bedrock screen instead, shown only while that container is open.
This is automatic for every glyph Nexo uses as a background in a GUI title:
The texture is placed on the matching Bedrock screen, sized and positioned to line up with the slot grid.
It shows only while that container is open, matched by the container title.
Any
<shift:N>in front of the glyph in the Java title is folded into the overlay's placement, since Bedrock cannot shift title text itself.autoBackgroundsingui.ymltoggles the whole feature (on by default, see below).
Only glyphs actually used in a Nexo GUI title are turned into overlays, so a random tall glyph elsewhere in your pack does not become a stray background. Anything Nexo does not put in a title, a GUI from another plugin for instance, has to be added by hand.
Tweaking a GUI manually
Everything the automatic conversion decides can be overridden per GUI in plugins/Scaffolding/gui.yml. Most setups never need this; reach for it when a background sits a few pixels off, renders at the wrong size, or when you want a glyph that was not picked up automatically.
Scaffolding writes the file for you on the first conversion if it does not exist, seeded with:
your auto-detected backgrounds, commented out, ready to uncomment and override
every other tall glyph as a commented candidate you can enable
Once the file exists it is never rewritten, so your edits are safe. Delete it if you want a fresh, re-seeded copy.
GUI Visualizer
A visual tool for working out the alignment, instead of guessing at numbers, is available at https://nexomc.com/tools/gui-visualizer.
After editing gui.yml, run /scf reload -f and have your Bedrock players reconnect. Bedrock only re-downloads the pack on reconnect.
Settings
Two top-level keys, both optional:
autoBackgrounds
true
Detect GUI backgrounds from your Nexo inventory titles. Set to false to show only the entries you list in this file.
minHeight
32
Minimum glyph height, in pixels, for a glyph to be listed as a commented candidate when the file is generated. Does not affect conversion.
Entries
Each entry is keyed by its glyph id and overrides the automatic overlay for that glyph. Only glyph is required, every other field falls back to the automatic value.
glyph
required
The Nexo glyph whose texture is drawn. Its texture and unicode are resolved from Nexo, so the id is all you need.
match_literal
the glyph
Java title, written with Nexo tags such as "<glyph:my_gui>". The overlay shows only while the open container's title contains it.
match_title
-
Same as above but a raw literal string, with no tag resolution. Use it when the title carries no Nexo tag.
shift
0
Horizontal nudge in pixels, mirroring the <shift:N> in front of the glyph on Java. Positive moves right.
size
auto
"W,H". "162px,54px" is fixed UI pixels, "100,100" or "100%,100%" is a percentage of the parent panel. Prefer pixels: they align to Bedrock's 18px slot grid without drift.
offset
auto
"x,y" pixel offset from the anchor. Positive x moves right, positive y moves down.
anchor
center
Where the image attaches to the screen. center for window art, top_left and the other JSON-UI anchors for HUD pieces.
layer
13
Draw order. 13 sits above the slot backgrounds and below the item icons; raise it to draw over items, lower it to hide behind them.
screen
container
Which Bedrock screen the art is injected into, see the table below.
An entry with no match, or with a match_literal that cannot be resolved (a typo'd glyph id, for example), is always visible on that screen. Scaffolding logs a warning when this happens.
Screens
screen
Where it draws
container / chest
Chest and double chest, the default for custom inventories.
shulker_box
Shulker box.
inventory
The whole survival inventory screen.
player_inventory
The inventory window's top half only.
crafting_table
Crafting table window.
furnace, blast_furnace, smoker
The 176x166 window of each smelting screen.
enchanting
Enchanting table.
anvil
Anvil.
smithing_table
Smithing table.
grindstone
Grindstone.
brewing_stand
Brewing stand.
villager
The right panel of the trading screen.
hud
The in-game HUD, drawn on top of everything.
Commands
/scf gui list
List the active overlays, auto-detected and from gui.yml, with the screen and title match each one uses.
/scf gui import <glyph> [screen]
Append an entry for a glyph to gui.yml and reconvert. Size and offset are left to auto-detect.
Advanced: injection points
Bedrock's own screen and control names occasionally move between game versions. If an update breaks a screen, the injection point can be repointed per entry without waiting for a Scaffolding update.
ui_file
Bedrock JSON-UI file to patch, for example ui/chest_screen.json.
namespace
JSON-UI namespace of that file, for example chest.
root
A single control to insert the overlay into.
roots
A list of controls, for screens with more than one panel (small/large chest).
array
Name of the child array on the control, controls on every vanilla screen.
layer_bias
Layer offset compensating the root's own depth, so layer means the same everywhere.
A malformed gui.yml is ignored entirely and a single bad entry is skipped, in both cases with a warning in the console. Conversion carries on either way, so a typo can never break your pack.
Sizing a glyph
Bedrock renders a glyph at its baked pixel size, so size and sharpness move together — a bigger bake is larger and sharper, a smaller bake is smaller and blockier. Override that bake per font or per glyph in plugins/Scaffolding/glyphs.yml. Most setups never touch this file.
Two sections, both keyed by id: fonts: (by font key) and glyphs: (by glyph id). A glyphs: entry wins over a fonts: entry for the same glyph. Every field is optional.
scale
Multiply the glyph's Java height. 2.0 = twice as tall, and sharper.
height
Pin an explicit baked height in px. Overrides scale.
supersample
Bake from the full-resolution source texture instead of the Java height. Sharpest, but renders larger — good for big or UI glyphs.
Vanilla GUI overrides
If your pack reskins a vanilla container screen (by replacing its texture), Scaffolding reproduces that on the matching Bedrock screen too. This is controlled by vanillaBackground.convertOverrides in config.yml (on by default; turn it off if you do not reskin vanilla content and want a smaller pack).
vanillaBackground.hideBackground (also on by default) hides Bedrock's own window background behind those reskins, so nothing vanilla peeks out from under your art. Turn it off to keep the gray panel drawn behind it.
Supported screens, if present in your pack:
Chest, double-chest and ender chest
Shulker box
Furnace, blast furnace and smoker
Crafting table
Player inventory
Enchanting table
Anvil
Brewing stand
Villager trading
Hopper, dropper and dispenser are not supported
These Bedrock screens are hard-coded and cannot be customized via a resourcepack at the moment, so they cannot be altered. They are noted in the conversion log and left as vanilla for Bedrock players.
Vanilla HUD overrides
Retextures of the vanilla HUD are converted to their Bedrock equivalents. Bedrock scales each texture to fit its on-screen element, so the source resolution does not matter.
Converted HUD elements include:
Hotbar and the selected-slot box
Hearts (health, absorption, frozen, vehicle/mount)
Hunger, Armor, air & experience bars
Mob-effect status backgrounds
Locator bar
A few Java-only HUD states have no Bedrock counterpart and are left out (and noted in the log): poisoned/withered/hardcore hearts, the crosshair and attack indicators, the jump/ride bar, per-effect status icons and offhand slots.
Custom HUD plugins are not supported yet
This only covers retextures of the vanilla HUD. Custom HUDs added by plugins such as MythicHUD are not supported at the moment.
Last updated