Adding new Cvars - Revision history

Stgatilov at 17:37, 5 January 2025

2025-01-05T17:37:19Z

← Older revision		Revision as of 17:37, 5 January 2025
Line 68:		Line 68:
	More info can be found in: '''framework/cvarsystem.h'''. This file actually contains a lot of documentation in the form of comments.		More info can be found in: '''framework/cvarsystem.h'''. This file actually contains a lot of documentation in the form of comments.

	= ~~Creating a~~ CVAR using script =		= Create or override CVAR using game script =

	If you ~~need~~ to create a cvar for use with game script, you~~'re in for a much easier ride~~.		If you want to create a new cvar for use with game script, you can do it dynamically during gameplay.
	This command will create a new cvar or modify the value of existing cvar:		This command will create a new cvar or modify the value of existing cvar:

Line 83:		Line 83:
	float value = sys.getcvarf("name");		float value = sys.getcvarf("name");

	Starting from TDM 2.13, <tt>sys.setcvar</tt> sets "mission override" for a cvar but does not modify the user-specified value.		Starting from TDM 2.13, <tt>sys.setcvar</tt> sets '''mission override''' for a cvar but does not modify the user-specified value.

	Mission override has special behavior and is considered to be part of gameplay state: it is saved/restored in savefiles, cleared on game start/end, and never saved into darkmod.cfg even for archived cvars.		Mission override has special behavior and is considered to be part of gameplay state: it is saved/restored in savefiles, cleared on game start/end, and never saved into darkmod.cfg even for archived cvars.

Stgatilov: Updated Cvar interactions in game scripts: mission override, binding to variable deleted.

2025-01-05T17:27:53Z

Updated Cvar interactions in game scripts: mission override, binding to variable deleted.

← Older revision		Revision as of 17:27, 5 January 2025
Line 69:		Line 69:

	= Creating a CVAR using script =		= Creating a CVAR using script =
	~~If you need to create a cvar for use with script, you're in for a much easier ride. Just use this line:~~

	~~sys~~.~~setcvar("name", variable);~~		If you need to create a cvar for use with game script, you're in for a much easier ride.
			This command will create a new cvar or modify the value of existing cvar:

	~~where~~ name ~~is the actual name of the cvar that the user will type in the console~~, ~~and variable is a variable you have already created in your script that will change when the user enters a new~~ value ~~for this cvar.~~		sys.setcvar("name", value);

	~~The initial value of your variable will be considered~~ the ~~default value~~ of the cvar ~~when~~ the ~~map starts (for when you~~ type the ~~name of~~ the cvar ~~in the console~~ and it will ~~tell you~~ its ~~default~~ value ~~and~~ current value).		where 'name' is the actual name of the cvar that the user will type in the console, and 'value' is the string you want to assign.

			User will see this cvar and will be able to modify its value.
			You can read the current effective value of the cvar by executing:

	''Geep comments, 2023/TDM 2.11: I don't know if this is how setcvar worked at one time, with some sort of persistant binding to the script variable, but it doesn't seem to do that now. The call just acts as a one-time assignment of the variable's value; and''
	string value = sys.getcvar("name");		string value = sys.getcvar("name");
	~~''goes~~ the ~~other way~~.''		float value = sys.getcvarf("name");

			Starting from TDM 2.13, <tt>sys.setcvar</tt> sets "mission override" for a cvar but does not modify the user-specified value.

			Mission override has special behavior and is considered to be part of gameplay state: it is saved/restored in savefiles, cleared on game start/end, and never saved into darkmod.cfg even for archived cvars.
			This is not important for cvars that you create dynamically, but very important if you modify the existing predefined cvars. See also [https://bugs.thedarkmod.com/view.php?id=5453 #5453].

	= CVARs and the GUI =		= CVARs and the GUI =

Geep: /* Creating a CVAR using script */ Report different behavior

2023-02-01T22:35:16Z

Creating a CVAR using script: Report different behavior

← Older revision		Revision as of 22:35, 1 February 2023
Line 76:		Line 76:

	The initial value of your variable will be considered the default value of the cvar when the map starts (for when you type the name of the cvar in the console and it will tell you its default value and current value).		The initial value of your variable will be considered the default value of the cvar when the map starts (for when you type the name of the cvar in the console and it will tell you its default value and current value).

			''Geep comments, 2023/TDM 2.11: I don't know if this is how setcvar worked at one time, with some sort of persistant binding to the script variable, but it doesn't seem to do that now. The call just acts as a one-time assignment of the variable's value; and''
			string value = sys.getcvar("name");
			''goes the other way.''

	= CVARs and the GUI =		= CVARs and the GUI =

Nbohr1more: /* Other Flags */

2016-08-25T17:58:25Z

Other Flags

← Older revision		Revision as of 17:58, 25 August 2016
Line 30:		Line 30:
	* CVAR_GAME, CVAR_RENDERER : Identifies the CVar as having to do with the game, or having to do with the renderer. Since we can't add anything to the renderer, I'm guessing we'll always ue CVAR_GAME.		* CVAR_GAME, CVAR_RENDERER : Identifies the CVar as having to do with the game, or having to do with the renderer. Since we can't add anything to the renderer, I'm guessing we'll always ue CVAR_GAME.
	* CVAR_GUI : Used by the GUI (the difference to "CVAR_GAME" is unclear)		* CVAR_GUI : Used by the GUI (the difference to "CVAR_GAME" is unclear)
	* CVAR_ARCHIVE : If set, the value of this CVAR will be stored to your ~~DoomConfig~~.cfg file, and saved. When you next start the game, the CVAR will have the same value, it will NOT go back to the default. (You can see what the default value was and set it back yourself by using listcvars <the cvar>).		* CVAR_ARCHIVE : If set, the value of this CVAR will be stored to your Darkmod.cfg file, and saved. When you next start the game, the CVAR will have the same value, it will NOT go back to the default. (You can see what the default value was and set it back yourself by using listcvars <the cvar>).
	* CVAR_NETWORKSYNC : Probably means that in multiplayer games, this is read from the server, so individuals cannot change it to a different setting on their client. Examples include jump height, walking speed, etc.		* CVAR_NETWORKSYNC : Probably means that in multiplayer games, this is read from the server, so individuals cannot change it to a different setting on their client. Examples include jump height, walking speed, etc.
	* CVAR_SERVERINFO : Server settings		* CVAR_SERVERINFO : Server settings

Tels: add info

2011-10-16T17:57:10Z

add info

← Older revision		Revision as of 17:57, 16 October 2011
Line 7:		Line 7:
	= Add a declaration of the cvar in game/gamesys/syscvar.cpp =		= Add a declaration of the cvar in game/gamesys/syscvar.cpp =

	idCVar ~~cv_ai_sndvol~~( "tdm_ai_sndvol", "0.0", CVAR_GAME \| CVAR_ARCHIVE \| CVAR_FLOAT,		idCVar cv_tdm_ai_sndvol( "tdm_ai_sndvol", "0.0", CVAR_GAME \| CVAR_ARCHIVE \| CVAR_FLOAT,
	"Modifier to the volume of suspcious sounds that AI's hear. Defaults to 0.0 dB" );		"Modifier to the volume of suspcious sounds that AI's hear. Defaults to 0.0 dB" );

Line 29:		Line 29:
	== Other Flags ==		== Other Flags ==
	* CVAR_GAME, CVAR_RENDERER : Identifies the CVar as having to do with the game, or having to do with the renderer. Since we can't add anything to the renderer, I'm guessing we'll always ue CVAR_GAME.		* CVAR_GAME, CVAR_RENDERER : Identifies the CVar as having to do with the game, or having to do with the renderer. Since we can't add anything to the renderer, I'm guessing we'll always ue CVAR_GAME.
	* CVAR_GUI : ~~USed~~ by the GUI (the difference to "CVAR_GAME" is unclear)		* CVAR_GUI : Used by the GUI (the difference to "CVAR_GAME" is unclear)
	* CVAR_ARCHIVE : If set, the value of this CVAR will be stored to your DoomConfig.cfg file, and saved. When you next start the game, the CVAR will have the same value, it will NOT go back to the default. (You can see what the default value was and set it back yourself by using listcvars <the cvar>).		* CVAR_ARCHIVE : If set, the value of this CVAR will be stored to your DoomConfig.cfg file, and saved. When you next start the game, the CVAR will have the same value, it will NOT go back to the default. (You can see what the default value was and set it back yourself by using listcvars <the cvar>).
	* CVAR_NETWORKSYNC : Probably means that in multiplayer games, this is read from the server, so individuals cannot change it to a different setting on their client. Examples include jump height, walking speed, etc.		* CVAR_NETWORKSYNC : Probably means that in multiplayer games, this is read from the server, so individuals cannot change it to a different setting on their client. Examples include jump height, walking speed, etc.
Line 43:		Line 43:
	= Adding extern declaration in game/gamesys/syscvar.h =		= Adding extern declaration in game/gamesys/syscvar.h =

	extern idCVar ~~cv_ai_sndvol~~;		extern idCVar cv_tdm_ai_sndvol;

	This step is pretty self explanatory, just add the extern declaration in syscvar.h. (Unfortunately, changing syscvar.h requires a recompile of all the src, since it is included in game_local.h, and that is included in pretty much everything.)		This step is pretty self explanatory, just add the extern declaration in syscvar.h. (Unfortunately, changing syscvar.h requires a recompile of all the src, since it is included in game_local.h, and that is included in pretty much everything.)
Line 50:		Line 50:
	To set and read the variable: use the appropriate idCvar::Set* and idCVar::Get* functions, where the * is replaced with the CVar type that you declared before.		To set and read the variable: use the appropriate idCvar::Set* and idCVar::Get* functions, where the * is replaced with the CVar type that you declared before.

	For example, suppose we want to use our ~~cv_ai_sndvol~~ in the code. Suppose we want to subtract it from some value InitialVolume.		For example, suppose we want to use our cv_tdm_ai_sndvol in the code. Suppose we want to subtract it from some value InitialVolume.

	float AdjustedVolume = InitialVolume - ~~cv_ai_sndvol~~.GetFloat();		float AdjustedVolume = InitialVolume - cv_tdm_ai_sndvol.GetFloat();

	Similarly, to set it in the SDK;		Similarly, to set it in the SDK;

	~~cv_ai_sndvol~~.SetFloat( 5.0f );		cv_tdm_ai_sndvol.SetFloat( 5.0f );

	== Side note: Manipulating cvars ingame in the console ==		== Side note: Manipulating cvars ingame in the console ==
Line 87:		Line 87:
	The user is presented with the list of choices from "choices", and for each of these, the appropriate value from "values" is set into "r_aspectRatio". So when this field is changed, the value of r_aspectRatio is automatically changed, too.		The user is presented with the list of choices from "choices", and for each of these, the appropriate value from "values" is set into "r_aspectRatio". So when this field is changed, the value of r_aspectRatio is automatically changed, too.

	Note: Choices ~~seem to be~~ limited to ASCII strings and the values are limited to valid choices for this CVAR.
			{{infobox\|'''Note: Choices are limited to ASCII strings and the values are limited to valid choices for this CVAR. See [[I18N]] for details and how to work around that limitation.'''}}

	{{sdk}} [[Category:CVARS]]		{{sdk}} [[Category:CVARS]]

Tels: add info about GUI

2011-08-05T07:47:09Z

add info about GUI

← Older revision		Revision as of 07:47, 5 August 2011
Line 29:		Line 29:
	== Other Flags ==		== Other Flags ==
	* CVAR_GAME, CVAR_RENDERER : Identifies the CVar as having to do with the game, or having to do with the renderer. Since we can't add anything to the renderer, I'm guessing we'll always ue CVAR_GAME.		* CVAR_GAME, CVAR_RENDERER : Identifies the CVar as having to do with the game, or having to do with the renderer. Since we can't add anything to the renderer, I'm guessing we'll always ue CVAR_GAME.
			* CVAR_GUI : USed by the GUI (the difference to "CVAR_GAME" is unclear)
	* CVAR_ARCHIVE : If set, the value of this CVAR will be stored to your DoomConfig.cfg file, and saved. When you next start the game, the CVAR will have the same value, it will NOT go back to the default. (You can see what the default value was and set it back yourself by using listcvars <the cvar>).		* CVAR_ARCHIVE : If set, the value of this CVAR will be stored to your DoomConfig.cfg file, and saved. When you next start the game, the CVAR will have the same value, it will NOT go back to the default. (You can see what the default value was and set it back yourself by using listcvars <the cvar>).
	* CVAR_NETWORKSYNC : Probably means that in multiplayer games, this is read from the server, so individuals cannot change it to a different setting on their client. Examples include jump height, walking speed, etc.		* CVAR_NETWORKSYNC : Probably means that in multiplayer games, this is read from the server, so individuals cannot change it to a different setting on their client. Examples include jump height, walking speed, etc.
Line 76:		Line 77:
	The initial value of your variable will be considered the default value of the cvar when the map starts (for when you type the name of the cvar in the console and it will tell you its default value and current value).		The initial value of your variable will be considered the default value of the cvar when the map starts (for when you type the name of the cvar in the console and it will tell you its default value and current value).

	~~[[Category~~:~~SDK]]~~		= CVARs and the GUI =
	[[Category:CVARS]]
			It is possible to bind an input field directly to a CVAR via:

			choices "#str_07213" // Aspect ratio
			values "0;1;4;2;3"
			cvar "r_aspectRatio"

			The user is presented with the list of choices from "choices", and for each of these, the appropriate value from "values" is set into "r_aspectRatio". So when this field is changed, the value of r_aspectRatio is automatically changed, too.

			Note: Choices seem to be limited to ASCII strings and the values are limited to valid choices for this CVAR.

			{{sdk}} [[Category:CVARS]]

Nbohr1more: /* Creating a CVAR using script */

2011-04-13T20:20:41Z

Creating a CVAR using script

← Older revision		Revision as of 20:20, 13 April 2011
Line 77:		Line 77:

	[[Category:SDK]]		[[Category:SDK]]
			[[Category:CVARS]]

Tels: fix typos

2010-06-21T14:57:32Z

fix typos

← Older revision		Revision as of 14:57, 21 June 2010
Line 5:		Line 5:
	Let's use the example of adding a cvar to globally lower the volume of sounds that AI hear. We want to add a cvar called dm_ai_sndvol so we can adjust the volume of sounds that AI hear in realtime in the console.		Let's use the example of adding a cvar to globally lower the volume of sounds that AI hear. We want to add a cvar called dm_ai_sndvol so we can adjust the volume of sounds that AI hear in realtime in the console.

	= Add a declaration of the cvar in /game/gamesys/syscvar.cpp =		= Add a declaration of the cvar in game/gamesys/syscvar.cpp =

	idCVar cv_ai_sndvol( "tdm_ai_sndvol", "0.0", CVAR_GAME \| CVAR_ARCHIVE \| CVAR_FLOAT,		idCVar cv_ai_sndvol( "tdm_ai_sndvol", "0.0", CVAR_GAME \| CVAR_ARCHIVE \| CVAR_FLOAT,
Line 40:		Line 40:
	CVAR_ARCHIVE, CVAR_USERINFO, CVAR_SERVERINFO, CVAR_NETWORKSYNC is set.		CVAR_ARCHIVE, CVAR_USERINFO, CVAR_SERVERINFO, CVAR_NETWORKSYNC is set.

	= Adding extern declaration in /game/gamesys/syscvar.h =		= Adding extern declaration in game/gamesys/syscvar.h =

	extern idCVar cv_ai_sndvol;		extern idCVar cv_ai_sndvol;

Tels: fix file names

2010-01-07T07:06:45Z

fix file names

← Older revision		Revision as of 07:06, 7 January 2010
Line 1:		Line 1:
	{{Original_Reference\|Ishtvan & Domarius\|2600}}		{{Original_Reference\|Ishtvan & Domarius\|2600}}

	To add a new console variable (cvar) the files that must be changed are /~~src~~/gamesys/syscvar.*		To add a new console variable (cvar) the files that must be changed are /game/gamesys/syscvar.*

	Let's use the example of adding a cvar to globally lower the volume of sounds that AI hear. We want to add a cvar called dm_ai_sndvol so we can adjust the volume of sounds that AI hear in realtime in the console.		Let's use the example of adding a cvar to globally lower the volume of sounds that AI hear. We want to add a cvar called dm_ai_sndvol so we can adjust the volume of sounds that AI hear in realtime in the console.

	= Add a declaration of the cvar in /~~src~~/gamesys/syscvar.cpp =		= Add a declaration of the cvar in /game/gamesys/syscvar.cpp =

	idCVar cv_ai_sndvol( "tdm_ai_sndvol", "0.0", CVAR_GAME \| CVAR_ARCHIVE \| CVAR_FLOAT,		idCVar cv_ai_sndvol( "tdm_ai_sndvol", "0.0", CVAR_GAME \| CVAR_ARCHIVE \| CVAR_FLOAT,
Line 40:		Line 40:
	CVAR_ARCHIVE, CVAR_USERINFO, CVAR_SERVERINFO, CVAR_NETWORKSYNC is set.		CVAR_ARCHIVE, CVAR_USERINFO, CVAR_SERVERINFO, CVAR_NETWORKSYNC is set.

	= Adding extern declaration in /~~src~~/gamesys/syscvar.h =		= Adding extern declaration in /game/gamesys/syscvar.h =

	extern idCVar cv_ai_sndvol;		extern idCVar cv_ai_sndvol;
Line 65:		Line 65:
	I believe you can also omit the "set" and just type "<cvar name> <value>" to set the value.		I believe you can also omit the "set" and just type "<cvar name> <value>" to set the value.

	More info can be found in: '''~~src/~~framework/cvarsystem.h'''. This file actually contains a lot of documentation in the form of comments.		More info can be found in: '''framework/cvarsystem.h'''. This file actually contains a lot of documentation in the form of comments.

	= Creating a CVAR using script =		= Creating a CVAR using script =

Greebo: naming convention for CVARs

2008-06-30T07:40:51Z

naming convention for CVARs

← Older revision		Revision as of 07:40, 30 June 2008
Line 7:		Line 7:
	= Add a declaration of the cvar in /src/gamesys/syscvar.cpp =		= Add a declaration of the cvar in /src/gamesys/syscvar.cpp =

	idCVar cv_ai_sndvol( "~~dm_ai_sndvol~~", "0.0", CVAR_GAME \| CVAR_ARCHIVE \| CVAR_FLOAT,		idCVar cv_ai_sndvol( "tdm_ai_sndvol", "0.0", CVAR_GAME \| CVAR_ARCHIVE \| CVAR_FLOAT,
	"Modifier to the volume of suspcious sounds that AI's hear. Defaults to 0.0 dB" );		"Modifier to the volume of suspcious sounds that AI's hear. Defaults to 0.0 dB" );

Line 15:		Line 15:
	"<Brief description of the variable>" );		"<Brief description of the variable>" );

	Our naming convention for the SDK variable name is "cv_*", where the cv indicates it's a cvar. This should be followed. The name ingame can be whatever you want, I've been using the format ~~dm_ai_~~ .. for stuff having to do with the AI, etc.		Our naming convention for the SDK variable name is "cv_*", where the cv indicates it's a cvar. This should be followed. The name ingame can be whatever you want but it has to include the tdm_ prefix at least. I've been using the format tdm_ai_ .. for stuff having to do with the AI, etc.

	Note that the default value is stored as a string. These things are parsed just like key/value pairs, so the name and default value are both strings.		Note that the default value is stored as a string. These things are parsed just like key/value pairs, so the name and default value are both strings.