CVARINFO
Jump to navigation
Jump to search
CVARINFO is a lump for defining custom, mod-specific CVARs. The syntax is as follows:
<scope> [noarchive] [cheat] [latch] [handlerclass("<classname>")] <type> <name> [= defaultvalue];
Scope
This can be one of the following:
- server
- This CVAR is shared by all players, and in network games, only select players can change it. Changes to server CVARs will not be reflected until at-least one tic later (network games will make this length of time indeterminate). Their values are saved to savegame. In ZScript server CVARs are readable directly, like global variables.
- user
- This CVar is not saved to save games, but is written into config (changing this CVar, then loading an earlier save will not modify its value). Each player has their own copy of this CVAR, which they can change independently. Changes to these variables are immediate and are shared across network.
- User CVars can be used to store per-player data that should still be visible to all players in multiplayer. For example, player's name, skin, color, gender and such are stored in user CVars.
- User CVars can be retrieved with CVar.GetCvar('<cvarname>', <PlayerInfo pointer>). Warning: Using CVar.FindCVar or passing
consoleplayeras the PlayerInfo pointer in GetCVar will obtain data for consoleplayer, not shared across network, and if any gameplay changes are tied to this value, it'll cause a desync in multiplayer.
- nosave
- Similarly to user CVars, nosave CVARs are only saved in config files, and each player has their own copy of this CVar. However, they're also not shared across network, so other players don't have access to each other values for this CVar.
- Nosave CVars should be used to store user-specific options that are not relevant to other players. For example, options that can modify some UI aspects (such as elements of a custom ZScript HUD) can be tied to a nosave CVar.
- Nothing that can modify the playsim (such as spawning actors) should be tied to nosave CVars, because doing so will cause a desync in multiplayer, since nosave CVar values aren't sent across network.
- Nosave CVars can be read directly, just like server CVars. If there's a need to obtain a pointer to it, CVar.FindCVar('<cvarname>') can be safely used, because this function always retrieves the CVar for the consoleplayer, and nosave CVars are not shared across network.
Summarized:
| server | user | nosave | |
|---|---|---|---|
| Stored in save games | Yes | No | No |
| Who can modify in multiplayer | Only host | Anyone | Anyone |
| Can value be different for each player? | No | Yes | Yes |
| Shared across network | Yes | Yes | No |
| How to read in ZScript | Readable directly by name, like a global variable. | CVar.GetCvar('<cvarname>', <PlayerInfo pointer>) This retrieves a pointer to the CVar. To get the actual value, use GetInt(), GetFloat(), GetBool(), GetString().
|
Readable directly by name, like a global variable. CVar.GetCVar and CVar.FindCVar can also be used to cache a pointer to the CVar, but usually aren't necessary. |
| Intended use | Data that affects all players equally (usually, gameplay changes) | Data unique to each player but visible for other players and their clients. This can either be tied to visual-only options, or to events that affect player separately, for example when you want to give each player a different item. |
Local user options that aren't relevant to other users. Nothing that modifies playsim should ever be tied to nosave CVars! |
| Note: Server CVAR names must be no longer than 63 characters. While GZDoom 3.4 will refuse to load, prior versions will suffer issues with multiplayer. |
Other options
- noarchive: If present, it prevents the CVAR from being written to the configuration file.
- cheat: If present, the CVAR can only be modified by console if sv_cheats is enabled. ACS can still change these freely.
- latch: Changes to this CVAR only take effect upon starting a new game. This is only the case when changing it from the console, however.
- handlerclass: See Handlers for more information.
- type: The data type of the CVAR's value, which can be one of the following:
- int — An integer value. Defaults to 0.
- float — A value that can include a fraction. Defaults to 0.0.
- color — A color value. Defaults to black ("00 00 00").
- bool — A boolean value that can hold either true or false. Defaults to false.
- string — A string value. It is not too useful for mods but is included for completeness. Defaults to "".
- name: The CVAR's name. It must begin with a letter and may only include alphanumeric characters and the underscore character.
 |
Warning: User CVAR name and its value cannot contain more than 254 characters in total. It may be saved to the external configuration file without warning, but the engine will refuse to load it next parsing. Error description will not contain the CVar name. |
- defaultvalue: The default value to be given to the CVAR, if desired.
Example
This creates an integer CVAR with the name mymod_coolness. The CVAR is shared by all players. It has a default value of 10, and it is saved in the configuration file.
server int mymod_coolness = 10;