SSGL Wiki

GuiValue

GuiValue<T> is a simple value holder used to connect GUI components to your mod's settings or internal state. It allows components to read and update values without requiring you to manually synchronize every widget.

Creating a value

Use GuiValue.of():

GuiValue<Boolean> enabled = GuiValue.of(true);

GuiValue<Integer> amount = GuiValue.of(10);

GuiValue<Double> volume = GuiValue.of(0.5);

GuiValue<String> username = GuiValue.of("Steve");

The initial value determines the generic type.

Values cannot be initialized or updated with null.

Reading values

Use get():

boolean isEnabled = enabled.get();

int currentAmount = amount.get();

double currentVolume = volume.get();

String currentUsername = username.get();

Changing values

Use set():

enabled.set(false);

amount.set(25);

volume.set(0.75);

username.set("Alex");

set() returns the same GuiValue, so calls can be chained:

volume.set(0.8);

A change notification is only generated when the new value differs from the previous value.

Binding values to components

Bind the same GuiValue to a component:

GuiValue<Boolean> enabled = GuiValue.of(true);

gui.add(
    GuiElement.toggle("Enabled", enabled)
);

The component automatically updates the value when interacted with.

You can also update it from elsewhere in your mod:

enabled.set(false);

The displayed toggle state will reflect the external change.

The same approach works with sliders and input fields.

Change listeners

Use onChange() to register a permanent listener.

volume.onChange(value -> {
    LOGGER.info("Volume changed to {}", value);
});

The listener receives the new value.

Listeners are called only when the value actually changes.

For example, setting the same value again does not generate a notification.

GuiValue<Boolean> enabled = GuiValue.of(true);

enabled.onChange(value -> {
    LOGGER.info("Enabled: {}", value);
});

enabled.set(true);  // No notification
enabled.set(false); // Notification

Removable listeners

When a listener is only needed temporarily, use subscribe().

GuiValue.Subscription subscription = volume.subscribe(
    value -> LOGGER.info("Volume: {}", value)
);

Remove it later:

subscription.close();

This is useful when dynamically creating and removing GUI screens or other temporary integrations.

The older onChange() method remains available for listeners that should stay registered for the lifetime of the value.

Threading

GuiValue notifications execute on the thread that calls set().

For changes originating from asynchronous work, schedule GUI-related updates on Minecraft's client thread:

Minecraft.getInstance().execute(() -> {
    volume.set(newVolume);
});

This is especially important for camera capture tasks, background screenshot processing, and other asynchronous operations.