settings - Windower/packages GitHub Wiki

This library allows addons to persist and load configuration options.

local settings = require('settings')

❗ Dependency Required

To use this library, you must include settings in the manifest.xml file for your package:

<dependency>settings</dependency>

The settings table has the following entries:

• settings.load : Loads a set of configuration options from a file.
• settings.save : Saves a set of configuration options to a file.
• settings.get : Gets a specific setting for the provided path.
• settings.set : Sets a specific setting for the provided path to the provided value.
• settings.settings_change : Event that triggers when the configuration options are reparsed.

Loads a table of configuration options from a file.

function settings.load(defaults : table, name : string = 'settings', global: boolean = false) : table

defaults table

A table that contains the default configuration options.

name string [default: 'settings']

A name to associate the options with. Only necessary if an addon uses multiple distinct option tables.

global boolean [default: false]

Indicates whether or not a settings object should apply globally, which prevents character-specific settings files.

options table

A table that contains the loaded configuration options. The table returned is a combination of options loaded from the file, where available, and the defaults table, where not.

Saves a table of configuration settings to a file.

function settings.save(options : table)

options table

The table that contains the configuration options to save.

This function does not return any values.

Gets a specific setting for the provided path.

function settings.get(path : string, name : string = 'settings') : any

path string

The path which identifies a specific setting.

name string [default: 'settings']

A name to identify the options table.

value any

The setting at the specified path.

local options = settings.load({
    window = {
        position = {
            x = 123,
            y = 456,
        },
    }
}

print(settings.get('window.position.y')) -- prints 456

Gets a specific setting for the provided path to the provided value.

function settings.set(path : string, value : any, name : string = 'settings')

path string

The path which identifies a specific setting.

value any

The value to assign to the setting.

name string [default: 'settings']

A name to identify the options table.

This function does not return any values.

An event that triggers when the configuration options are reparsed, currently on account login and account logout.

settings.settings_change : event

This event does not receive any parameters.