|
| 1 | +TODO: finalize dependency declaration to only use the API package, variant declaration? |
| 2 | + |
| 3 | +# Usage of the Sodium Config API |
| 4 | + |
| 5 | +The Sodium Config API lets mods add their own pages to the Video Settings screen, which Sodium replaces with its own screen. |
| 6 | + |
| 7 | +## Scope |
| 8 | + |
| 9 | +The Sodium Config API is intended for mods that add video settings, not as a general purpose config API. For general purpose configuration, use the platform's appropriate mod list and a config library. |
| 10 | + |
| 11 | +As a presentation API, it does not handle loading, parsing, or saving configuration data to files. It is up to your mod to handle that on its own. |
| 12 | + |
| 13 | +## Overview |
| 14 | + |
| 15 | +Sodium redirects Minecraft's "Video Settings" screen to its own screen. Historically, third-party mods have mixed into Sodium to add buttons to their own settings pages or additional options to Sodium's pages. |
| 16 | + |
| 17 | +With this API, these mods will not need to touch Sodium's internals anymore and should be able to operate independently of the GUI's implementation details. The API may not be able to cover all use cases where mods mixed into Sodium's options code, but it should cover most of the common ones. |
| 18 | + |
| 19 | +Registration of options happens in two stages: Early and late. Early registration happens when Sodium initializes its own early options before the window is created. Late registration happens after the game launched. Most mods will only need to use late registration. These stages are independent and only options that are registered in the late stage will show up in the GUI. |
| 20 | + |
| 21 | +## Getting Started |
| 22 | + |
| 23 | +### Dependency on Sodium's API |
| 24 | + |
| 25 | +Sodium publishes its api package on a maven repository that you can depend on in your buildscript. |
| 26 | + |
| 27 | +Fabric: |
| 28 | + |
| 29 | +```groovy |
| 30 | +dependencies { |
| 31 | + // ... other dependencies |
| 32 | + |
| 33 | + modImplementation "net.caffeinemc.mods:sodium-fabric:0.6.0+mc1.21.3" |
| 34 | +} |
| 35 | +``` |
| 36 | + |
| 37 | +NeoForge: |
| 38 | + |
| 39 | +```groovy |
| 40 | +dependencies { |
| 41 | + // ... other dependencies |
| 42 | + |
| 43 | + implementation "net.caffeinemc.mods:sodium-neoforge:0.6.0+mc1.21.3" |
| 44 | +} |
| 45 | +``` |
| 46 | + |
| 47 | +### Creating an Entrypoint |
| 48 | + |
| 49 | +Entrypoint classes that Sodium calls to run your options registration code can be declared either in your mod's metadata file, or on NeoForge with a special annotation. |
| 50 | + |
| 51 | +#### With a Metadata Entry |
| 52 | + |
| 53 | +Metadata-based entrypoints use the key `sodium:config_api_user` and the value is the full reference to a class that implements the `net.caffeinemc.mods.sodium.api.config.ConfigEntryPoint` interface. |
| 54 | + |
| 55 | +Fabric `fabric.mod.json`: |
| 56 | + |
| 57 | +```json5 |
| 58 | +{ |
| 59 | + "entrypoints": { |
| 60 | + // ... other entrypoints |
| 61 | + |
| 62 | + "sodium:config_api_user": [ |
| 63 | + "com.example.examplemod.ExampleModConfigBuilder" |
| 64 | + ] |
| 65 | + } |
| 66 | +} |
| 67 | +``` |
| 68 | + |
| 69 | +NeoForge `neoforge.mods.toml`: |
| 70 | +```toml |
| 71 | +[modproperties.examplemod] |
| 72 | +"sodium:config_api_user" = "com.example.examplemod.ExampleModConfigBuilder" |
| 73 | +``` |
| 74 | + |
| 75 | +The implementation of the entrypoint can look something like this: |
| 76 | + |
| 77 | +```java |
| 78 | +package com.example.examplemod; |
| 79 | + |
| 80 | +import net.caffeinemc.mods.sodium.api.config.ConfigEntryPoint; |
| 81 | +import net.caffeinemc.mods.sodium.api.config.structure.ConfigBuilder; |
| 82 | +import net.minecraft.network.chat.Component; |
| 83 | +import net.minecraft.resources.ResourceLocation; |
| 84 | + |
| 85 | +public class ExampleConfigUser implements ConfigEntryPoint { |
| 86 | + // Store your options in a separate class! |
| 87 | + private final class OptionStorage { |
| 88 | + private boolean exampleOption = true; |
| 89 | + |
| 90 | + public boolean getExampleOption() { |
| 91 | + return this.exampleOption; |
| 92 | + } |
| 93 | + |
| 94 | + public void setExampleOption(boolean value) { |
| 95 | + this.exampleOption = value; |
| 96 | + } |
| 97 | + |
| 98 | + public void flush() { |
| 99 | + // flush options to config file |
| 100 | + } |
| 101 | + } |
| 102 | + |
| 103 | + private final OptionStorage storage = new OptionStorage(); |
| 104 | + private final Runnable handler = this.storage::flush; |
| 105 | + |
| 106 | + @Override |
| 107 | + public void registerConfigLate(ConfigBuilder builder) { |
| 108 | + builder.registerOwnModOptions() |
| 109 | + .addPage(builder.createOptionPage() |
| 110 | + .setName(Component.literal("Example Page")) |
| 111 | + .addOptionGroup(builder.createOptionGroup() |
| 112 | + .setName(Component.literal("Example Group")) |
| 113 | + .addOption(builder.createBooleanOption(ResourceLocation.parse("examplemod:example_option")) |
| 114 | + .setName(Component.literal("Example Option")) // use translation keys here |
| 115 | + .setTooltip(Component.literal("Example tooltip")) |
| 116 | + .setStorageHandler(this.handler) |
| 117 | + .setBinding(this.storage::setExampleOption, this.storage::getExampleOption) |
| 118 | + .setDefaultValue(true) |
| 119 | + ) |
| 120 | + ) |
| 121 | + ); |
| 122 | + } |
| 123 | +} |
| 124 | +``` |
| 125 | + |
| 126 | +#### NeoForge: With an Annotation |
| 127 | + |
| 128 | +Since NeoForge has the convention of using annotations for entrypoints, this option is provided as an alternative. Any classes annotated with `@ConfigEntryPointForge("examplemod")` will be loaded as config entrypoints too. Note that the annotation must be given the mod id that should be associated as the default mod for which a config is registered with `ConfigBuilder.registerOwnModOptions`. This is necessary as it's otherwise impossible to uniquely determine which mod a class is associated with on NeoForge. |
| 129 | + |
| 130 | +```java |
| 131 | +import net.caffeinemc.mods.sodium.api.config.ConfigEntryPoint; |
| 132 | +import net.caffeinemc.mods.sodium.api.config.ConfigEntryPointForge; |
| 133 | + |
| 134 | +@ConfigEntryPointForge("examplemod") |
| 135 | +public class ExampleConfigUser implements ConfigEntryPoint { |
| 136 | + // class body identical to the above |
| 137 | +} |
| 138 | +``` |
| 139 | + |
| 140 | +### Registering Your Options |
| 141 | + |
| 142 | +Each mod adds a page for its options, within each page there are groups of options, and each group contains a list of options. Each option has an id, a name, a tooltip, a storage handler, a binding, and a default value. There are three types of options: boolean (tickbox), integer (slider), and enum. Optionally, all types of options can be disabled, while integer and enum options can have their allowed values restricted. Those two types also require you to set a function that assigns a label to each selected value. |
| 143 | + |
| 144 | +Some attributes of an option can be provided dynamically, meaning the returned value can depend on the state of another option. The default value, option enablement, and the allowed values can be computed dynamically. The methods for setting a dynamic value provider also require you to specify a list of dependencies, which are the resource locations of the options that the dynamic value provider reads from. Since dynamically evaluated attributes may change the state of an option, cyclic dependencies will lead to option registration failing and the game crashing. |
| 145 | + |
| 146 | +Sodium constructs one instance of the entrypoint class, and then calls the early and late registration methods at the right time. |
| 147 | + |
| 148 | +## API Notes |
| 149 | + |
| 150 | +The API is largely self-explanatory and an example is provided above. Also see Sodium's own options registration for a more in-depth example of the API's usage. |
| 151 | + |
| 152 | +### Using `ConfigBuilder` and `ModOptions` |
| 153 | + |
| 154 | +The `ConfigBuilder` instance passed to the registration method allows quick and easy registration of a mod's own options using `ConfigBuilder.registerOwnModOptions`. The mod's id, name, version or a formatter for the existing version, and the color theme can be configured on the returned `ModOptionsBuilder`. It's also possible to register options for additional mods using `ConfigBuilder.registerModOptions`. Which mod is the "own" mod for `registerOwnModOptions` is determined by the mod that owns the metadata-based entrypoint or the mod id passed to the `@ConfigEntryPointForge("examplemod")` annotation. |
| 155 | + |
| 156 | +Each registered mod gets its own header in the page list. The color of the header and the corresponding entries is randomly selected from a predefined list by default, but can be customized using `ModOptionsBuilder.setColorTheme`. A color theme is created either by specifying three RGB colors or a single base color with the lighter and darker colors getting derived automatically. |
| 157 | + |
| 158 | +To simply switch to a new `Screen` when an entry in the video settings screen's page list is clicked, use `ConfigBuilder.createExternalPage` and add the returned page normally after configuring it with a name and a `Consumer<Screen>` that receives the current screen and switches to your custom screen. |
| 159 | + |
| 160 | +### Using `OptionBuilder` |
| 161 | + |
| 162 | +The storage handler set with `OptionBuilder.setStorageHandler` is called after changes have been made to the options through the bindings. This lets you flush the changes to the config file once, instead of every time an option is changed. |
| 163 | + |
| 164 | +The tooltip set with `OptionBuilder.setTooltip` can optionally be a function that generates a tooltip depending on the option's current value. This is useful for enum options for which the description would be too long otherwise. |
| 165 | + |
| 166 | +Optionally a performance impact can be specified with `OptionBuilder.setImpact` where the impact ranges from low to high (or "varies"). |
| 167 | + |
| 168 | +Flags set with `OptionBuilder.setFlags` control what things are reset when this option is applied. They include reloading chunks or reloading resource packs. See `OptionFlag` for the available values. |
| 169 | + |
| 170 | +The default value set with `OptionBuilder.setDefaultValue`, or dynamically with `OptionBuilder.setDefaultProvider`, is used if the value returned by the binding does not fulfill the option's value constraint (in the case of a integer or enum option). |
| 171 | + |
| 172 | +Disabling an option with `OptionBuilder.setEnabled(false)` shows the option as strikethrough and makes it non-interactive. Otherwise, especially with regard to value constraints, it will behave as usual. |
| 173 | + |
| 174 | +The binding configured with `OptionBuilder.setBinding` is called when changes to the options have been made and are applied, or when the value no longer fulfills the option's constraints and is reset to the default value. It's also used to initially load a value during initialization. |
| 175 | + |
| 176 | +### Using `? extends OptionBuilder` |
| 177 | + |
| 178 | +Some of the attributes of an option are required and you must set them, or registration will fail. The concrete extensions of `OptionBuilder` for each of the option types have some additional methods for configuring type-specific things, some of which are also required. Notably, `EnumOptionBuilder.setElementNameProvider` and `IntegerOptionBuilder.setValueFormatter` are required in order to display these types of options. The method `setValueFormatter` for integer options takes a `ControlValueFormatter`, which simply formats a number as a `Component`. Many standard value formatters are provided in `ControlValueFormatterImpls` (not part of the API package). |
| 179 | + |
| 180 | +Integer and enum options can have value constraints that restrict the set of allowed values the user can select. For integer options, a `Range` must be configured with `IntegerOptionBuilder.setRange` so that the slider's start, end, and step positions are well-defined. Enum options may be configured to only allow the selection of certain elements with `EnumOptionBuilder.setAllowedValues`. |
0 commit comments