torque Torque Game Engine Documentation
CVS Revision Label 1.3.x
Torque Home   Class Hierarchy   Data Structures   Namespaces   Namespace Members   File List   Globals
engine / console

console.h File Reference

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

Namespaces

namespace  Con

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

Control Functions

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

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 init ()
 Initializes the console.
void shutdown ()
 Shuts down the console.
bool 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 getLog() to get the on-screen console entries, then renders them as needed.
See also:
TelnetConsole

TelnetDebugger

WinConsole

MacCarbConsole

StdConsole

ConsoleLogger



void addConsumer (ConsumerCallback cb)
void removeConsumer (ConsumerCallback cb)

Miscellaneous

void stripColorChars (char *line)
 Remove color marking information from a string.
bool expandScriptFilename (char *filename, U32 size, const char *src)
 Convert from a relative script path to an absolute script path.
bool isFunction (const char *fn)
 Returns true if fn is a global scripting function.
U32 tabComplete (char *inputBuffer, U32 cursorPos, U32 maxResultLength, bool forwardTab)
 This is the basis for tab completion in the console.

Variable Management

bool addVariable (const char *name, S32 type, void *pointer)
 Add a console variable that references the value of a variable in C++ code.
bool removeVariable (const char *name)
 Remove a console variable.
void setLocalVariable (const char *name, const char *value)
 Assign a string value to a locally scoped console variable.
const char * 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 setVariable (const char *name, const char *value)
const char * getVariable (const char *name)
 Retrieve the string value of a global console variable.
void setBoolVariable (const char *name, bool var)
 Same as setVariable(), but for bools.
bool getBoolVariable (const char *name, bool def=false)
 Same as getVariable(), but for bools.
void setIntVariable (const char *name, S32 var)
 Same as setVariable(), but for ints.
S32 getIntVariable (const char *name, S32 def=0)
 Same as getVariable(), but for ints.
void setFloatVariable (const char *name, F32 var)
 Same as setVariable(), but for floats.
F32 getFloatVariable (const char *name, F32 def=.0f)
 Same as getVariable(), but for floats.

Global Function Registration

void 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 addCommand (const char *name, IntCallback cb, const char *usage, S32 minArgs, S32 maxArgs)
 
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 addCommand (const char *name, FloatCallback cb, const char *usage, S32 minArgs, S32 maxArgs)
 
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 addCommand (const char *name, VoidCallback cb, const char *usage, S32 minArgs, S32 maxArgs)
 
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 addCommand (const char *name, BoolCallback cb, const char *usage, S32 minArgs, S32 maxArgs)
 
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 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 addCommand (const char *nameSpace, const char *name, IntCallback cb, const char *usage, S32 minArgs, S32 maxArgs)
 
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 addCommand (const char *nameSpace, const char *name, FloatCallback cb, const char *usage, S32 minArgs, S32 maxArgs)
 
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 addCommand (const char *nameSpace, const char *name, VoidCallback cb, const char *usage, S32 minArgs, S32 maxArgs)
 
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 addCommand (const char *nameSpace, const char *name, BoolCallback cb, const char *usage, S32 minArgs, S32 maxArgs)
 
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 markCommandGroup (const char *nsName, const char *name, const char *usage=NULL)
void beginCommandGroup (const char *nsName, const char *name, const char *usage)
void endCommandGroup (const char *nsName, const char *name)
void 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 printf (const char *_format,...)
void warnf (const char *_format,...)
void errorf (const char *_format,...)
void warnf (ConsoleLogEntry::Type type, const char *_format,...)
void errorf (ConsoleLogEntry::Type type, const char *_format,...)

Console Execution

These are functions relating to the execution of script code.

const char * execute (S32 argc, const char *argv[])
 Call a script function from C/C++ code.
const char * executef (S32 argc,...)
const char * execute (SimObject *object, S32 argc, const char *argv[])
 Call a Torque Script member function of a SimObject from C/C++ code.
const char * executef (SimObject *, S32 argc,...)
const char * evaluate (const char *string, bool echo=false, const char *fileName=NULL)
 Evaluate an arbitrary chunk of code.
const char * evaluatef (const char *string,...)
 Evaluate an arbitrary line of script.

Namespaces

Namespace * lookupNamespace (const char *nsName)
bool linkNamespaces (const char *parentName, const char *childName)
bool classLinkNamespaces (Namespace *parent, Namespace *child)

Logging

void getLog (ConsoleLogEntry *&log, U32 &size)
void setLogMode (S32 mode)

Dynamic Types

void registerType (const char *typeName, S32 type, S32 size, GetDataFunction gdf, SetDataFunction sdf)
const char * getTypeName (S32 type)
void setData (S32 type, void *dptr, S32 index, S32 argc, const char **argv, EnumTable *tbl=NULL, BitSet32 flag=0)
const char * getData (S32 type, void *dptr, S32 index, EnumTable *tbl=NULL, BitSet32 flag=0)

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  Constants {
  DSOVersion = 33,
  MaxLineLength = 512,
  MaxDataTypes = 256
}
 Various configuration constants. More...

Functions

char * getReturnBuffer (U32 bufferSize)
 getReturnBuffer lets you allocate stack space to return data in.
char * getArgBuffer (U32 bufferSize)
char * getFloatArg (F64 arg)
char * getIntArg (S32 arg)
void expandEscape (char *dest, const char *src)
bool collapseEscape (char *buf)
S32 HashPointer (StringTableEntry ptr)

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
 

Enumeration values:
StringTagPrefixByte  Magic value prefixed to tagged strings.

enum Con::Constants
 

Various configuration constants.

Enumeration values:
DSOVersion  This is the version number associated with DSO files.

If you make any changes to the way the scripting language works (such as DSO format changes, adding/removing op-codes) that would break compatibility, then you should increment this.

If you make a really major change, increment it to the next multiple of ten.

MaxLineLength  Maximum length of a line of console input.
MaxDataTypes  Maximum number of registereed data types.

Function Documentation

void Con::init (   ) 
 

Initializes the console.

This performs the following steps:

  • Calls Namespace::init() to initialize the scripting namespace hierarchy.
  • Calls ConsoleConstructor::setup() to initialize globally defined console methods and functions.
  • Registers some basic global script variables.
  • Calls AbstractClassRep::init() to initialize Torque's class database.
  • Registers some basic global script functions that couldn't usefully be defined anywhere else.

void Con::shutdown (   ) 
 

Shuts down the console.

This performs the following steps:

  • Closes the console log file.
  • Calls Namespace::shutdown() to shut down the scripting namespace hierarchy.

bool Con::isActive (   ) 
 

Is the console active at this time?

void Con::addConsumer (  ConsumerCallback  cb  ) 
 

void Con::removeConsumer (  ConsumerCallback  cb  ) 
 

void Con::stripColorChars (  char *  line  ) 
 

Remove color marking information from a string.

Note:
It does this in-place, so be careful! It may potentially blast data if you're not careful. When in doubt, make a copy of the string first.

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

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

This is used in (among other places) the exec() script function, which takes a parameter indicating a script file and executes it. Script paths can be one of:

  • Absolute: fps/foo/bar.cs Paths of this sort are passed through.
  • Mod-relative: ~/foo/bar.cs Paths of this sort have their replaced with the name of the current mod.
  • File-relative: ./baz/blip.cs Paths of this sort are calculated relative to the path of the current scripting file.

Note:
This function determines paths relative to the currently executing CodeBlock. Calling it outside of script execution will result in it directly copying src to filename, since it won't know to what the path is relative!
Parameters:
filename Pointer to string buffer to fill with absolute path.
size Size of buffer pointed to by filename.
src Original, possibly relative script path.

bool Con::isFunction (  const char *  fn  ) 
 

Returns true if fn is a global scripting function.

This looks in the global namespace. It also checks to see if fn is in the StringTable; if not, it returns false.

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

This is the basis for tab completion in the console.

Note:
This is an internally used function. You probably don't care much about how this works.
This function does some basic parsing to try to ascertain the namespace in which we are attempting to do tab completion, then bumps control off to the appropriate tabComplete function, either in SimObject or Namespace.

Parameters:
inputBuffer Pointer to buffer containing starting data, or last result.
cursorPos Location of cursor in this buffer. This is used to indicate what part of the string should be kept and what part should be advanced to the next match if any.
maxResultLength Maximum amount of result data to put into inputBuffer. This is capped by MaxCompletionBufferSize.
forwardTab Should we go forward to next match or backwards to previous match? True indicates forward.

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

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

If a value is assigned to the console variable the C++ variable is updated, and vice-versa.

Parameters:
name Global console variable name to create
type The type of the C++ variable; see the ConsoleDynamicTypes enum for a complete list.
pointer Pointer to the variable.
See also:
ConsoleDynamicTypes

bool Con::removeVariable (  const char *  name  ) 
 

Remove a console variable.

Parameters:
name Global console variable name to remove
Returns:
true if variable existed before removal.

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

Assign a string value to a locally scoped console variable.

Note:
The context of the variable is determined by gEvalState; that is, by the currently executing code.
Parameters:
name Local console variable name to set
value String value to assign to name

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

Retrieve the string value to a locally scoped console variable.

Note:
The context of the variable is determined by gEvalState; that is, by the currently executing code.
Parameters:
name Local console variable name to get

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.

Parameters:
name Global Console variable name to query
Returns:
The string value of the variable or "" if the variable does not exist.

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.

Parameters:
name Name of the variable.
def Default value to supply if no matching variable is found.

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.

Parameters:
name Name of the variable.
def Default value to supply if no matching variable is found.

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.

Parameters:
name Name of the variable.
def Default value to supply if no matching variable is found.

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.

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,
IntCallback  cb,
const char *  usage,
S32  minArgs,
S32  maxArgs
) 
 

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
) 
 

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
) 
 

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
) 
 

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

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,
IntCallback  cb,
const char *  usage,
S32  minArgs,
S32  maxArgs
) 
 

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
) 
 

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
) 
 

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
) 
 

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