ix.option

Client-side configuration management.

The option library provides a cleaner way to manage any arbitrary data on the client without the hassle of managing CVars. It is analagous to the ix.config library, but it only deals with data that needs to be stored on the client.

To get started, you'll need to define an option in a client realm so the framework can be aware of its existence. This can be done in the cl_init.lua file of your schema, or in an if (CLIENT) then statement in the sh_plugin.lua file of your plugin:

ix.option.Add("headbob", ix.type.bool, true)

If you need to get the value of an option on the server, you'll need to specify true for the bNetworked argument in ix.option.Add. NOTE: You also need to define your option in a shared realm, since the server now also needs to be aware of its existence. This makes it so that the client will send that option's value to the server whenever it changes, which then means that the server can now retrieve the value that the client has the option set to. For example, if you need to get what language a client is using, you can simply do the following:

ix.option.Get(player.GetByID(1), "language", "english")

This will return the language of the player, or "english" if one isn't found. Note that "language" is a networked option that is already defined in the framework, so it will always be available. All options will show up in the options menu on the client, unless hidden returns true when using ix.option.Add.

Note that the labels for each option in the menu will use a language phrase to show the name. For example, if your option is named headbob, then you'll need to define a language phrase called optHeadbob that will be used as the option title.

Functions

ix.option.Add(key, optionType, default, data)

 View source »

Creates a client-side configuration option with the given information.

Parameters

  • key string

    Unique ID for this option

  • optionType ix.type

    Type of this option

  • default

    Default value that this option will have - this can be nil if needed

Example Usage

ix.option.Add("animationScale", ix.type.number, 1, {
	category = "appearance",
	min = 0.3,
	max = 2,
	decimals = 1
})

ix.option.Get(client, key, default)

 View source »

Retrieves an option value from the specified player. If it is not set, it'll return the default that you've specified. This function will error when an invalid player is passed.

Parameters

  • client Player

    Player to retrieve option value from

  • key string

    Unique ID of the option

  • default

    Default value to return if the option is not set

Returns

  • any

    Value associated with the key

    • OR
  • any

    The given default if the option is not set

ix.option.Get(key, default)

 View source »

Retrieves an option value for the local player. If it is not set, it'll return the default that you've specified.

Parameters

  • key string

    Unique ID of the option

  • default

    Default value to return if the option is not set

Returns

  • any

    Value associated with the key

    • OR
  • any

    The given default if the option is not set

ix.option.GetAll()

 View source »

Returns all of the available options. Note that this does contain the actual values of the options, just their properties.

Returns

  • table

    Table of all options

Example Usage

PrintTable(ix.option.GetAll())
> language:
>	bNetworked = true
>	default = english
>	type = 512
-- etc.

ix.option.GetAllByCategories(bRemoveHidden)

 View source »

Returns all of the available options grouped by their categories. The returned table contains category tables, that contain all the options in that category as an array (this is so you can sort them if you'd like).

Parameters

  • bRemoveHidden boolean default: false

    Remove entries that are marked as hidden

Returns

  • table

    Table of all options

Example Usage

PrintTable(ix.option.GetAllByCategories())
> general:
>	1:
>		key = language
>		bNetworked = true
>		default = english
>		type = 512
-- etc.

ix.option.Load()
Internal

This is an internal function! You are able to use it, but you risk unintended side effects if used incorrectly.

View source »

Loads all saved options from disk.

ix.option.Save()
Internal

This is an internal function! You are able to use it, but you risk unintended side effects if used incorrectly.

View source »

Saves all options to disk.

ix.option.Set(key, value, bNoSave)

 View source »

Sets an option value for the local player. This function will error when an invalid key is passed.

Parameters

  • key string

    Unique ID of the option

  • value

    New value to assign to the option

  • bNoSave boolean default: false

    Whether or not to avoid saving

ix.option.Sync()

 View source »

Syncs all networked options to the server.

Tables

OptionStructure

 View source »

You can specify additional optional arguments for ix.option.Add by passing in a table of specific fields as the fourth argument.

Fields

  • phrase string default: "opt" .. key

    The phrase to use when displaying in the UI. The default value is your option key in UpperCamelCase, prefixed with "opt". For example, if your key is "exampleOption", the default phrase will be "optExampleOption".

  • description string default: "optd" .. key

    The phrase to use in the tooltip when hovered in the UI. The default value is your option key in UpperCamelCase, prefixed with "optd". For example, if your key is "exampleOption", the default phrase will be "optdExampleOption".

  • category string default: "misc"

    The category that this option should reside in. This is purely for aesthetic reasons when displaying the options in the options menu. When displayed in the UI, it will take the form of L("category name"). This means that you must create a language phrase for the category name - otherwise it will only show as the exact string you've specified. If no category is set, it will default to "misc".

  • min number default: 0

    The minimum allowed amount when setting this option. This field is not applicable to any type other than ix.type.number.

  • max number default: 10

    The maximum allowed amount when setting this option. This field is not applicable to any type other than ix.type.number.

  • decimals number default: 0

    How many decimals to constrain to when using a number type. This field is not applicable to any type other than ix.type.number.

  • bNetworked boolean default: false

    Whether or not the server should be aware of this option for each client.

  • OnChanged function optional

    The function to run when this option is changed - this includes whether it was set by the player, or through code using ix.option.Set.

    OnChanged = function(oldValue, value)
    print("new value is", value)
end

  • hidden function optional

    The function to check whether the option should be hidden from the options menu.

  • populate function optional

    The function to run when the option needs to be added to the menu. This is a required field for any array options. It should return a table of entries where the key is the value to set in ix.option.Set, and the value is the display name for the entry. An example:

    populate = function()
    return {
        ["english"] = "English",
        ["french"] = "French",
        ["spanish"] = "Spanish"
    }
end