Skip to content

ToadConfig

ITsMrToad edited this page Jan 8, 2025 · 6 revisions

ToadConfig, an easy way to create configs that are GUI-enabled. By default, config files are saved as .txt, but you can change this.

ConfigEntries

Constructor must-have:

  • Unique name(String), to save/load.
  • Default value.

Have common settings such as:

  • Name(Component), defaults to empty.
  • Description(Component), defaults to empty.
  • Screen rendering, defaults to true.

Numeric:
ByteEntry, ShortEntry, IntEntry, LongEntry and BigDecimal is numeric. In GUI it is rendered as a slider.

Important

Each numeric has min, max, and step.

If these values are not set manually, entry will take the default values.

The step itself is float, but for non-fractional values, it will be rounded downward. The fatal field, determines whether an exception will be raised when the min/max is exceeded or if the bounds are reset to default.

Warning

If min or max do not match the scope of the primitive (for a byte, for example, it is -128 and 127), it will raise an exception. Also, if the min is greater than max or they are equal, this will also lead to exception.

There is also DegreeValue. It has no additional settings and is limited to -180 - 180 and step is 0.1. DegreeValue can be converted to radians by special method.

Boolean:
BoolEntry - simple value without special settings. In GUI it is rendered as a checkbox

String:
Text. It has a lot of settings, which are mostly needed for EditBox. As you have already understood, it is rendered in GUI entry as EditBox.

EnumEntry:
EnumEntry is a special value for enum. It is necessary to specify codec. Also has naming, this is the relation of enum constant to its name (Component). In GUI it is rendered as a cycle-button.

Warning

If the enum length is empty or equal 1, it will throw an exception. If enum, will not inherit StringRepresentable, it will also throw an exception.

The enum should be created via CommonEntries#createEnum.

ColorEntry:
Color as a simple int. There are two constructors - Palette and Cells (define widget on the screen).

Caution

Cells constructor now unavailable because it's rendering incorrectly.

Palette Demonstration:
image

Warning

Any values specified for entry (even standard values) must be color-coded (can be HEX).

Custom config entries

You can create your own ConfigEntry. This requires a new type with a unique name.

public static final ConfigEntryType FROG_TYPE = new ConfigEntryType("frog_type");

Then use it in your ConfigEntry class. If you want to add a widget in the GUI to your ConfigEntry.

//Invoke in you clientSetup
ConfigEntryWidgetsRegistry.registerMaker(FROG_TYPE /*<-- config entry type*/, FrogType.class /*<-- class of value*/, (owner, nextX, nextY, entry) -> {
       try {
            if (entry instanceof NumericEntry numericEntry) {
               //Create widget
               //Owner - ToadConfigScreen, nextX - nextXPos, nextY - 0(WIP), entry - ConfigEntry<?, ?>
            } else {
                throw new ConfigException(); //Throw for null
            }
    } catch (ConfigException) {
          return new UnexpectedEntry(nextX, nextY); //Null-safe
    }
});

Config Creation

  1. Create a class that extends ToadConfig
  2. Override the title method
  3. In the constructor, set the name of the config.
  4. Use register to add entries in method

Example:

public final IntEntry test_int = this.register(new IntEntry("integer", 0).range(-100, 100).addTitle(Component.literal("Integer")));

public ToadLibConfig() {
    super(() -> "coolmod_config");
}

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

Tip

If you don't want the config to create a screen, then override the shouldCreateScreen method and return false.

Interactions with config

  1. Create instance of your config
public static final CoolModConfig CFG = new CoolModConfig();

2.For it to load you must additionally have the ToadConfigs#create method in your mod's clientSetup, otherwise your config will not be visible on the config select screen.

private void clientSetup(FMLClientSetupEvent event) {
    event.enqueueWork(() -> {
        ToadConfigs.create(MODID, CFG);
    });
}

Now you can get values of entries, but not everywhere(For example in config mixins may not be there because they are loaded too early).

Misc

  • Config values are loaded at startup and when resources are reloaded.
  • You can also set config values with setValue anywhere.
  • You can register a ticker for your ConfigWidget:
registerTicker(ConfigEntryTypes.STRING, w -> { //Invoke in you clientSetup
     if (w instanceof EditBox editBox) {
           editBox.tick(); //Example with edit box
     }
});
  • In the future there will also be built-in entries for keybinds, interpolations, and others.
  • Appearance of the config test screen:

Снимок экрана 2025-01-07 195158

Clone this wiki locally