Skip to content

GUI Toolkit

Gugas749 edited this page Nov 5, 2026 · 1 revision

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)

11.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)
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.

11.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
    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);
}

11.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.

11.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.

11.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.

11.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.
// 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.

11.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)

11.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
}

Clone this wiki locally