SSGL Wiki

Notes and Best Practices

Prefer Components for user-visible text

Use Component.translatable() for text that should be localized.

This applies to GUI titles, labels, button text, tooltips, and image-button narration.

Use GuiValue for shared state

When a setting is used by multiple widgets or by other parts of your mod, store it in a GuiValue.

This keeps components synchronized with the same underlying state.

Use layouts instead of manual positioning

Prefer GuiLayout.vertical() and GuiLayout.horizontal() over hardcoded coordinates.

Layouts are easier to maintain and adapt better to changes in screen size.

Use scroll areas for larger interfaces

Avoid placing too many controls directly on the root screen.

A scroll area keeps the interface compact and helps prevent clipping at larger GUI scales.

Handle dynamic textures yourself

SSGL displays already registered dynamic textures, but the owning mod is responsible for their creation, updates, and cleanup.

Avoid updating texture data from the rendering callback. Prepare and upload image data through the appropriate Minecraft client-side texture APIs.

Keep GUI operations on the client thread

Do not create or manipulate Minecraft GUI widgets from background threads.

When necessary, schedule operations using:

Minecraft.getInstance().execute(() -> {
    value.set(newValue);
});

Keep the interface simple

SSGL is intended to make common GUI development straightforward.

Use its built-in widgets and layouts where possible. Keep specialized behavior inside your own mod rather than extending the library with unnecessary custom components.