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 cityrptype

    Type of this option

  • default any

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

Example Usage

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

cityrp.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 any optional

    Default value to return if the option is not set

Returns

  • any Value associated with the key or 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 any optional

    Default value to return if the option is not set

Returns

  • any Value associated with the key or 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

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 boolean optional

    Remove entries that are marked as hidden

Returns

Example Usage

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

cityrp.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 options from data storage and initializes fonts.

cityrp.option.LoadChatFonts(font)
Internal

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

View source »

Loads chat fonts based on the selected option.

Parameters

  • font string

    The font name to use for chat.

cityrp.option.LoadFonts(font, genericFont)
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.

Parameters

  • font string

    The primary font name.

  • genericFont string

    The fallback/generic font name.

cityrp.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.

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 any

    New value to assign to the option

  • bNoSave boolean optional

    Whether or not to avoid saving

cityrp.option.Sync()
Internal

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

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

    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

    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

    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

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

  • max number

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

  • decimals number

    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

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

  • any fun(oldValue:

    , value: any) OnChanged? 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.

  • hidden fun():boolean optional

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

  • string fun():table

    populate? 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