Usage - isXander/Settxi GitHub Wiki
All together now! This is how you use Settxi!
If you want to actually use Settxi, you probably want to use a buildsystem.
First, you need to add the maven repository
repositories {
maven("https://maven.isxander.dev/releases")
}
And then use the dependency
dependencies {
implementation("dev.isxander.settxi:settxi-core:(latest)")
}
This demonstrates how to make a super simple settings class, no serialization, no nothing.
First, make an Object or a Class that implements ConfigProcessor
import dev.isxander.settxi.ConfigProcessor
object MySettingsObject : ConfigProcessor {
}
Next, you need to initialise your settings list. You can use any type, as long as its mutable.
import dev.isxander.settxi.ConfigProcessor
import dev.isxander.settxi.Setting
object MySettingsObject : ConfigProcessor {
override val settings = mutableListOf<Setting<*>>()
}
You are all done with boilerplate! You can now start adding settings to your class! Check out more about settings on the Settings page.
import dev.isxander.settxi.ConfigProcessor
import dev.isxander.settxi.Setting
import dev.isxander.settxi.impl.*
object MySettingsObject : ConfigProcessor {
override val settings = mutableListOf<Setting<*>>()
var myBoolean by boolean(true) {
name = "Boolean Setting"
category = "Examples"
description = "An example that demonstrates how to add a boolean setting"
}
}
By invoking boolean()
the setting is automagically added to the settings
list you defined. How cool!
For a slightly more practical use-case, you may want to save and load (import/export) the settings if a user modifies them.
For this example, we are going to modify our basic example a little bit. Instead of implementing ConfigProcessor
, we are going to extend SettxiConfig
instead. We also don't need to define settings
either as it is already implemented as a MutableList
you can always override this though.
This class has two abstract functions, import()
and export()
that we have to implement.
import dev.isxander.settxi.impl.*
import dev.isxander.settxi.serialization.SettxiConfig
object MySettingsObject : SettxiConfig() {
var myBoolean by boolean(true) {
name = "Boolean Setting"
category = "Examples"
description = "An example that demonstrates how to add a boolean setting"
}
// always remember to import AFTER defining all your settings
init {
import()
}
override fun import() {
for (setting in this.settings) {
// however you want to load the setting values, do it here, and convert them into
// a PrimitiveType (check javadoc) which can then be set here
setting.setSerialized(PrimitiveType.of(true))
}
}
override fun export() {
for (setting in this.settings) {
val primitiveType = setting.serializedValue // you can convert PrimitiveType into whatever you need to export.
}
}
}
Settxi has a couple modules that can help you import/export without the effort of doing it yourself. There are multiple libraries you can choose from, if you want to see another one added to settxi, make an issue
First, you need to depend on the module
dependencies {
implementation("dev.isxander.settxi:settxi-core:(latest)")
implementation("dev.isxander.settxi:settxi-kotlinx-serialization:(latest)")
}
Now, instead of the manual way you can use it by passing a java.nio.file.Path
import dev.isxander.settxi.impl.*
import dev.isxander.settxi.serialization.SettxiConfigKotlinx
object MySettingsObject : SettxiConfigKotlinx(Path.of("./settxi.json")) {
var myBoolean by boolean(true) {
name = "Boolean Setting"
category = "Examples"
description = "An example that demonstrates how to add a boolean setting"
}
// always remember to import AFTER defining all your settings
init {
import()
}
}
Voila! Settxi is now automatically saving and loading from a file using JSON!
If you don't want to use the provided implementation, you can always just use the serialization helper utils provided with the extension function kotlinx
.
settings.kotlinx.asJson()
// or
settings.kotlinx.importFromJson(jsonObject)
settings
refers to the list provided by ConfigProcessor
First, you need to depend on the module
dependencies {
implementation("dev.isxander.settxi:settxi-core:(latest)")
implementation("dev.isxander.settxi:settxi-gson:(latest)")
}
Now, instead of the manual way you can use it by passing a java.nio.file.Path
import dev.isxander.settxi.impl.*
import dev.isxander.settxi.serialization.SettxiConfigGson
object MySettingsObject : SettxiConfigGson(Path.of("./settxi.json")) {
var myBoolean by boolean(true) {
name = "Boolean Setting"
category = "Examples"
description = "An example that demonstrates how to add a boolean setting"
}
// always remember to import AFTER defining all your settings
init {
import()
}
}
Voila! Settxi is now automatically saving and loading from a file using JSON!
If you don't want to use the provided implementation, you can always just use the serialization helper utils provided with the extension function gson
.
settings.gson.asJson()
// or
settings.gson.importFromJson(jsonObject)
settings
refers to the list provided by ConfigProcessor
Settxi also gives easy utilities for displaying settings on a gui.
Cloth Config (Minecraft)
This module is currently only available for Fabric Loader and Quilt Loader for 1.19
This module requires you use SettxiConfig
from #import-and-export-settings or #serialization-helpers
First, you need to depend on the module
dependencies {
implementation("dev.isxander.settxi:settxi-core:(latest)")
implementation("dev.isxander.settxi:settxi-gui-cloth-config:(latest)")
}
Then all you need to do is call the extension function SettxiConfig.clothGui()
with a title Text
and optionally a parent Screen
MySettings.clothGui(title = Text.literal("GUI Title"), parent = null) // returns Screen
You can also register custom Setting
class factories too.
SettxiClothConfigGui.registerType<MyCustomSetting> { setting ->
// build cloth config entry
}