Command Console: Difference between revisions

From C4 Engine Wiki
Jump to navigation Jump to search
(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...")
 
 
(2 intermediate revisions by the same user not shown)
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>.
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.)
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 ==

Latest revision as of 21:35, 12 September 2023

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.


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

Command

Description

address

Displays the IP address of the local machine. Must be in a network game.

bind key "command"

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.

body

Toggles the display of bounding boxes for active rigid bodies.

cmd

Displays a list of available console commands.

disconnect

Disconnects from a multiplayer game.

dump

Writes a list of all currently allocated memory blocks to the file Memory.txt. Leak detection must be turned on.

exec path

Executes the file Data/*/path.cfg.

gentex

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

heap

(Advanced) Displays memory heap totals in the console.

load name

Loads the world name.wld for gameplay.

lrgn

(Advanced) Toggles the display of light regions.

net

Opens the Network window, which displays various network statistics. (The Network window can also be opened by choosing C4 > Network Window.)

norm

Toggles the display of normal vectors.

quit

Quits the C4 Engine.

record name

Starts recording video and/or audio to files that can later be imported as a movie. See Recording Movies for more information.

resolve hostname

Resolves a host name to an IP address. Must be in a network game.

restore name

Restore the previously saved game Save/name.sav.

save name

Save the current game as Save/name.sav.

say "message"

Sends a chat message to all players in the current multiplayer game.

shot name

Takes a screenshot and saves it as name.tga in the user's Documents directory in a subfolder named C4 Engine. If a # 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.

smap type

(Advanced) Opens the Shadow Map window for a particular light type. The value of type must be inft, pont, or spot.

spth

(Advanced) Toggles the display of sound flow paths.

stat

Opens the Stats window, which displays various engine statistics. (The Stats window can also be accessed by choosing C4 > Stats Window.)

tang

Toggles the display of tangent vectors.

time

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

unbind key

Unbinds the key whose name is key.

undef name

Undefines the variable name, if the variable is not permanent.

unload

Unloads the current gameplay world.

var

Displays a list of currently defined system variables.

wire

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.

Command

Description

ifont

Opens the Font Importer tool. (This tool can also be opened by choosing C4 > Import Font.)

imovie

Opens the Movie Importer tool. (Movies can also be imported by choosing C4 > Import Movie.)

isound name

Imports the sound file name.wav. See also Sound Importer. (Sounds can also be imported by choosing C4 > Import Sound.)

istring name

Imports the string table file name.txt. See also String Tables. (String tables can also be imported by choosing C4 > Import String Table.)

itexture name

Imports the texture file name.tga. See also Texture Importer. (Textures can also be imported by choosing C4 > Import Texture.)

model name

Opens the model file name.mdl in the Model Viewer tool. (Models can also be opened by choosing C4 > Open Model.)

movie name

Opens the movie file name.mvi in the Movie Player tool. (Movies can also be opened by choosing C4 > Open Movie.)

pack name

Creates a pack file, where name is the name of a top-level subfolder in the Data directory. See also Pack Files and Virtual Directories.

panel name

Opens the panel file name.pan in the Panel Editor tool. (Panels can also be opened by choosing C4 > Open Panel.)

sound name

Opens the sounds file name.snd in the Sound Player tool. (Sounds can also be opened by choosing C4 > Open Sound.)

texture name

Opens the texture file name.tex in the Texture Viewer tool. (Textures can also be opened by choosing C4 > Open Texture.)

world name

Opens the world file name.wld 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 Command class. The constructor for the Command 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 MyClass::ExplodeFunction() function to be called, you would construct a new Command instance as follows. 

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

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 Engine::AddCommand() function. Continuing the explode example, you would make the following call to add the explode command to the engine. 

TheEngine->AddCommand(explodeCommand);

Destroying the Command instance automatically removes the command from the engine.

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

void ExplodeFunction(Command *command, const char *text);

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 explode 1 boom would cause the ExplodeFunction() function to be called with a pointer to the string "1 boom".

Console Output

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

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

(The number 63 represents the maximum length of the string stored in the String 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: 

TheInputMgr->SetConsoleCallback(nullptr);
TheInterfaceMgr->DisableConsole();

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: 

// Declared in some larger scope:
InputMgr::KeyCallback    savedConsoleCallback;
void                     *savedConsoleCookie;

...

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

TheInputMgr->SetConsoleCallback(nullptr);
TheInterfaceMgr->DisableConsole();

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

TheInputMgr->SetConsoleProc(savedConsoleProc, savedConsoleCookie);
TheInterfaceMgr->EnableConsole();

See Also

Retrieved from "https://c4engine.com/wiki/index.php?title=Command_Console&oldid=531"