Command Console Legacy

This is legacy documentation

Current Wiki index can be found here

To facilitate updating of xygine properties at runtime, xygine implements a console which can be opened by pressing F1. The console outputs messages reported by the Logger class, and allows input of commands to xygine. By default there are only a few commands registered with the console, which can be listed with the command list_all. The power of the console comes from its ability to allow registering custom commands via callbacks, written in code. For example the Scene class registers a command "r_drawDebug" which accepts a boolean value that turns on or off the debug display output when a Scene object is active:

xy::Console::addCommand("r_drawDebug",
    [this](const std::string& params)
{
    if (params.find_first_of('0') == 0 ||
        params.find_first_of("false") == 0)
    {
        drawDebug(false);
    }
    else if (params.find_first_of('1') == 0 ||
        params.find_first_of("true") == 0)
    {
        drawDebug(true);
    }
    else
    {
        xy::Console::print("r_drawDebug: valid parameters are 0, 1, false or true");
    }

}, this);

The functions in the Console class are static so may be accessed anywhere Console.hpp is included. addCommand() accepts three parameters: a string which will become the command typed into the console, a std::function to act as the callback executed when the command is entered, and an optional void pointer. The callback signature is as follows:

void callback(const std::string& params);

The string passed in as 'params' is the remaining input of the console buffer after the entered command. For example opening the console and typing 'r_drawDebug true' will pass the string 'true' in to the callback. How these parameters are handled is up to the author of the callback. In this example the string is checked for 'true' or 'false' and the Scene::drawDebug() function is called appropriately. Unknown or invalid strings respond with a short message explaining the use of the command.

It may be obvious from the example that the lambda expression used captures the this pointer of the current Scene instance. When doing this it's important to note that when the particular instance of the scene is destroyed this callback will become invalid, but the command will remain registered with the Console class. Executing a command with an invalid callback will result in undefined behaviour. This is why the addCommand() function takes an optional third parameter, a void pointer, which can be used to associate an instance of an object which registers a command, by passing in the this pointer. Objects which do this can then call Console::unregisterCommand() in the destructor, once again passing in the this pointer, to let the console know the object is being destroyed and that any commands it had registered should now be removed. This can be seen in the Scene class's destructor. These steps are unnecessary for objects which live at least as long as the running console. As commands can be registered and unregistered at any time the list_all command will return different results depending on the currently registered commands. This can be seen in the example application by typing list_all first on the main menu, and again by entering it during the Platform Demo. The MeshRenderer used by the demonstration registers its own debug commands, and removes them again when the Platform Demo is exited.

Scripting

Rudimentary scripting can be performed by the console with the 'exec' command. Typing 'exec' followed by the name of a text file containing a list of valid console commands will cause xygine to attempt to open the file and execute each command, one at a time. All console commands are valid except 'exec' itself, and comments may be inserted using the usual c-style double slash format. This can be useful for games which load configurable data on start up, such as key bindings.