cityrp.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 cityrp.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:
cityrp.option.Add("headbob", cityrp.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
cityrp.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:
cityrp.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 cityrp.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
cityrp.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
cityrp.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
cityrp.option.Add("animationScale", cityrp.type.number, 1, {
category = "appearance",
min = 0.3,
max = 2,
decimals = 1
})
cityrp.option.Get(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
-
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
cityrp.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
cityrp.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(cityrp.option.GetAll())
> language:
> bNetworked = true
> default = english
> type = 512
-- etc.
cityrp.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
bool
default: false
Remove entries that are marked as hidden
Returns
-
table
Table of all options
Example Usage
PrintTable(cityrp.option.GetAllByCategories())
> general:
> 1:
> key = language
> bNetworked = true
> default = english
> type = 512
-- etc.
cityrp.option.LoadFonts(font, genericFont)
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.
Parameters
-
font
-
genericFont
cityrp.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.
cityrp.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
bool
default: false
Whether or not to avoid saving
cityrp.option.Sync()
View source »Syncs all networked options to the server.
Tables
OptionStructure
View source »You can specify additional optional arguments for cityrp.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
cityrp.type.number
.
-
max
number
default: 10
The maximum allowed amount when setting this option. This field is not applicable to any type other than
cityrp.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
cityrp.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 cityrp.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 cityrp.option.Set, and the value is the display name for the entry. An example:
populate = function() return { ["english"] = "English", ["french"] = "French", ["spanish"] = "Spanish" } end