Torque Game Engine Documentation
TGE Version 1.5.2

engine/console/console.h File Reference

#include "platform/platform.h"
#include "core/bitSet.h"
#include <stdarg.h>

Namespaces

namespace Con

Data Structures

struct ConsoleLogEntry

Represents an entry in the log. More...

struct EnumTable

Scripting engine representation of an enum. More...

struct EnumTable::Enums

This represents a specific item in the enumeration. More...

class ConsoleConstructor

This is the backend for the ConsoleMethod()/ConsoleFunction() macros. More...

Defines

Global Console Definition Macros

Note:
If TORQUE_DEBUG is defined, then we gather documentation information, and do some extra sanity checks.

See also:
ConsoleConstructor Console Auto-Documentation

#define conmethod_return_const   return (const

#define conmethod_return_S32   return (S32

#define conmethod_return_F32   return (F32

#define conmethod_nullify(val)

#define conmethod_return_void   conmethod_nullify(void

#define conmethod_return_bool   return (bool

#define ConsoleFunctionGroupBegin(groupName, usage)   static ConsoleConstructor gConsoleFunctionGroup##groupName##__GroupBegin(NULL,#groupName,usage);

#define ConsoleFunction(name, returnType, minArgs, maxArgs, usage1)

#define ConsoleFunctionGroupEnd(groupName)   static ConsoleConstructor gConsoleFunctionGroup##groupName##__GroupEnd(NULL,#groupName,NULL);

#define ConsoleMethodGroupBegin(className, groupName, usage)   static ConsoleConstructor className##groupName##__GroupBegin(#className,#groupName,usage);

#define ConsoleMethod(className, name, returnType, minArgs, maxArgs, usage1)

#define ConsoleStaticMethod(className, name, returnType, minArgs, maxArgs, usage1)

#define ConsoleMethodGroupEnd(className, groupName)   static ConsoleConstructor className##groupName##__GroupEnd(#className,#groupName,NULL);

Typedefs

typedef const char * StringTableEntry

typedef const char *(*) StringCallback (SimObject *obj, S32 argc, const char *argv[])

typedef S32(*) IntCallback (SimObject *obj, S32 argc, const char *argv[])

typedef F32(*) FloatCallback (SimObject *obj, S32 argc, const char *argv[])

typedef void(*) VoidCallback (SimObject *obj, S32 argc, const char *argv[])

typedef bool(*) BoolCallback (SimObject *obj, S32 argc, const char *argv[])

typedef void(*) ConsumerCallback (ConsoleLogEntry::Level level, const char *consoleLine)

typedef const char *(*) GetDataFunction (void *dptr, EnumTable *tbl, BitSet32 flag)

typedef void(*) SetDataFunction (void *dptr, S32 argc, const char **argv, EnumTable *tbl, BitSet32 flag)

Enumerations

enum StringTableConstants { StringTagPrefixByte = 0x01 }

enum Con::Constants {
  Con::DSOVersion = 36,
  Con::MaxLineLength = 512,
  Con::MaxDataTypes = 256
}

Various configuration constants. More...

Functions

bool Con::isMainThread ()

Returns true when called from the main thread, false otherwise.

void expandEscape (char *dest, const char *src)

bool collapseEscape (char *buf)

S32 HashPointer (StringTableEntry ptr)

Control Functions

The console must be initialized and shutdown appropriately during the lifetime of the app.
These functions are used to manage this behavior.

Note:
Torque deals with this aspect of console management, so you don't need to call these functions in normal usage of the engine.

void Con::init ()

Initializes the console.

void Con::shutdown ()

Shuts down the console.

bool Con::isActive ()

Is the console active at this time?

Console Consumers

The console distributes its output through Torque by using consumers.
Every time a new line is printed to the console, all the ConsumerCallbacks registered using addConsumer are called, in order.

Note:
The GuiConsole control, which provides the on-screen in-game console, uses a different technique to render the console. It calls getLockLog() to lock the Vector of on-screen console entries, then it renders them as needed. While the Vector is locked, the console will not change the Vector. When the GuiConsole control is done with the console entries, it calls unlockLog() to tell the console that it is again safe to modify the Vector.

See also:
TelnetConsole
TelnetDebugger
WinConsole
MacCarbConsole
StdConsole
ConsoleLogger

void Con::addConsumer (ConsumerCallback cb)

void Con::removeConsumer (ConsumerCallback cb)

Miscellaneous

void Con::stripColorChars (char *line)

Remove color marking information from a string.

bool Con::expandScriptFilename (char *filename, U32 size, const char *src)

Convert from a relative script path to an absolute script path.

bool Con::isFunction (const char *fn)

Returns true if fn is a global scripting function.

U32 Con::tabComplete (char *inputBuffer, U32 cursorPos, U32 maxResultLength, bool forwardTab)

This is the basis for tab completion in the console.

Variable Management

bool Con::addVariable (const char *name, S32 type, void *pointer)

Add a console variable that references the value of a variable in C++ code.

bool Con::removeVariable (const char *name)

Remove a console variable.

void Con::setLocalVariable (const char *name, const char *value)

Assign a string value to a locally scoped console variable.

const char * Con::getLocalVariable (const char *name)

Retrieve the string value to a locally scoped console variable.

Global Variable Accessors

Assign a string value to a global console variable

Parameters:

name Global console variable name to set

value String value to assign to this variable.

void Con::setVariable (const char *name, const char *value)

const char * Con::getVariable (const char *name)

Retrieve the string value of a global console variable.

void Con::setBoolVariable (const char *name, bool var)

Same as setVariable(), but for bools.

bool Con::getBoolVariable (const char *name, bool def=false)

Same as getVariable(), but for bools.

void Con::setIntVariable (const char *name, S32 var)

Same as setVariable(), but for ints.

S32 Con::getIntVariable (const char *name, S32 def=0)

Same as getVariable(), but for ints.

void Con::setFloatVariable (const char *name, F32 var)

Same as setVariable(), but for floats.

F32 Con::getFloatVariable (const char *name, F32 def=.0f)

Same as getVariable(), but for floats.

Global Function Registration

void Con::addCommand (const char *name, StringCallback cb, const char *usage, S32 minArgs, S32 maxArgs)

Register a C++ function with the console making it a global function callable from the scripting engine.

void Con::addCommand (const char *name, IntCallback cb, const char *usage, S32 minArgs, S32 maxArgs)

Register a C++ function with the console making it a global function callable from the scripting engine.

Parameters:

name Name of the new function.

cb Pointer to the function implementing the scripting call; a console callback function returning a specific type value.

usage Documentation for this function. Console Auto-Documentation

minArgs Minimum number of arguments this function accepts

maxArgs Maximum number of arguments this function accepts

void Con::addCommand (const char *name, FloatCallback cb, const char *usage, S32 minArgs, S32 maxArgs)

Register a C++ function with the console making it a global function callable from the scripting engine.

Parameters:

name Name of the new function.

cb Pointer to the function implementing the scripting call; a console callback function returning a specific type value.

usage Documentation for this function. Console Auto-Documentation

minArgs Minimum number of arguments this function accepts

maxArgs Maximum number of arguments this function accepts

void Con::addCommand (const char *name, VoidCallback cb, const char *usage, S32 minArgs, S32 maxArgs)

Register a C++ function with the console making it a global function callable from the scripting engine.

Parameters:

name Name of the new function.

cb Pointer to the function implementing the scripting call; a console callback function returning a specific type value.

usage Documentation for this function. Console Auto-Documentation

minArgs Minimum number of arguments this function accepts

maxArgs Maximum number of arguments this function accepts

void Con::addCommand (const char *name, BoolCallback cb, const char *usage, S32 minArgs, S32 maxArgs)

Register a C++ function with the console making it a global function callable from the scripting engine.

Parameters:

name Name of the new function.

cb Pointer to the function implementing the scripting call; a console callback function returning a specific type value.

usage Documentation for this function. Console Auto-Documentation

minArgs Minimum number of arguments this function accepts

maxArgs Maximum number of arguments this function accepts

Namespace Function Registration

void Con::addCommand (const char *nameSpace, const char *name, StringCallback cb, const char *usage, S32 minArgs, S32 maxArgs)

Register a C++ function with the console making it callable as a method of the given namespace from the scripting engine.

void Con::addCommand (const char *nameSpace, const char *name, IntCallback cb, const char *usage, S32 minArgs, S32 maxArgs)

Register a C++ function with the console making it callable as a method of the given namespace from the scripting engine.

Parameters:

nameSpace Name of the namespace to associate the new function with; this is usually the name of a class.

name Name of the new function.

cb Pointer to the function implementing the scripting call; a console callback function returning a specific type value.

usage Documentation for this function. Console Auto-Documentation

minArgs Minimum number of arguments this function accepts

maxArgs Maximum number of arguments this function accepts

void Con::addCommand (const char *nameSpace, const char *name, FloatCallback cb, const char *usage, S32 minArgs, S32 maxArgs)

Register a C++ function with the console making it callable as a method of the given namespace from the scripting engine.

Parameters:

nameSpace Name of the namespace to associate the new function with; this is usually the name of a class.

name Name of the new function.

cb Pointer to the function implementing the scripting call; a console callback function returning a specific type value.

usage Documentation for this function. Console Auto-Documentation

minArgs Minimum number of arguments this function accepts

maxArgs Maximum number of arguments this function accepts

void Con::addCommand (const char *nameSpace, const char *name, VoidCallback cb, const char *usage, S32 minArgs, S32 maxArgs)

Register a C++ function with the console making it callable as a method of the given namespace from the scripting engine.

Parameters:

nameSpace Name of the namespace to associate the new function with; this is usually the name of a class.

name Name of the new function.

cb Pointer to the function implementing the scripting call; a console callback function returning a specific type value.

usage Documentation for this function. Console Auto-Documentation

minArgs Minimum number of arguments this function accepts

maxArgs Maximum number of arguments this function accepts

void Con::addCommand (const char *nameSpace, const char *name, BoolCallback cb, const char *usage, S32 minArgs, S32 maxArgs)

Register a C++ function with the console making it callable as a method of the given namespace from the scripting engine.

Parameters:

nameSpace Name of the namespace to associate the new function with; this is usually the name of a class.

name Name of the new function.

cb Pointer to the function implementing the scripting call; a console callback function returning a specific type value.

usage Documentation for this function. Console Auto-Documentation

minArgs Minimum number of arguments this function accepts

maxArgs Maximum number of arguments this function accepts

Special Purpose Registration

These are special-purpose functions that exist to allow commands to be grouped, so that when we generate console docs, they can be more meaningfully presented.
Click here for more information about console docs and grouping.

void Con::markCommandGroup (const char *nsName, const char *name, const char *usage=NULL)

void Con::beginCommandGroup (const char *nsName, const char *name, const char *usage)

void Con::endCommandGroup (const char *nsName, const char *name)

void Con::addOverload (const char *nsName, const char *name, const char *altUsage)

Console Output

These functions process the formatted string and pass it to all the ConsumerCallbacks that are currently registered.
The console log file and the console window callbacks are installed by default.

See also:
addConsumer()
removeConsumer()

void Con::printf (const char *_format,...)

Parameters:

_format A stdlib printf style formatted out put string

void Con::warnf (const char *_format,...)

Note:
The console window colors warning text as LIGHT GRAY.

void Con::errorf (const char *_format,...)

Note:
The console window colors warning text as RED.

void Con::warnf (ConsoleLogEntry::Type type, const char *_format,...)

Note:
The console window colors warning text as LIGHT GRAY.

void Con::errorf (ConsoleLogEntry::Type type, const char *_format,...)

Note:
The console window colors warning text as RED.

Console Execution

These are functions relating to the execution of script code.

const char * Con::execute (S32 argc, const char *argv[])

Call a script function from C/C++ code.

const char * Con::executef (S32 argc,...)

See also:
execute(S32 argc, const char* argv[])

const char * Con::execute (SimObject *object, S32 argc, const char *argv[])

Call a Torque Script member function of a SimObject from C/C++ code.

const char * Con::executef (SimObject *, S32 argc,...)

See also:
execute(SimObject *, S32 argc, const char *argv[])

const char * Con::evaluate (const char *string, bool echo=false, const char *fileName=NULL)

Evaluate an arbitrary chunk of code.

const char * Con::evaluatef (const char *string,...)

Evaluate an arbitrary line of script.

Console Function Implementation Helpers

The functions Con::getIntArg, Con::getFloatArg and Con::getArgBuffer(size) are used to allocate on the console stack string variables that will be passed into the next console

char * Con::getReturnBuffer (U32 bufferSize)

char * Con::getArgBuffer (U32 bufferSize)

char * Con::getFloatArg (F64 arg)

char * Con::getIntArg (S32 arg)

Namespaces

Namespace * Con::lookupNamespace (const char *nsName)

bool Con::linkNamespaces (const char *parentName, const char *childName)

bool Con::unlinkNamespaces (const char *parentName, const char *childName)

bool Con::classLinkNamespaces (Namespace *parent, Namespace *child)

Note:
This should only be called from consoleObject.h

Logging

void Con::getLockLog (ConsoleLogEntry *&log, U32 &size)

void Con::unlockLog (void)

void Con::setLogMode (S32 mode)

Dynamic Type System

void Con::setData (S32 type, void *dptr, S32 index, S32 argc, const char **argv, EnumTable *tbl=NULL, BitSet32 flag=0)

const char * Con::getData (S32 type, void *dptr, S32 index, EnumTable *tbl=NULL, BitSet32 flag=0)

Variables

bool gWarnUndefinedScriptVariables

Indicates that warnings about undefined script variables should be displayed.

Define Documentation

#define conmethod_return_const return (const

#define conmethod_return_S32 return (S32

#define conmethod_return_F32 return (F32

#define conmethod_nullify ( val )

#define conmethod_return_void conmethod_nullify(void

#define conmethod_return_bool return (bool

#define ConsoleFunctionGroupBegin	(	groupName,
		usage		)	static ConsoleConstructor gConsoleFunctionGroup##groupName##__GroupBegin(NULL,#groupName,usage);

#define ConsoleFunction	(	name,
		returnType,
		minArgs,
		maxArgs,
		usage1	)

Value:

static returnType c##name(SimObject *, S32, const char **argv);                     \
      static ConsoleConstructor g##name##obj(NULL,#name,c##name,usage1,minArgs,maxArgs);  \
      static returnType c##name(SimObject *, S32 argc, const char **argv)

#define ConsoleFunctionGroupEnd ( groupName ) static ConsoleConstructor gConsoleFunctionGroup##groupName##__GroupEnd(NULL,#groupName,NULL);

#define ConsoleMethodGroupBegin	(	className,
		groupName,
		usage	)	static ConsoleConstructor className##groupName##__GroupBegin(#className,#groupName,usage);

#define ConsoleMethod	(	className,
		name,
		returnType,
		minArgs,
		maxArgs,
		usage1	)

Value:

static inline returnType c##className##name(className *, S32, const char **argv);               \
      static returnType c##className##name##caster(SimObject *object, S32 argc, const char **argv) {  \
         AssertFatal( dynamic_cast<className*>( object ), "Object passed to " #name " is not a " #className "!" ); \
         conmethod_return_##returnType ) c##className##name(static_cast<className*>(object),argc,argv);              \
      };                                                                                              \
      static ConsoleConstructor className##name##obj(#className,#name,c##className##name##caster,usage1,minArgs,maxArgs); \
      static inline returnType c##className##name(className *object, S32 argc, const char **argv)

#define ConsoleStaticMethod	(	className,
		name,
		returnType,
		minArgs,
		maxArgs,
		usage1	)

Value:

static inline returnType c##className##name(S32, const char **);                                \
      static returnType c##className##name##caster(SimObject *object, S32 argc, const char **argv) {  \
         conmethod_return_##returnType ) c##className##name(argc,argv);                                \
      };                                                                                              \
      static ConsoleConstructor                                                                       \
         className##name##obj(#className,#name,c##className##name##caster,usage1,minArgs,maxArgs);    \
      static inline returnType c##className##name(S32 argc, const char **argv)

#define ConsoleMethodGroupEnd	(	className,
		groupName		)	static ConsoleConstructor className##groupName##__GroupEnd(#className,#groupName,NULL);

Typedef Documentation

typedef const char* StringTableEntry

Enumeration Type Documentation

enum StringTableConstants

Enumerator:

StringTagPrefixByte

Magic value prefixed to tagged strings.

Function Documentation

void expandEscape	(	char *	dest,
		const char *	src
	)

bool collapseEscape ( char * buf )

S32 HashPointer ( StringTableEntry ptr )

Variable Documentation

bool gWarnUndefinedScriptVariables

Indicates that warnings about undefined script variables should be displayed.

Note:: This is set and controlled by script.