Usage - isXander/Settxi GitHub Wiki

All together now! This is how you use Settxi!

Gradle

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)")
}

Basic use-case

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!

Import and export settings

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.
        }
    }
}

Serialization helpers

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

kotlinx.serialization

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

Gson

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

GUI Implementations

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
}
⚠️ **GitHub.com Fallback** ⚠️