Native Game Settings

Native Game Settings

PleasureLib exposes the game's four native value types on the dedicated Settings -> Mods page:

• runtime:register_game_bool_setting(options)
• runtime:register_game_int_setting(options)
• runtime:register_game_float_setting(options)
• runtime:register_game_enum_setting(options)

Each registration creates its own native settings row and matching widget. Mouse, keyboard, controller focus, scrolling, and the details panel therefore behave like the vanilla settings pages. Registrations are grouped by section, which defaults to the runtime mod name, so multiple mods normally receive separate sections on the same page.

Minimal setting

local show_extra_info = false

local handle = pleasureLib:register_game_bool_setting({
    id = "MyMod.ShowExtraInfo",
    get = function()
        return show_extra_info
    end,
    set = function(value)
        show_extra_info = value
        return true
    end,
})

Common contract

All four registration methods require the same three options:

Option	Description
id	Globally unique, stable identifier. Prefix it with the mod name.
get()	Returns the mod's current value using the registered type.
set(value)	Applies the normalized value. Only a literal false return rejects the change.

Invalid registrations return nil and write a readable log message. Errors inside get() fall back to the configured default. Errors inside set(value) reject the change and restore the visible widget value.

These options are shared by all four types:

Option	Description
default	Fallback value. Its type-specific default is listed below.
section	Heading used to group the settings. Defaults to the runtime mod name.
translations	Localized display names and descriptions keyed by language code.
persist	Optional INI persistence table described below.

Type-specific options

Bool

register_game_bool_setting uses the native ON/OFF toggle.

Option	Default	Description
default	false	Boolean fallback value; only a literal true enables it.

get() must return a boolean, and set(value) receives a boolean.

Int

register_game_int_setting uses the native integer slider.

Option	Default	Description
minimum	0	Smallest permitted integer.
maximum	100	Largest permitted integer; must be greater than minimum.
default	minimum	Fallback value, floored and clamped to the range.

Finite numeric values returned by get() are floored and clamped for display and comparison. Values coming from the native UI are floored and clamped before they reach set(value).

local item_limit = 20

pleasureLib:register_game_int_setting({
    id = "MyMod.ItemLimit",
    minimum = 5,
    maximum = 50,
    default = 20,
    get = function() return item_limit end,
    set = function(value)
        item_limit = value
        return true
    end,
})

Float

register_game_float_setting uses the native floating-point slider.

Option	Default	Description
minimum	0	Smallest permitted number.
maximum	1	Largest permitted number; must be greater than minimum.
step	(maximum - minimum) / 100	Slider step size; must be positive.
default	minimum	Fallback value, clamped to the range.
always_show_sign	false	Shows an explicit sign on the native value label.

Finite numeric values returned by get() are clamped for display and comparison. Values coming from the native UI are clamped before they reach set(value). step configures the native widget but does not additionally quantize values returned by the mod.

local tooltip_delay = 0.3

pleasureLib:register_game_float_setting({
    id = "MyMod.TooltipDelay",
    minimum = 0,
    maximum = 2,
    step = 0.1,
    default = 0.3,
    get = function() return tooltip_delay end,
    set = function(value)
        tooltip_delay = value
        return true
    end,
})

Enum

register_game_enum_setting uses either the native spinner or dropdown. get(), set(value), and default use a zero-based numeric index into values. Lua list entry 1 therefore represents setting value 0.

Option	Default	Description
values	required	Non-empty list of value labels.
default	0	Fallback index, floored and clamped to the list.
widget	"spinner"	Either "spinner" or "dropdown".
wrap_around	false	Lets a spinner wrap between its first and last value.
value_translations	none	Localized value-label lists keyed by language code.

local detail_level = 1

pleasureLib:register_game_enum_setting({
    id = "MyMod.DetailLevel",
    values = { "Low", "Medium", "High" },
    default = 1,
    widget = "dropdown",
    get = function() return detail_level end,
    set = function(value)
        detail_level = value
        return true
    end,
    value_translations = {
        en = { "Low", "Medium", "High" },
        de = { "Niedrig", "Mittel", "Hoch" },
    },
})

Enum values may also be tables with a name, label, or value fallback and their own translations or labels table.

Persistence

All four types support optional INI persistence:

persist = {
    path = function() return config_path end,
    key = "ShowExtraInfo",
    serialize = function(value)
        return value
    end,
}

Option	Description
persist.path	INI path or callback returning the path.
persist.key	INI key or callback returning the key.
persist.serialize(value)	Optional callback returning the value to write.

Persistence runs after set(value) accepts a change. Without a serializer, booleans are written as true or false, while numeric values use their Lua string representation. If persist, its path, or its key is unavailable, the setting still works without writing an INI value.

The target INI file must already exist and be readable and writable. PleasureLib replaces the first matching key case-insensitively or appends it; this helper does not distinguish INI sections.

Native changes are auto-applied. PleasureLib also confirms the current mod value when the settings page applies or discards pending values, so Discard does not roll these API settings back.

Translations

translations = {
    en = {
        name = "Show extra information",
        description = "Shows more information in the inventory.",
    },
    de = {
        name = "Zusatzliche Informationen anzeigen",
        description = "Zeigt mehr Informationen im Inventar an.",
    },
}

Translation lookup tries the complete current language code, then its base language, then en, and finally en-us. You can supply Gothic 1 Remake language codes such as de, fr, it, es, pl, ru, zh-hans, ja, and pt-br.

Return value and refresh

Every successful registration returns a handle containing:

• id: the registered setting identifier
• refresh(): synchronizes existing native widgets, labels, and type configuration with the current value from get() without calling set(value) or persistence

Call refresh() when the mod changes the setting outside the settings menu:

show_extra_info = false
if handle then handle.refresh() end

Registration timing and duplicates

Registration is safe before the game's settings assets are loaded. PleasureLib activates the game's unused native test page as a dedicated Mods category and populates it when the settings menu becomes available. Settings are grouped by their configured section, and the page is managed independently from the vanilla categories.

Use one stable, globally unique id per logical setting. Registering the same id again replaces the entry used by PleasureLib instead of creating a second row. A compatible row is reused; changing the value type or switching an Enum between spinner and dropdown rebuilds that row.

Current scope

The public settings API supports native Bool, Int, Float, and Enum rows. Keybinding and custom widget settings are not part of the public API.