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
-
data
OptionStructure
Additional settings for this option
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
-
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
-
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()
This is an internal function! You are able to use it, but you risk unintended side effects if used incorrectly.
Loads all saved options from disk.
ix.option.Save()
This is an internal function! You are able to use it, but you risk unintended side effects if used incorrectly.
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