Command Console - Revision history

Eric Lengyel: /* Core Engine Commands */

2024-11-27T09:12:03Z

Core Engine Commands

← Older revision		Revision as of 09:12, 27 November 2024
Line 63:		Line 63:
	\|-		\|-
	{{Tablerow\|<code>target</code> ''type''\|(Advanced) Opens the Target window, which displays one of the offscreen render targets. The value of ''type'' can be one of the following:		{{Tablerow\|<code>target</code> ''type''\|(Advanced) Opens the Target window, which displays one of the offscreen render targets. The value of ''type'' can be one of the following:
	* <code>strc</code> – ~~line~~ depth in structure buffer		* <code>strc</code> – linear depth in structure buffer
	* <code>grad</code> – gradient in structure buffer		* <code>grad</code> – gradient in structure buffer
	* <code>occl</code> – ambient occlusion buffer		* <code>occl</code> – ambient occlusion buffer

Eric Lengyel: /* Core Engine Commands */

2024-11-27T09:11:12Z

Core Engine Commands

← Older revision		Revision as of 09:11, 27 November 2024
Line 61:		Line 61:
	\|-		\|-
	{{Tablerow\|<code>tang</code>\|Toggles the display of tangent vectors.}}		{{Tablerow\|<code>tang</code>\|Toggles the display of tangent vectors.}}
			\|-
			{{Tablerow\|<code>target</code> ''type''\|(Advanced) Opens the Target window, which displays one of the offscreen render targets. The value of ''type'' can be one of the following:
			* <code>strc</code> – line depth in structure buffer
			* <code>grad</code> – gradient in structure buffer
			* <code>occl</code> – ambient occlusion buffer
			* <code>dist</code> – distortion buffer
			* <code>velo</code> – velocity buffer
			* <code>atms</code> – atmospheric shadowing buffer
			* <code>glbl</code> – glow/bloom buffer}}
	\|-		\|-
	{{Tablerow\|<code>time</code>\|Opens the Time window, which displays the frame rate in frames/s and ms/frame, the current load on the GPU and CPU, and a detailed breakdown of the time the engine spends on specific features such as shadows and post processing. (The Time window can also be opened by choosing '''C4 > Time Window'''.)}}		{{Tablerow\|<code>time</code>\|Opens the Time window, which displays the frame rate in frames/s and ms/frame, the current load on the GPU and CPU, and a detailed breakdown of the time the engine spends on specific features such as shadows and post processing. (The Time window can also be opened by choosing '''C4 > Time Window'''.)}}
			\|-
			{{Tablerow\|<code>tone</code>\|(Advanced) Opens the Tone Mapping window, which displays a luminance histogram and tone mapping curve.}}
	\|-		\|-
	{{Tablerow\|<code>unbind</code> ''key''\|Unbinds the key whose name is ''key''.}}		{{Tablerow\|<code>unbind</code> ''key''\|Unbinds the key whose name is ''key''.}}

Eric Lengyel: /* Disabling the Console */

2023-09-12T21:35:51Z

Disabling the Console

← Older revision		Revision as of 21:35, 12 September 2023
Line 147:		Line 147:
	The Command Console window can be opened when the keyboard is in either interface mode or game input mode, and both of these methods must be disabled in order to prevent access to the console. To make the Command Console window completely inaccessible, make the following two function calls:		The Command Console window can be opened when the keyboard is in either interface mode or game input mode, and both of these methods must be disabled in order to prevent access to the console. To make the Command Console window completely inaccessible, make the following two function calls:

	<~~source~~ lang="c++">		<syntaxhighlight lang="c++">
	TheInputMgr->SetConsoleCallback(nullptr);		TheInputMgr->SetConsoleCallback(nullptr);
	TheInterfaceMgr->DisableConsole();		TheInterfaceMgr->DisableConsole();
	</~~source~~>		</syntaxhighlight>

	If the Command Console window is later going to be enabled again, then it will also be necessary to save the previous console procedure so that it can be restored. This can be done by expanding the above code as follows:		If the Command Console window is later going to be enabled again, then it will also be necessary to save the previous console procedure so that it can be restored. This can be done by expanding the above code as follows:

	<~~source~~ lang="c++">		<syntaxhighlight lang="c++">
	// Declared in some larger scope:		// Declared in some larger scope:
	InputMgr::KeyCallback savedConsoleCallback;		InputMgr::KeyCallback savedConsoleCallback;
Line 166:		Line 166:
	TheInputMgr->SetConsoleCallback(nullptr);		TheInputMgr->SetConsoleCallback(nullptr);
	TheInterfaceMgr->DisableConsole();		TheInterfaceMgr->DisableConsole();
	</~~source~~>		</syntaxhighlight>

	To enable the Command Console window again and restore the previous console procedure in the Input Manager, use the following code:		To enable the Command Console window again and restore the previous console procedure in the Input Manager, use the following code:

	<~~source~~ lang="c++">		<syntaxhighlight lang="c++">
	TheInputMgr->SetConsoleProc(savedConsoleProc, savedConsoleCookie);		TheInputMgr->SetConsoleProc(savedConsoleProc, savedConsoleCookie);
	TheInterfaceMgr->EnableConsole();		TheInterfaceMgr->EnableConsole();
	</~~source~~>		</syntaxhighlight>

	== See Also ==		== See Also ==

Eric Lengyel: /* Console Output */

2023-09-12T21:35:39Z

Console Output

← Older revision		Revision as of 21:35, 12 September 2023
Line 137:		Line 137:
	For example, to write some integer value to the console with a text label, you could make the following call:		For example, to write some integer value to the console with a text label, you could make the following call:

	<~~source~~ lang="c++">		<syntaxhighlight lang="c++">
	Engine::Report(String<63>("My value is now ") += myValue);		Engine::Report(String<63>("My value is now ") += myValue);
	</~~source~~>		</syntaxhighlight>

	(The number 63 represents the maximum length of the string stored in the <code>String</code> object. This number can be omitted altogether to get an arbitrarily large string, but it causes extra memory allocations.)		(The number 63 represents the maximum length of the string stored in the <code>String</code> object. This number can be omitted altogether to get an arbitrarily large string, but it causes extra memory allocations.)

Eric Lengyel: /* Defining New Commands */

2023-09-12T21:35:29Z

Defining New Commands

← Older revision		Revision as of 21:35, 12 September 2023
Line 111:		Line 111:
	Application modules and plugin modules can add their own commands to the engine by creating new instances of the <code>Command</code> class. The constructor for the <code>Command</code> class takes a command string and a pointer to an observer object that is invoked when the command is executed. For example, to define a command called explode that causes the <code>MyClass::ExplodeFunction()</code> function to be called, you would construct a new <code>Command</code> instance as follows.		Application modules and plugin modules can add their own commands to the engine by creating new instances of the <code>Command</code> class. The constructor for the <code>Command</code> class takes a command string and a pointer to an observer object that is invoked when the command is executed. For example, to define a command called explode that causes the <code>MyClass::ExplodeFunction()</code> function to be called, you would construct a new <code>Command</code> instance as follows.

	<~~source~~ lang="c++">		<syntaxhighlight lang="c++">
	CommandObserver<MyClass> explodeObserver(this, &MyClass::ExplodeFunction);		CommandObserver<MyClass> explodeObserver(this, &MyClass::ExplodeFunction);
	Command *explodeCommand = new Command("explode", &explodeObserver);		Command *explodeCommand = new Command("explode", &explodeObserver);
	</~~source~~>		</syntaxhighlight>

	Once the command has been constructed, it needs to be added to the engine's command list before it will be recognized. This is done by calling the <code>Engine::AddCommand()</code> function. Continuing the explode example, you would make the following call to add the explode command to the engine.		Once the command has been constructed, it needs to be added to the engine's command list before it will be recognized. This is done by calling the <code>Engine::AddCommand()</code> function. Continuing the explode example, you would make the following call to add the explode command to the engine.

	<~~source~~ lang="c++">		<syntaxhighlight lang="c++">
	TheEngine->AddCommand(explodeCommand);		TheEngine->AddCommand(explodeCommand);
	</~~source~~>		</syntaxhighlight>

	Destroying the <code>Command</code> instance automatically removes the command from the engine.		Destroying the <code>Command</code> instance automatically removes the command from the engine.
Line 126:		Line 126:
	The observer event handling function assigned to a new command must have the following prototype.		The observer event handling function assigned to a new command must have the following prototype.

	<~~source~~ lang="c++">		<syntaxhighlight lang="c++">
	void ExplodeFunction(Command command, const char text);		void ExplodeFunction(Command command, const char text);
	</~~source~~>		</syntaxhighlight>

	When a command is entered into the console (or executed from a file), the observer event handler is invoked, and the text passed in through the text parameter provides the rest of the command line. For instance, the command <code>explode 1 boom</code> would cause the <code>ExplodeFunction()</code> function to be called with a pointer to the string <code>"1 boom"</code>.		When a command is entered into the console (or executed from a file), the observer event handler is invoked, and the text passed in through the text parameter provides the rest of the command line. For instance, the command <code>explode 1 boom</code> would cause the <code>ExplodeFunction()</code> function to be called with a pointer to the string <code>"1 boom"</code>.

Eric Lengyel: Created page with "right The '''Command Console''' window can be opened at any time by pressing the tilde/grave key. (On some non-English keyboards, the key directly below the Escape key should be used.) The window displays a command line and an output buffer as shown in the image to the right. If the C4 Engine was built using the debug settings, the window displays "(Debug)" to the right of the build number. The console stores a small command history that can b..."

2023-07-15T10:35:38Z

Created page with "480px|right The '''Command Console''' window can be opened at any time by pressing the tilde/grave key. (On some non-English keyboards, the key directly below the Escape key should be used.) The window displays a command line and an output buffer as shown in the image to the right. If the C4 Engine was built using the debug settings, the window displays "(Debug)" to the right of the build number. The console stores a small command history that can b..."

New page

[[File:Console.png|480px|right]]
The '''Command Console''' window can be opened at any time by pressing the tilde/grave key. (On some non-English keyboards, the key directly below the Escape key should be used.) The window displays a command line and an output buffer as shown in the image to the right. If the C4 Engine was built using the debug settings, the window displays "(Debug)" to the right of the build number.

The console stores a small command history that can be accessed with the up and down arrow keys.

__TOC__
<br clear="right" />

== Core Engine Commands ==

The following table describes some of the commands that are built into the engine. New commands can be added by an application or plugin module (see below).

{| {{Table}}
{{Tablehead|Command|Description}}
|-
{{Tablerow|<code>address</code>|Displays the IP address of the local machine. Must be in a network game.}}
|-
{{Tablerow|<code>bind</code> ''key'' <code>"</code>''command''<code>"</code>|Binds the key whose name is ''key'' to the command specified by ''command''. Whenever the bound key is pressed in gameplay mode, the specified command is executed.}}
|-
{{Tablerow|<code>body</code>|Toggles the display of bounding boxes for active rigid bodies.}}
|-
{{Tablerow|<code>cmd</code>|Displays a list of available console commands.}}
|-
{{Tablerow|<code>disconnect</code>|Disconnects from a multiplayer game.}}
|-
{{Tablerow|<code>dump</code>|Writes a list of all currently allocated memory blocks to the file <code>Memory.txt</code>. Leak detection must be turned on.}}
|-
{{Tablerow|<code>exec</code> ''path''|Executes the file <code>Data/*/''path''.cfg</code>.}}
|-
{{Tablerow|<code>gentex</code>|Opens the [[Texture Generation]] tool, which renders textures for light projections, environment maps, and impostor textures. (Can only be invoked while a game world is running.)}}
|-
{{Tablerow|<code>heap</code>|(Advanced) Displays memory heap totals in the console.}}
|-
{{Tablerow|<code>load</code> ''name''|Loads the world <code>''name''.wld</code> for gameplay.}}
|-
{{Tablerow|<code>lrgn</code>|(Advanced) Toggles the display of light regions.}}
|-
{{Tablerow|<code>net</code>|Opens the Network window, which displays various network statistics. (The Network window can also be opened by choosing '''C4 > Network Window'''.)}}
|-
{{Tablerow|<code>norm</code>|Toggles the display of normal vectors.}}
|-
{{Tablerow|<code>quit</code>|Quits the C4 Engine.}}
|-
{{Tablerow|<code>record</code> ''name''|Starts recording video and/or audio to files that can later be imported as a movie. See [[Recording Movies]] for more information.}}
|-
{{Tablerow|<code>resolve</code> ''hostname''|Resolves a host name to an IP address. Must be in a network game.}}
|-
{{Tablerow|<code>restore</code> ''name''|Restore the previously saved game <code>Save/''name''.sav</code>.}}
|-
{{Tablerow|<code>save</code> ''name''|Save the current game as <code>Save/''name''.sav</code>.}}
|-
{{Tablerow|<code>say</code> <code>"</code>''message''<code>"</code>|Sends a chat message to all players in the current multiplayer game.}}
|-
{{Tablerow|<code>shot</code> ''name''|Takes a [[Screenshots|screenshot]] and saves it as <code>''name''.tga</code> in the user's Documents directory in a subfolder named C4 Engine. If a <code>#</code> character appears in the name, then the name from that point on is replaced with a screenshot count that starts at 1 and gets incremented each time it is used in a screenshot name.}}
|-
{{Tablerow|<code>smap</code> ''type''|(Advanced) Opens the Shadow Map window for a particular light type. The value of ''type'' must be <code>inft</code>, <code>pont</code>, or <code>spot</code>.}}
|-
{{Tablerow|<code>spth</code>|(Advanced) Toggles the display of sound flow paths.}}
|-
{{Tablerow|<code>stat</code>|Opens the Stats window, which displays various engine statistics. (The Stats window can also be accessed by choosing '''C4 > Stats Window'''.)}}
|-
{{Tablerow|<code>tang</code>|Toggles the display of tangent vectors.}}
|-
{{Tablerow|<code>time</code>|Opens the Time window, which displays the frame rate in frames/s and ms/frame, the current load on the GPU and CPU, and a detailed breakdown of the time the engine spends on specific features such as shadows and post processing. (The Time window can also be opened by choosing '''C4 > Time Window'''.)}}
|-
{{Tablerow|<code>unbind</code> ''key''|Unbinds the key whose name is ''key''.}}
|-
{{Tablerow|<code>undef</code> ''name''|Undefines the variable ''name'', if the variable is not permanent.}}
|-
{{Tablerow|<code>unload</code>|Unloads the current gameplay world.}}
|-
{{Tablerow|<code>var</code>|Displays a list of currently defined system variables.}}
|-
{{Tablerow|<code>wire</code>|Toggles the display of the wireframe overlay.}}
|}

== Tool Commands ==

The following commands are defined by the standard tools that ship with the C4 Engine. Most of these commands have equivalent items in the [[C4 Menu]]. If the ''name'' parameter is omitted from any of these commands, then a file picker dialog will appear to let you select a file.

{| {{Table}}
{{Tablehead|Command|Description}}
|-
{{Tablerow|<code>ifont</code>|Opens the [[Font Importer]] tool. (This tool can also be opened by choosing '''C4 > Import Font'''.)}}
|-
{{Tablerow|<code>imovie</code>|Opens the [[Movie Importer]] tool. (Movies can also be imported by choosing '''C4 > Import Movie'''.)}}
|-
{{Tablerow|<code>isound</code> ''name''|Imports the sound file <code>''name''.wav</code>. See also [[Sound Importer]]. (Sounds can also be imported by choosing '''C4 > Import Sound'''.)}}
|-
{{Tablerow|<code>istring</code> ''name''|Imports the string table file <code>''name''.txt</code>. See also [[String Tables]]. (String tables can also be imported by choosing '''C4 > Import String Table'''.)}}
|-
{{Tablerow|<code>itexture</code> ''name''|Imports the texture file <code>''name''.tga</code>. See also [[Texture Importer]]. (Textures can also be imported by choosing '''C4 > Import Texture'''.)}}
|-
{{Tablerow|<code>model</code> ''name''|Opens the model file <code>''name''.mdl</code> in the [[Model Viewer]] tool. (Models can also be opened by choosing '''C4 > Open Model'''.)}}
|-
{{Tablerow|<code>movie</code> ''name''|Opens the movie file <code>''name''.mvi</code> in the [[Movie Player]] tool. (Movies can also be opened by choosing '''C4 > Open Movie'''.)}}
|-
{{Tablerow|<code>pack</code> ''name''|Creates a pack file, where ''name'' is the name of a top-level subfolder in the <code>Data</code> directory. See also [[Pack Files and Virtual Directories]].}}
|-
{{Tablerow|<code>panel</code> ''name''|Opens the panel file <code>''name''.pan</code> in the [[Panel Editor]] tool. (Panels can also be opened by choosing '''C4 > Open Panel'''.)}}
|-
{{Tablerow|<code>sound</code> ''name''|Opens the sounds file <code>''name''.snd</code> in the [[Sound Player]] tool. (Sounds can also be opened by choosing '''C4 > Open Sound'''.)}}
|-
{{Tablerow|<code>texture</code> ''name''|Opens the texture file <code>''name''.tex</code> in the [[Texture Viewer]] tool. (Textures can also be opened by choosing '''C4 > Open Texture'''.)}}
|-
{{Tablerow|<code>world</code> ''name''|Opens the world file <code>''name''.wld</code> in the [[World Editor]] tool. (Worlds can also be opened by choosing '''C4 > Open World'''.)}}
|}

== Defining New Commands ==

Application modules and plugin modules can add their own commands to the engine by creating new instances of the <code>Command</code> class. The constructor for the <code>Command</code> class takes a command string and a pointer to an observer object that is invoked when the command is executed. For example, to define a command called explode that causes the <code>MyClass::ExplodeFunction()</code> function to be called, you would construct a new <code>Command</code> instance as follows.

<source lang="c++">
CommandObserver<MyClass> explodeObserver(this, &MyClass::ExplodeFunction);
Command *explodeCommand = new Command("explode", &explodeObserver);
</source>

Once the command has been constructed, it needs to be added to the engine's command list before it will be recognized. This is done by calling the <code>Engine::AddCommand()</code> function. Continuing the explode example, you would make the following call to add the explode command to the engine.

<source lang="c++">
TheEngine->AddCommand(explodeCommand);
</source>

Destroying the <code>Command</code> instance automatically removes the command from the engine.

The observer event handling function assigned to a new command must have the following prototype.

<source lang="c++">
void ExplodeFunction(Command *command, const char *text);
</source>

When a command is entered into the console (or executed from a file), the observer event handler is invoked, and the text passed in through the text parameter provides the rest of the command line. For instance, the command <code>explode 1 boom</code> would cause the <code>ExplodeFunction()</code> function to be called with a pointer to the string <code>"1 boom"</code>.

== Console Output ==

You can write text to the Command Console window by calling the <code>Engine::Report()</code> function. The string passed to the <code>Engine::Report()</code> function is output to the console whenever the <code>flags</code> parameter does not include the bit <code>kReportLog</code>.
For example, to write some integer value to the console with a text label, you could make the following call:

<source lang="c++">
Engine::Report(String<63>("My value is now ") += myValue);
</source>

(The number 63 represents the maximum length of the string stored in the <code>String</code> object. This number can be omitted altogether to get an arbitrarily large string, but it causes extra memory allocations.)

== Disabling the Console ==

The Command Console window can be opened when the keyboard is in either interface mode or game input mode, and both of these methods must be disabled in order to prevent access to the console. To make the Command Console window completely inaccessible, make the following two function calls:

<source lang="c++">
TheInputMgr->SetConsoleCallback(nullptr);
TheInterfaceMgr->DisableConsole();
</source>

If the Command Console window is later going to be enabled again, then it will also be necessary to save the previous console procedure so that it can be restored. This can be done by expanding the above code as follows:

<source lang="c++">
// Declared in some larger scope:
InputMgr::KeyCallback savedConsoleCallback;
void *savedConsoleCookie;

...

savedConsoleCallback = TheInputMgr->GetConsoleCallback();
savedConsoleCookie = TheInputMgr->GetConsoleCookie();

TheInputMgr->SetConsoleCallback(nullptr);
TheInterfaceMgr->DisableConsole();
</source>

To enable the Command Console window again and restore the previous console procedure in the Input Manager, use the following code:

<source lang="c++">
TheInputMgr->SetConsoleProc(savedConsoleProc, savedConsoleCookie);
TheInterfaceMgr->EnableConsole();
</source>

== See Also ==

* [[C4 Menu]]
* [[List of System Variables]]