Repository navigation
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)
┌─ 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.
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 ininit().
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);
}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.
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. UseDANGERfor destructive actions and pair it withAbyssDialog.confirmDanger. - Labels that are too long scroll instead of overflowing.
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)// 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.0AbyssTextField 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 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, RIGHTIt's 9 tall and not clickable.
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 andUUIDs work best.
// 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.
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.
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 widgetRight-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.
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.
| 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.
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) |
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
}- Setup: depending on AbyssCore
- Sides, threads and lifecycle: read this first
- Permissions
- Networking
- Synced player data
- Corruption
- Damage
- Continuous effects
- Screen overlays
- Commands
- GUI toolkit
- GeckoLib
- Outside the API package: vanish and config queries
- Complete example: a mana mod
- Limitations, troubleshooting and changelog
- Quick reference