Skip to content

GUI Toolkit

Gugas749 edited this page Nov 16, 2026 · 2 revisions

GUI toolkit

Client-only. It gives you an Abyss-styled screen base with sidebar tabs, widgets, layout helpers, dialogs and drawing helpers, with the same look and behavior on 1.20.1 and 1.21.1. Run /abyssgui in game (MODERATOR) to see every component.

com.gugas749.abysscore.api.gui
├── screen   AbyssPanelScreen, AbyssTab, TabContext
├── widget   AbyssButton, AbyssIconButton, AbyssLabel, AbyssScrollList, AbyssSlider,
│            AbyssTabButton, AbyssTextField, AbyssToggle
├── layout   AbyssLayout (column / row / grid), AbyssSized
├── dialog   AbyssDialog (alert / confirm / confirmDanger / input)
├── render   AbyssDraw (nineSlice, sprite, outline, stars, sectionTitle, trimmed)
├── theme    AbyssTheme (sprites + colors)
└── hud      AbyssHud, AbyssHudElement, HudSetting, HudEditorScreen (movable HUD + layout editor, §14.9),
             HudPlacement, HudAnchor, HudPositioning, HudBounds, HudBox, HudLayoutMath (plain maths)

14.1 Screens - AbyssPanelScreen

┌─ TITLE ─────────────────────── STAFF ✕ ┐
│ [Tab 1] │                              │
│  Tab 2  │   content area (TabContext)  │
│  Tab 3  │                              │
└─────────┴──────────────────────────────┘
public class SpellbookScreen extends AbyssPanelScreen {

    public SpellbookScreen() {
        super(Component.literal("Spellbook"));
    }

    @Override
    protected void addTabs(List<AbyssTab> tabs) {      // called once, the first time the screen opens
        tabs.add(new SpellListTab());
        tabs.add(new SettingsTab());
        tabs.add(AbyssTab.of(Component.literal("About"), ctx ->
                ctx.add(new AbyssLabel(ctx.x, ctx.y, ctx.width, Component.literal("Spellbook v1")))));
    }

    @Override protected int panelWidth()  { return 360; }   // default 320, shrunk on small windows
    @Override protected int panelHeight() { return 220; }   // default 200

    @Override
    protected AbyssPermissionLevel requiredLevel() {
        return AbyssPermissionLevel.PLAYER;                   // default MODERATOR: open to everyone
    }
}

// open it (client)
Minecraft.getInstance().setScreen(new SpellbookScreen());
Member Description
AbyssPanelScreen(Component title) Close/Esc leaves the GUI
AbyssPanelScreen(Component title, Screen parent) Close/Esc goes back to parent
addTabs(List<AbyssTab>) Required. Tabs in sidebar order. With one tab there's no sidebar and the content uses the full width.
panelWidth() / panelHeight() Preferred size
requiredLevel() Client-side gate. Below it, the screen shows "no permission" and a Close button. The server must still check.
selectTab(int) Switch tab from code
panelX, panelY, panelW, panelH The panel's current rectangle (protected)
renderPanel(g, mx, my, pt) Override to draw extra things under the widgets (call super first)
backgroundDim() ARGB drawn over the world behind the panel (default 0x90000000). Lower it to keep the world visible, e.g. for a live preview.
parent The parent screen, or null

Behavior you get for free:

  • Remembers the last open tab per screen class while the game runs.
  • Doesn't pause the game.
  • No vanilla blur on 1.21.1, so it looks the same as 1.20.1.
  • The header always shows a STAFF badge.

14.2 Tabs - AbyssTab and TabContext

public interface AbyssTab {
    Component title();
    void init(TabContext ctx);                                                     // build widgets
    default void tick(TabContext ctx) {}                                           // 20×/s while visible
    default void render(GuiGraphics g, TabContext ctx, int mx, int my, float pt) {} // drawn BEFORE widgets
    default void renderAfter(GuiGraphics g, TabContext ctx, int mx, int my, float pt) {} // drawn AFTER widgets (0.2.0)
    static AbyssTab of(Component title, Consumer<TabContext> init) { ... }         // tab without a class
}

init() runs every time the tab is shown and every time the window is resized, and it creates new widgets each time. Keep the tab's state (typed text, selection, toggle values) in fields of the tab, and give the new widgets those values in init().

TabContext Description
x, y, width, height The free content area (right of the sidebar, below the header)
add(widget) Add a widget to this tab. It's removed when switching tabs. Returns the same widget.
column(gap) / row(gap) A layout starting at the content area's top-left
font() The game font
screen() The owning AbyssPanelScreen (pass it as a dialog's parent)
open(Screen) Open a dialog or screen. Closing it returns here, on the same tab.
rebuild() Throw away and rebuild this tab's widgets, e.g. after its data changed

A tab with state:

public class SettingsTab implements AbyssTab {
    // STATE: survives tab switches and resizes
    private boolean autoCast = false;
    private double volume = 0.8;
    private String nickname = "";

    @Override public Component title() { return Component.literal("Settings"); }

    @Override
    public void init(TabContext ctx) {
        var col = ctx.column(4);
        col.add(ctx.add(new AbyssToggle(0, 0, Component.literal("Auto-cast"), autoCast, v -> autoCast = v)));
        col.add(ctx.add(new AbyssSlider(0, 0, 150, volume,
                v -> Component.literal("Volume: " + Math.round(v * 100) + "%"),
                v -> volume = v)));
        AbyssTextField nick = col.add(ctx.add(new AbyssTextField(0, 0, 150, Component.literal("Nickname..."))));
        nick.setValue(nickname);
        nick.setResponder(text -> nickname = text);

        col.space(6);
        col.add(ctx.add(new AbyssButton(0, 0, 80, Component.literal("Save"),
                b -> MyPackets.CHANNEL.sendToServer(new SaveSettingsPacket(autoCast, volume, nickname)))));
    }
}

A tab that refreshes its data:

public class OnlineTab implements AbyssTab {
    private int lastCount = -1;

    @Override public Component title() { return Component.literal("Online"); }

    @Override
    public void init(TabContext ctx) {
        // build a list from current data...
    }

    @Override
    public void tick(TabContext ctx) {
        var conn = Minecraft.getInstance().getConnection();
        int count = conn == null ? 0 : conn.getOnlinePlayers().size();
        if (count != lastCount) {                 // only rebuild when something changed
            lastCount = count;
            ctx.rebuild();
        }
    }
}

Drawing text and section titles in a tab:

@Override
public void render(GuiGraphics g, TabContext ctx, int mouseX, int mouseY, float partialTick) {
    AbyssDraw.sectionTitle(g, ctx.font(), Component.literal("SPELLS"), ctx.x, ctx.y);
    g.drawString(ctx.font(), "Mana: " + MyData.MANA.getClient().current(), ctx.x, ctx.y + ctx.height - 9,
            AbyssTheme.TEXT_DIM, false);
}

14.3 Widgets

All widgets are normal vanilla AbstractWidgets, so active, visible, setTooltip(...) and so on all work. Positions passed to constructors can be 0, 0 when a layout places them.

AbyssButton (20 tall, any width)

new AbyssButton(x, y, 80, Component.literal("Save"), b -> save());
new AbyssButton(x, y, 80, Component.literal("Delete"), AbyssButton.Style.DANGER, b -> delete());  // red

AbyssButton locked = ctx.add(new AbyssButton(0, 0, 64, Component.literal("Locked"), b -> {}));
locked.active = false;                                   // grey, not clickable
locked.setTooltip(Tooltip.create(Component.literal("Requires ADMIN")));
  • AbyssButton.HEIGHT = 20
  • Styles: NORMAL, DANGER. Use DANGER for destructive actions and pair it with AbyssDialog.confirmDanger.
  • Labels that are too long scroll instead of overflowing.

AbyssToggle (switch + label, 20 tall, width from the label)

AbyssToggle t = new AbyssToggle(x, y, Component.literal("Vanish"), isVanished, on -> sendVanish(on));
t.getValue();
t.setValue(true);     // from code: does NOT call onChange (that's only for clicks)

AbyssSlider (always 0.0-1.0 inside, you convert)

// 0-128 radius
new AbyssSlider(x, y, 150, radius / 128.0,
        v -> Component.literal("Radius: " + (int) (v * 128)),   // label, updated live
        v -> radius = (int) (v * 128));                         // called on every change

// Steps of 5 between 0 and 100
new AbyssSlider(x, y, 150, chance / 100.0,
        v -> Component.literal("Chance: " + (Math.round(v * 20) * 5) + "%"),
        v -> chance = Math.round(v * 20) * 5);

slider.getValue();   // 0.0-1.0

AbyssTextField (Abyss frame around a vanilla EditBox)

AbyssTextField name = new AbyssTextField(x, y, 150, Component.literal("Region name..."));  // hint text
name.setValue("spawn");
name.setMaxLength(32);
name.setFilter(s -> s.matches("[a-z0-9_]*"));          // reject other characters
name.setResponder(text -> saveButton.active = !text.isBlank());
String value = name.getValue();

Everything from EditBox works. Positions: the x, y, width you pass and setX/setY are the frame (what you see), while getX/getY/getWidth return the inner text area. Use frameX(), frameY(), outerWidth() and outerHeight() for the frame. Layouts handle this for you through AbyssSized. AbyssTextField.HEIGHT = 20.

AbyssLabel (text as a widget, trimmed with "…")

AbyssLabel status = ctx.add(new AbyssLabel(x, y, 150, Component.literal("Ready")));
status.setText(Component.literal("Saved!"))
      .color(AbyssTheme.ACCENT)
      .align(AbyssLabel.Align.CENTER);                   // LEFT (default), CENTER, RIGHT

It's 9 tall and not clickable.

AbyssScrollList<T> (a scrollable list of anything)

record SpellEntry(int id, String name, int cost) {}

AbyssScrollList<SpellEntry> list = ctx.add(new AbyssScrollList<>(ctx.x, ctx.y, ctx.width, ctx.height - 24, 14,
        (g, spell, x, y, w, h, hovered, selected) -> {
            var font = Minecraft.getInstance().font;
            g.drawString(font, spell.name(), x, y + 3, selected ? AbyssTheme.TEXT_BRIGHT : AbyssTheme.TEXT, true);
            String cost = spell.cost() + " MP";
            g.drawString(font, cost, x + w - font.width(cost) - 2, y + 3, AbyssTheme.ACCENT, true);
        }));

list.setItems(spells)                                     // replaces items; keeps the selection if still present
    .setSelected(selectedSpell)                           // restore state in init()
    .onSelect(spell -> { selectedSpell = spell; castButton.active = true; })
    .emptyText(Component.literal("No spells learned"));

list.selectable(false);       // hover-only, clicks do nothing
list.getSelected();           // or null
list.getItems();
  • Constructor: (x, y, width, height, rowHeight, RowRenderer<T>)
  • RowRenderer.render(g, item, x, y, width, height, hovered, selected): draw only the row's content. The list draws the hover/selection highlight, the scrollbar (wheel and drag) and the empty text.
  • Selection uses equals(), so records, Strings and UUIDs work best.

AbyssIconButton (a clickable icon)

// From the Abyss sheet
new AbyssIconButton(x, y, AbyssTheme.ICON_CLOSE, AbyssTheme.ICON_CLOSE_HOVER,
        Component.literal("Close"),           // used as tooltip + narration, never drawn
        () -> onClose());

// From YOUR texture: path, texture size, normal sprite, hover sprite
new AbyssIconButton(x, y, ResourceLocation.fromNamespaceAndPath("mymod", "textures/gui/icons.png"), 64, 64,
        new AbyssTheme.Sprite(0, 0, 12, 12), new AbyssTheme.Sprite(12, 0, 12, 12),
        Component.literal("Refresh"), this::refresh);

Its size is the icon's size. The Abyss sheet has only the close icon, so use your own texture for anything else.

AbyssTabButton (sidebar tab, 18 tall)

Used by AbyssPanelScreen. You only need it if you build your own tab bar:

new AbyssTabButton(x, y, 80, Component.literal("General"), () -> current == 0, () -> current = 0);

AbyssTabButton.HEIGHT = 18. It asks the supplier "am I selected?" every frame.

14.4 Layout - AbyssLayout

Widgets are positioned immediately when added, with no "arrange later" step. add returns the same widget, so you can chain it with ctx.add.

// Column: stack vertically, 4px apart
var col = AbyssLayout.column(x, y, 4);            // or ctx.column(4)
col.add(ctx.add(new AbyssButton(0, 0, 100, Component.literal("Save"), b -> save())));
col.add(ctx.add(new AbyssToggle(0, 0, Component.literal("Vanish"), false, v -> {})));
col.space(8);                                     // extra gap
int labelY = col.y();                             // where the next widget would go
col.add(...);
col.usedHeight();                                 // total height so far

// Row: side by side
var row = AbyssLayout.row(x, y, 4);               // or ctx.row(4)
row.add(ctx.add(okButton));
row.add(ctx.add(cancelButton));

// Grid: 3 columns of 64 × 20 cells, 4px gaps (widgets are resized to the cell width)
var grid = AbyssLayout.grid(x, y, 3, 64, 20, 4, 4);
for (int i = 1; i <= 9; i++) {
    grid.add(ctx.add(new AbyssButton(0, 0, 0, Component.literal("Slot " + i), b -> {})));
}
grid.skip();                                      // leave a cell empty
grid.rowsUsed();

// Centering
int bx = AbyssLayout.center(ctx.x, ctx.width, 80);   // x that centers an 80-wide widget

Right-aligned button bar at the bottom of a tab:

int w = 70, gap = 4;
var bar = AbyssLayout.row(ctx.x + ctx.width - (2 * w + gap), ctx.y + ctx.height - AbyssButton.HEIGHT, gap);
bar.add(ctx.add(new AbyssButton(0, 0, w, Component.literal("Cancel"), b -> ctx.screen().onClose())));
bar.add(ctx.add(new AbyssButton(0, 0, w, Component.literal("Apply"), b -> apply())));

AbyssSized is for widgets whose visible size differs from their widget size (AbyssTextField). Implement outerWidth() and outerHeight() on your own widget if the same applies to it.

AbyssCore uses its own layout instead of vanilla's LinearLayout/GridLayout because those were rewritten in 1.20.2 and behave differently between the two versions.

14.5 Dialogs - AbyssDialog

Pop-ups drawn over the screen that opened them. Closing (button or Esc) goes back to the parent, and the callback runs after that, so a callback may open another screen or dialog. Enter = confirm.

var screen = ctx.screen();

// OK only
ctx.open(AbyssDialog.alert(screen, Component.literal("Heads up"), Component.literal("Region saved.")));

// Cancel / Confirm
ctx.open(AbyssDialog.confirm(screen, Component.literal("Save changes?"),
        Component.literal("The region settings will be saved."),
        () -> MyPackets.CHANNEL.sendToServer(new SaveRegionPacket(...))));

// Red confirm button, for delete/reset/ban
ctx.open(AbyssDialog.confirmDanger(screen, Component.literal("Delete region?"),
        Component.literal("This cannot be undone."),
        () -> { MyPackets.CHANNEL.sendToServer(new DeleteRegionPacket(name)); ctx.rebuild(); }));

// Text input, with Confirm enabled only while the validator returns true
ctx.open(AbyssDialog.input(screen, Component.literal("Rename"),
        Component.literal("New name (3+ characters):"),
        currentName,                                  // initial text
        s -> s.trim().length() >= 3,                  // validator
        s -> MyPackets.CHANNEL.sendToServer(new RenamePacket(currentName, s.trim()))));

The message wraps automatically. The input is limited to 128 characters. Any Screen works as parent, not only an AbyssPanelScreen.

14.6 Drawing - AbyssDraw

Method Description
sprite(g, Sprite, x, y) A sprite at its own size
nineSlice(g, Sprite, border, x, y, w, h) Stretch a sprite to any size: corners copied once, edges and middle tiled
outline(g, x, y, w, h, argb) 1px outline inside the rectangle
stars(g, x, y, w, h, seed) Faint "void" stars. Same seed = same positions every frame.
sectionTitle(g, font, text, x, y) Heading in AbyssTheme.TITLE color, with shadow
trimmed(font, text, maxWidth) Text cut with "…", keeping colors and styles. Returns FormattedCharSequence.
gradientH(g, x0, y0, x1, y1, leftArgb, rightArgb) Horizontal gradient (vanilla only has vertical ones)
vignette(g, w, h, rgb, depth, strength) Screen edges darkened towards rgb over depth px (what cinematics use)
mix(argbA, argbB, t) Mixes two ARGB colours
// A custom framed box inside a tab
AbyssDraw.nineSlice(g, AbyssTheme.PANEL, AbyssTheme.PANEL_BORDER, x, y, 120, 60);
AbyssDraw.stars(g, x + 6, y + 6, 108, 48, 42L);
AbyssDraw.outline(g, x, y, 120, 60, AbyssTheme.ACCENT);
g.drawString(font, AbyssDraw.trimmed(font, longName, 100), x + 8, y + 8, AbyssTheme.TEXT, true);

sprite and nineSlice draw from AbyssCore's sheet (abysscore:textures/gui/abyss_gui.png) by default. Each has an overload for your own texture: pass the texture, its pixel size, and an AbyssTheme.Sprite for the part to draw:

Method
sprite(g, ResourceLocation texture, int texW, int texH, Sprite s, x, y) A part of your texture at its own size
nineSlice(g, ResourceLocation texture, int texW, int texH, Sprite s, border, x, y, w, h) Nine-slice from your texture
// assets/mymod/textures/gui/frames.png is 128 × 64; a 32 × 32 frame at (0, 0) with a 5px border
private static final ResourceLocation FRAMES = ResourceLocation.fromNamespaceAndPath("mymod", "textures/gui/frames.png");
private static final AbyssTheme.Sprite GOLD_FRAME = new AbyssTheme.Sprite(0, 0, 32, 32);

AbyssDraw.nineSlice(g, FRAMES, 128, 64, GOLD_FRAME, 5, x, y, 200, 80);
AbyssDraw.sprite(g, FRAMES, 128, 64, new AbyssTheme.Sprite(32, 0, 16, 16), x + 4, y + 4);

Nine-slice rule for your own art: only the four corners (border × border) are drawn once. Edges are repeated along their length and the middle is repeated both ways, so an ornament that must appear once has to fit in a corner.

14.7 Theme - AbyssTheme

Colors (ARGB):

Constant Value Use
TEXT 0xFFDCE4FF Normal text
TEXT_BRIGHT 0xFFF0F5FF Hovered / selected
TEXT_DIM 0xFF7887AF Secondary
TEXT_OFF 0xFF46506E Disabled
TITLE 0xFF78B4FF Headings
ACCENT 0xFF60D4FF Cyan highlights
DANGER_TEXT 0xFFFF96AA Destructive text
BADGE 0xFFE4466E "STAFF" badge
DIVIDER 0xFF1D2B58 Lines
ROW_HOVER 0x22507CE0 Translucent row hover
ROW_SELECTED 0x3860D4FF Translucent row selection
DIM_OVERLAY 0xB0000000 Behind dialogs

Sprites (AbyssTheme.Sprite(u, v, width, height)) and their nine-slice borders:

Sprites Border constant
PANEL PANEL_BORDER = 6
HEADER HEADER_BORDER = 4
BUTTON, BUTTON_HOVER, BUTTON_DISABLED, BUTTON_DANGER, BUTTON_DANGER_HOVER BUTTON_BORDER = 3
TAB, TAB_HOVER, TAB_SELECTED TAB_BORDER = 4
SLIDER_TRACK, SLIDER_HANDLE, SLIDER_HANDLE_HOVER SLIDER_BORDER = 3
TOGGLE_OFF, TOGGLE_OFF_HOVER, TOGGLE_ON, TOGGLE_ON_HOVER (drawn at size, 24 × 12)
FIELD, FIELD_FOCUSED FIELD_BORDER = 3
SCROLL_TRACK, SCROLL_HANDLE, SCROLL_HANDLE_HOVER SCROLL_BORDER = 2, SCROLL_WIDTH = 6
ICON_CLOSE, ICON_CLOSE_HOVER (9 × 9)

SHEET is the texture, SHEET_SIZE = 256, and rl(path) gives abysscore:<path>. A resource pack can replace assets/abysscore/textures/gui/abyss_gui.png to retheme every Abyss screen, as long as the parts stay at the same positions.

Translation keys used by the toolkit (en_us / pt_br ship with AbyssCore, and a resource pack can override them):

Key Where
gui.abysscore.close Close icon tooltip, "no permission" Close button
gui.abysscore.staff Header badge
gui.abysscore.no_permission Panel text when requiredLevel() isn't met
gui.abysscore.dialog.ok / .confirm / .cancel Dialog buttons
gui.abysscore.list.empty Default AbyssScrollList empty text
message.abysscore.no_permission Chat message from AbyssPermissionHandler.require (%s = the level)

14.8 Opening screens: three common ways

From a server packet (the server decides, e.g. after a permission check):

// server
if (AbyssPermissionHandler.require(player, AbyssPermissionLevel.MODERATOR)) {
    MyPackets.CHANNEL.sendToPlayer(player, OpenSpellbookPacket.INSTANCE);
}
// client handler
ctx.enqueueWork(() -> Minecraft.getInstance().setScreen(new SpellbookScreen()));

From a client command. The chat screen closes itself after the command runs, which would close your screen immediately, so defer it one frame with tell:

dispatcher.register(Commands.literal("spellbook").executes(ctx -> {
    Minecraft mc = Minecraft.getInstance();
    mc.tell(() -> mc.setScreen(new SpellbookScreen()));
    return 1;
}));
// registered from RegisterClientCommandsEvent (NeoForge / Forge)

From a key binding (client tick):

while (MyKeys.OPEN_SPELLBOOK.consumeClick()) {
    Minecraft.getInstance().setScreen(new SpellbookScreen());
}

As a sub-screen that returns to its opener:

public SpellDetailScreen(Screen parent, SpellEntry spell) {
    super(Component.literal(spell.name()), parent);   // Close/Esc -> back to parent
}

14.9 Movable HUDs - AbyssHud (since 0.1.1)

A HUD players can move, resize, hide and configure in game, with no editor code in your mod. AbyssCore draws your elements where they belong and runs the layout editor; your mod keeps what is drawn (look, labels, values) and where it is saved (your own config file). AbyssOrigins (/abyssoriginshud) and AbyssMagic (/abyssmagic layout) both use it.

The editor: the game under a light fog with every element on it. Drag to move (snaps to the screen edges/centre and to the other elements; Shift = free), scroll or pull the corner handle to resize, right-click or the eye to hide (hidden elements stay faded so they can come back), arrows nudge (Shift: 5 px), Tab = next element, R = reset the selected one. Every element has a gear button that opens its own settings popup: Visible + Reset, Size, then the options that element lists - never another element's. Done / Esc save, Cancel throws everything away, Reset All restores the defaults.

AbyssHud (abstract, one per mod)           AbyssHudElement (interface, one per movable part)
├── title(), elements()                    ├── id(), displayName()
├── placement(e) / setPlacement(e, p)      ├── bounds(preview)        area at scale 1 around (0, 0)
├── save() / revert()                      ├── render(g, partialTick, preview)   drawn at (0, 0), already scaled
├── positioning()  ALIGNED | ORIGIN        ├── defaultPlacement()     HudPlacement.at(...) or auto()
├── min/maxScale(), scaleStep()            ├── isAvailable()          false = skipped everywhere
├── accentColor(), renderEditorBackdrop()  ├── autoBox(hud, w, h, preview)   the spot while AUTO
├── render(g, partialTick)   ← your layer  ├── settings()             List<HudSetting> for the gear popup
├── openEditor()             ← key/button  └── resetSettings()
└── editorCommand("name")    ← client command: /name, /name reset

1. The elements - an enum works well:

public enum ManaHudElement implements AbyssHudElement {
    MANA_BAR;

    @Override public String id() { return "mana_bar"; }
    @Override public Component displayName() { return Component.translatable("hud.mymod.mana_bar"); }
    @Override public HudBounds bounds(boolean preview) { return HudBounds.ofSize(82, 9); }

    @Override public void render(GuiGraphics g, float partialTick, boolean preview) {
        float mana = preview ? 0.75f : ClientMana.fraction();       // sample value in the editor
        g.fill(0, 0, 82, 9, 0xC0000000);
        g.fill(1, 1, 1 + (int) (80 * mana), 8, MyConfig.color.argb());
        if (MyConfig.showNumber) g.drawString(Minecraft.getInstance().font, ClientMana.text(), 86, 1, 0xFFFFFFFF);
    }

    @Override public HudPlacement defaultPlacement() { return HudPlacement.at(HudAnchor.BOTTOM_CENTER, -91, -50); }

    // Shown in THIS element's gear popup only
    @Override public List<HudSetting> settings() {
        return List.of(
            HudSetting.toggle(Component.translatable("hud.mymod.show_number"),
                () -> MyConfig.showNumber, v -> MyConfig.showNumber = v),
            HudSetting.cycle(List.of(BarColor.values()), () -> MyConfig.color, v -> MyConfig.color = v,
                v -> Component.translatable("hud.mymod.color", v.displayName())));
    }

    @Override public void resetSettings() { MyConfig.showNumber = true; MyConfig.color = BarColor.BLUE; }
}

2. The HUD - connects the elements to your config. The editor changes the live values through setPlacement and the settings' setters; save() writes them (Done / Esc / the reset command), revert() reloads them (Cancel, or the editor closed by anything else):

public final class MyHud extends AbyssHud {
    public static final MyHud INSTANCE = new MyHud();

    @Override public Component title() { return Component.translatable("hud.mymod.layout"); }
    @Override public List<ManaHudElement> elements() { return List.of(ManaHudElement.values()); }

    @Override public HudPlacement placement(AbyssHudElement e) { return MyConfig.placements.get(e.id()); }
    @Override public void setPlacement(AbyssHudElement e, HudPlacement p) { MyConfig.placements.put(e.id(), p); }
    @Override public void save()   { MyConfig.write(); }
    @Override public void revert() { MyConfig.reload(); }
}

Storing a HudPlacement = five values: anchor (a HudAnchor name, or none for AUTO), offsetX, offsetY, scale, visible. Keep them in your NeoForge ModConfigSpec / Forge ForgeConfigSpec / JSON - AbyssCore never touches files (it can't use loader config classes from common code, and your players' saved layouts stay where they are). If your config already has its own anchor enum, map it: HudAnchor is row-major (top row first), so a same-order enum maps by ordinal(), or by name() if the names match.

3. Hook it up (client only):

// Your HUD layer (NeoForge RegisterGuiLayersEvent) or RenderGuiEvent.Post (Forge):
event.registerAbove(VanillaGuiLayers.HOTBAR, MyMod.id("hud"),
        (g, delta) -> MyHud.INSTANCE.render(g, delta.getGameTimeDeltaPartialTick(true)));

// A client command (RegisterClientCommandsEvent): /myhud opens the editor, /myhud reset restores the defaults
event.getDispatcher().register(MyHud.INSTANCE.editorCommand("myhud"));
// ...or under your own command:  Commands.literal("mymod").then(MyHud.INSTANCE.editorCommand("layout"))

// A key or a button:
MyHud.INSTANCE.openEditor();

render draws nothing while the editor is open (the editor draws the previews itself) or with F1, so you don't need to check mc.screen yourself.

Placement rules - HudPositioning. Pick the one your saved numbers mean (it can't change later without converting players' configs):

The offset moves… Kept on screen Good for
ALIGNED (default) the element's box, lined up with the anchor: TOP_RIGHT + (0, 0) = touching the top-right corner the whole box panels and bars drawn from their top-left (HudBounds.ofSize(w, h))
ORIGIN the element's drawing origin (0, 0 of its bounds) from the anchor point the origin things drawn around a centre (new HudBounds(-13, -13, 13, 13))

AUTO spot. HudPlacement.auto() (no anchor) means "wherever autoBox says", which may depend on other elements (hud.box(otherElement, preview)), e.g. a bar docked under a panel until the player moves it. Moving an AUTO element in the editor pins it to an anchor.

Settings - HudSetting (all change your live values; the editor's Done / Cancel keep or discard them):

Factory Shows
toggle(label, get, set) a checkbox
cycle(values, get, set, v -> label) a button label(current); left-click next, right-click previous
choice(title?, values, get, set, v -> name) one row per value, the current one framed
choice(..., (g, v, x, y, w, h) -> preview, w, h) the same with a drawn preview per row (e.g. each bar style)
slider(label, min, max, step, get, set, v -> text) a slider

settings() is asked again every frame while the popup is open, so the list may depend on state (AbyssOrigins lists the bar styles of the player's current origin). If a setting changes the element's size, return the new size from bounds - the editor keeps the element on screen.

Optional overrides on AbyssHud: positioning(), minScale() / maxScale() (default 0.5-2), scaleStep() (0.05), accentColor(), renderEditorBackdrop(g, w, h) (your own fog), editorUnavailableReason() (non-null = the editor refuses to open and shows it, e.g. "you need an origin first"), shouldRender() (extra conditions for the whole HUD), onEditorOpened() / onEditorClosed(), resetAll() / resetElement(e) and resetMessage() (the reset command's feedback).

Lang keys used by the editor (in AbyssCore): gui.abysscore.hud.* (hints, Reset All, Reset This, Visible, Size, hidden, reset message) plus vanilla gui.done / gui.cancel. Your mod only provides the title, element names and setting labels.

Clone this wiki locally