Command Console

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.
target type	(Advanced) Opens the Target window, which displays one of the offscreen render targets. The value of type can be one of the following: strc – linear depth in structure buffer grad – gradient in structure buffer occl – ambient occlusion buffer dist – distortion buffer velo – velocity buffer atms – atmospheric shadowing buffer glbl – glow/bloom buffer
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.)
tone	(Advanced) Opens the Tone Mapping window, which displays a luminance histogram and tone mapping curve.
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

• C4 Menu
• List of System Variables