config library

Defines the global config library, the framework's saved and networked configuration keys.

The server declares a key and its default with config.Add, and config.Get(key) returns an object with Get, Set, GetNumber, GetDefault and similar methods. Changed values are saved per schema or globally, shared keys are sent to clients over the Config message, and the client lists keys in the config system menu with config.AddToSystem.

Summary

Functions

Add(key, value, isShared, isGlobal, isStatic, isPrivate, needsRestart)shared
Adds a new config key with a default value.
AddToSystem(name, key, help, minimum, maximum, decimals, category)client
Adds a config key to the client's config system menu.
Get(key)shared
Returns the config object for a key.
GetFromSystem(key)client
Returns a config key's entry in the config system menu.
GetStored()shared
Returns the table of every config entry, indexed by key.
GetVal(key, failSafe)shared
Returns the current value of a config key without creating a config object.
HasInitialized()shared
Returns whether the config has been initialized.
HasSentInitialized()client
Returns whether the client has told the server that its config has initialized.
Import(fileName)shared
Imports config keys from a text file and adds or updates them.
IsValidValue(value)shared
Returns whether a value can be stored in a config key.
Load(fileName, loadGlobal)server
Loads saved config values from a data file, or applies every saved config file when no file is given.
LoadINI(fileName, bFromGame, bStripQuotes)shared
Reads an INI file into a table of sections.
Parse(text)shared
Replaces every $key$ in a text with the value of that config key.
Save(fileName, configTable)server
Saves the config entries that differ from their defaults.
Send(player, key)server
Sends shared config values to players over the Config Cable message.
SetInitialized(bInitalized)shared
Sets whether the config has been initialized.
SetSentInitialized(sentInitialized)client
Sets whether the client has told the server that its config has initialized.
ShareKey(key)shared
Registers a short CRC index for a config key so it is networked under the index instead of its name.

Functions

config.Add(key, value, isShared, isGlobal, isStatic, isPrivate, needsRestart)

shared gamemodes/catwork/gamemode/core/libraries/sh_config.lua:552

On the server

Adds a new config key with a default value.

Values saved in the global or schema config files are applied to the new key, and shared keys are sent to every player. The key's category is the name of the plugin being loaded, if any. Does nothing when the key already exists or the value is not a string, number or boolean.

config.Add('default_attribute_points', 30, true)
config.Add('mysql_host', '', nil, nil, true, true, true)

Parameters

  • key String Unique name of the key
  • value Any Default value; a string, number or boolean
  • isShared Boolean optional, defaults to nil Network the value to clients
  • isGlobal Boolean optional, defaults to nil Save the value for every schema instead of the current one
  • isStatic Boolean optional, defaults to nil Prevent the value from changing unless forced
  • isPrivate Boolean optional, defaults to nil Mark the key as private
  • needsRestart Boolean optional, defaults to nil Apply changes only after a restart

Returns

  • Config The new config object, or nil when the key was not added

On the client

Adds a config key on the client, usually when the server sends its value.

Does nothing when the key already exists or the value is not a string, number or boolean.

Parameters

  • key String Name of the key
  • value Any Value of the key, also used as its default

Returns

  • Config The new config object, or nil when the key was not added

Defined in

config.AddToSystem(name, key, help, minimum, maximum, decimals, category)

client gamemodes/catwork/gamemode/core/libraries/sh_config.lua:761

Adds a config key to the client's config system menu.

The category argument is ignored: it is always replaced by the name of the plugin being loaded, falling back to 'Clockwork'.

Parameters

  • name String Display name; the key when nil
  • key String The config key
  • help String Help text; '#ConfigNoHelp' when nil
  • minimum Number optional, defaults to 0 Minimum value for numeric keys
  • maximum Number optional, defaults to 100 Maximum value for numeric keys
  • decimals Number optional, defaults to 0 Number of decimals for numeric keys
  • category String optional, defaults to nil Unused

config.Get(key)

shared gamemodes/catwork/gamemode/core/libraries/sh_config.lua:357

Returns the config object for a key.

Objects for existing keys are cached. An object is returned even for keys that do not exist, so check it with CLASS_TABLE:IsValid when the key might be missing.

local walkSpeed = config.Get('walk_speed'):GetNumber(100)

Parameters

  • key String The config key

Returns

  • Config The config object

config.GetFromSystem(key)

client gamemodes/catwork/gamemode/core/libraries/sh_config.lua:777

Returns a config key's entry in the config system menu.

Parameters

  • key String The config key

Returns

  • Map The entry with name, help, minimum, maximum, decimals and category, or nil

config.GetStored()

shared gamemodes/catwork/gamemode/core/libraries/sh_config.lua:195

Returns the table of every config entry, indexed by key.

Returns

  • Map Config entries indexed by key, each with value, default and flag fields

config.GetVal(key, failSafe)

shared gamemodes/catwork/gamemode/core/libraries/sh_config.lua:376

Returns the current value of a config key without creating a config object.

Parameters

  • key String The config key
  • failSafe Any optional, defaults to nil Value returned when the key does not exist

Returns

  • Any The current value, or failSafe

See also

config.HasInitialized()

shared gamemodes/catwork/gamemode/core/libraries/sh_config.lua:167

Returns whether the config has been initialized.

Returns

config.HasSentInitialized()

client gamemodes/catwork/gamemode/core/libraries/sh_config.lua:746

Returns whether the client has told the server that its config has initialized.

Returns

  • Boolean Whether the ConfigInitialized message was sent

config.Import(fileName)

shared gamemodes/catwork/gamemode/core/libraries/sh_config.lua:211

Imports config keys from a text file and adds or updates them.

Each line has the form <class> <key> = <value>;, where the class contains any of boolean, number, force, global, shared, static, private and restart to set the type and flags. Lines starting with // and [section] lines are skipped. Existing keys are set, with force bypassing the static flag; new keys are added with config.Add.

shared number default_attribute_points = 30;

Parameters

  • fileName String Path of the file, relative to the GAME mount

config.IsValidValue(value)

shared gamemodes/catwork/gamemode/core/libraries/sh_config.lua:174

Returns whether a value can be stored in a config key.

Parameters

  • value Any The value to check

Returns

  • Boolean Whether the value is a string, number or boolean

config.Load(fileName, loadGlobal)

server gamemodes/catwork/gamemode/core/libraries/sh_config.lua:489

Loads saved config values from a data file, or applies every saved config file when no file is given.

Without a file name, the default and current map config files are read into config.global or config.schema and applied to existing keys whose saved default matches their current default, map values only applying on that map.

Parameters

  • fileName String optional, defaults to nil Name of the data file to read and return
  • loadGlobal Boolean optional, defaults to nil Use the framework's data folder instead of the schema's

Returns

  • Map The saved entries when fileName is given; nothing otherwise

config.LoadINI(fileName, bFromGame, bStripQuotes)

shared gamemodes/catwork/gamemode/core/libraries/sh_config.lua:256

Reads an INI file into a table of sections.

Comments starting with ; or # are stripped. Numeric and true/false values are converted.

Parameters

  • fileName String Path of the file
  • bFromGame Boolean optional, defaults to nil Read from the GAME mount instead of DATA
  • bStripQuotes Boolean optional, defaults to nil Remove double quotes from every line

Returns

  • Map Sections indexed by name, each a Map of keys to values; false when a line appears before the first section or a section header is not closed, nil when the file cannot be read

config.Parse(text)

shared gamemodes/catwork/gamemode/core/libraries/sh_config.lua:333

Replaces every $key$ in a text with the value of that config key.

Unknown keys are left in the text as they are.

config.Parse('Players start with $default_cash$ tokens.')

Parameters

  • text String The text to parse

Returns

  • String The text with the config values filled in

config.Save(fileName, configTable)

server gamemodes/catwork/gamemode/core/libraries/sh_config.lua:395

Saves the config entries that differ from their defaults.

Global keys are saved with cw.core:SaveClockworkData and schema keys with cw.core:SaveSchemaData. Map-specific, temporary and mysql_ keys are skipped, and a pending nextValue is saved in place of the current value. When configTable is nil, both saved files are deleted instead.

Parameters

  • fileName String Name of the data file, e.g. 'config' or 'config/gm_construct'
  • configTable Map optional, defaults to nil Config entries indexed by key, as returned by config.GetStored

config.Send(player, key)

server gamemodes/catwork/gamemode/core/libraries/sh_config.lua:437

Sends shared config values to players over the Config Cable message.

Only keys added as shared are sent. Bots are marked as config initialized straight away and fire PlayerConfigInitialized instead of being sent anything.

Parameters

  • player Player optional, defaults to nil The player to send to; every player when nil
  • key String optional, defaults to nil The key to send; every shared key when nil

config.SetInitialized(bInitalized)

shared gamemodes/catwork/gamemode/core/libraries/sh_config.lua:161

Sets whether the config has been initialized.

On the server, config changes are only saved and ClockworkConfigChanged is only fired once this is set; on the client it is set when the first Config message arrives from the server.

Parameters

  • bInitalized Boolean Whether the config has initialized

config.SetSentInitialized(sentInitialized)

client gamemodes/catwork/gamemode/core/libraries/sh_config.lua:740

Sets whether the client has told the server that its config has initialized.

Parameters

  • sentInitialized Boolean Whether the ConfigInitialized message was sent

config.ShareKey(key)

shared gamemodes/catwork/gamemode/core/libraries/sh_config.lua:183

Registers a short CRC index for a config key so it is networked under the index instead of its name.

Call it in both realms with the same key; the server maps the key to the index and the client maps the index back to the key.

Parameters

  • key String The config key

Defined in