Torque2D Reference
Classes | Typedefs | Enumerations | Functions
Con Namespace Reference

Classes

class  ConPrinfThreadedEvent
 

Typedefs

typedef HashMap< StringTableEntry, StringTableEntry > typePathExpandoMap
 

Enumerations

enum  Constants { DSOVersion = 44, MaxLineLength = 512, MaxDataTypes = 256 }
 Various configuration constants. More...
 

Functions

bool isMainThread ()
 Returns true when called from the main thread, false otherwise. More...
 
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 * getReturnBuffer (U32 bufferSize)
 
char * getReturnBuffer (const char *stringToCopy)
 
char * getArgBuffer (U32 bufferSize)
 
char * getFloatArg (F64 arg)
 
char * getIntArg (S32 arg)
 
char * getBoolArg (bool arg)
 
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 init ()
 
void shutdown ()
 
bool isActive ()
 Is the console active at this time? More...
 
Logging
void getLockLog (ConsoleLogEntry *&log, U32 &size)
 
void unlockLog ()
 
void setLogMode (S32 newMode)
 
Miscellaneous
U32 tabComplete (char *inputBuffer, U32 cursorPos, U32 maxResultLength, bool forwardTab)
 
void stripColorChars (char *line)
 
bool isFunction (const char *fn)
 
StringTableEntry getModNameFromPath (const char *path)
 
void addPathExpando (const char *pExpandoName, const char *pPath)
 
StringTableEntry getPathExpando (const char *pExpandoName)
 
void removePathExpando (const char *pExpandoName)
 
bool isPathExpando (const char *pExpandoName)
 
U32 getPathExpandoCount (void)
 
StringTableEntry getPathExpandoKey (U32 expandoIndex)
 
StringTableEntry getPathExpandoValue (U32 expandoIndex)
 
bool expandPath (char *pDstPath, U32 size, const char *pSrcPath, const char *pWorkingDirectoryHint, const bool ensureTrailingSlash)
 
bool isBasePath (const char *SrcPath, const char *pBasePath)
 
void collapsePath (char *pDstPath, U32 size, const char *pSrcPath, const char *pWorkingDirectoryHint)
 
void ensureTrailingSlash (char *pDstPath, const char *pSrcPath)
 
bool stripRepeatSlashes (char *pDstPath, const char *pSrcPath, S32 dstSize)
 
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 cls (void)
 clear the console log More...
 
void printf (const char *fmt,...)
 
void warnf (ConsoleLogEntry::Type type, const char *fmt,...)
 
void errorf (ConsoleLogEntry::Type type, const char *fmt,...)
 
void warnf (const char *fmt,...)
 
void errorf (const char *fmt,...)
 
void printSeparator (void)
 Prints a separator to the console. More...
 
void printBlankLine (void)
 Prints a separator to the console. More...
 
Global Variable Accessors

Assign a string value to a global console variable

Parameters
nameGlobal console variable name to set
valueString value to assign to this variable.
void setVariable (const char *name, const char *value)
 
void setBoolVariable (const char *name, bool var)
 Same as setVariable(), but for bools. More...
 
void setIntVariable (const char *name, S32 var)
 Same as setVariable(), but for ints. More...
 
void setFloatVariable (const char *name, F32 var)
 Same as setVariable(), but for floats. More...
 
const char * getVariable (const char *name)
 
bool getBoolVariable (const char *varName, bool def)
 
S32 getIntVariable (const char *varName, S32 def)
 
F32 getFloatVariable (const char *varName, F32 def)
 
Variable Management
void setLocalVariable (const char *name, const char *value)
 
const char * getLocalVariable (const char *name)
 
bool addVariable (const char *name, S32 t, void *dp)
 
bool removeVariable (const char *name)
 
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
iPhoneConsole
StdConsole
ConsoleLogger
void addConsumer (ConsumerCallback consumer)
 
void removeConsumer (ConsumerCallback consumer)
 
Namespace Function Registration
void addCommand (const char *nsName, const char *name, StringCallback cb, const char *usage, S32 minArgs, S32 maxArgs)
 
void addCommand (const char *nameSpace, const char *name, VoidCallback cb, const char *usage, S32 minArgs, S32 maxArgs)
 
void addCommand (const char *nameSpace, const char *name, IntCallback cb, const char *usage, S32 minArgs, S32 maxArgs)
 
void addCommand (const char *nameSpace, const char *name, FloatCallback cb, const char *usage, S32 minArgs, S32 maxArgs)
 
void addCommand (const char *nameSpace, const char *name, BoolCallback cb, const char *usage, S32 minArgs, S32 maxArgs)
 
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)
 
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)
 
Global Function Registration
void addCommand (const char *name, StringCallback cb, const char *usage, S32 minArgs, S32 maxArgs)
 
void addCommand (const char *name, VoidCallback cb, const char *usage, S32 minArgs, S32 maxArgs)
 
void addCommand (const char *name, IntCallback cb, const char *usage, S32 minArgs, S32 maxArg)
 
void addCommand (const char *name, FloatCallback cb, const char *usage, S32 minArgs, S32 maxArgs)
 
void addCommand (const char *name, BoolCallback cb, const char *usage, S32 minArgs, S32 maxArgs)
 
Console Execution

These are functions relating to the execution of script code.

const char * evaluate (const char *string, bool echo, const char *fileName)
 
const char * evaluatef (const char *string,...)
 
const char * execute (S32 argc, const char *argv[])
 
const char * execute (SimObject *object, S32 argc, const char *argv[], bool thisCallOnly)
 
const char * executef (SimObject *object, S32 argc,...)
 
const char * executef (S32 argc,...)
 
Namespaces
NamespacelookupNamespace (const char *ns)
 
bool linkNamespaces (const char *parent, const char *child)
 
bool unlinkNamespaces (const char *parent, const char *child)
 
bool classLinkNamespaces (Namespace *parent, Namespace *child)
 
Dynamic Type System
void setData (S32 type, void *dptr, S32 index, S32 argc, const char **argv, EnumTable *tbl, BitSet32 flag)
 
const char * getData (S32 type, void *dptr, S32 index, EnumTable *tbl, BitSet32 flag)
 

Variables

StringTableEntry gCurrentFile
 
StringTableEntry gCurrentRoot
 

Detailed Description

This namespace contains the core of the console functionality.

Introduction

The console is a key part of Torque's architecture. It allows direct run-time control of many aspects of the engine.

Typedef Documentation

typedef HashMap<StringTableEntry, StringTableEntry> typePathExpandoMap

Enumeration Type Documentation

enum Constants

Various configuration constants.

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

  12/29/04 - BJG - 33->34 Removed some opcodes, part of namespace upgrade.
  12/30/04 - BJG - 34->35 Reordered some things, further general shuffling.
  11/03/05 - BJG - 35->36 Integrated new debugger code.  
MaxLineLength 

Maximum length of a line of console input.

MaxDataTypes 

Maximum number of registered data types.

Function Documentation

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.

Parameters
nameSpaceName of the namespace to associate the new function with; this is usually the name of a class.
nameName of the new function.
cbPointer to the function implementing the scripting call; a console callback function returning a specific type value.
usageDocumentation for this function. Console Auto-Documentation
minArgsMinimum number of arguments this function accepts
maxArgsMaximum number of arguments this function accepts
void 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
nameSpaceName of the namespace to associate the new function with; this is usually the name of a class.
nameName of the new function.
cbPointer to the function implementing the scripting call; a console callback function returning a specific type value.
usageDocumentation for this function. Console Auto-Documentation
minArgsMinimum number of arguments this function accepts
maxArgsMaximum number of arguments this function accepts
void 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
nameSpaceName of the namespace to associate the new function with; this is usually the name of a class.
nameName of the new function.
cbPointer to the function implementing the scripting call; a console callback function returning a specific type value.
usageDocumentation for this function. Console Auto-Documentation
minArgsMinimum number of arguments this function accepts
maxArgsMaximum number of arguments this function accepts
void 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
nameSpaceName of the namespace to associate the new function with; this is usually the name of a class.
nameName of the new function.
cbPointer to the function implementing the scripting call; a console callback function returning a specific type value.
usageDocumentation for this function. Console Auto-Documentation
minArgsMinimum number of arguments this function accepts
maxArgsMaximum number of arguments this function accepts
void 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
nameSpaceName of the namespace to associate the new function with; this is usually the name of a class.
nameName of the new function.
cbPointer to the function implementing the scripting call; a console callback function returning a specific type value.
usageDocumentation for this function. Console Auto-Documentation
minArgsMinimum number of arguments this function accepts
maxArgsMaximum number of arguments this function accepts
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.

Parameters
nameName of the new function.
cbPointer to the function implementing the scripting call; a console callback function returning a specific type value.
usageDocumentation for this function. Console Auto-Documentation
minArgsMinimum number of arguments this function accepts
maxArgsMaximum number of arguments this function accepts
void 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
nameName of the new function.
cbPointer to the function implementing the scripting call; a console callback function returning a specific type value.
usageDocumentation for this function. Console Auto-Documentation
minArgsMinimum number of arguments this function accepts
maxArgsMaximum number of arguments this function accepts
void addCommand ( const char *  name,
IntCallback  cb,
const char *  usage,
S32  minArgs,
S32  maxArg 
)

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

Parameters
nameName of the new function.
cbPointer to the function implementing the scripting call; a console callback function returning a specific type value.
usageDocumentation for this function. Console Auto-Documentation
minArgsMinimum number of arguments this function accepts
maxArgsMaximum number of arguments this function accepts
void 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
nameName of the new function.
cbPointer to the function implementing the scripting call; a console callback function returning a specific type value.
usageDocumentation for this function. Console Auto-Documentation
minArgsMinimum number of arguments this function accepts
maxArgsMaximum number of arguments this function accepts
void 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
nameName of the new function.
cbPointer to the function implementing the scripting call; a console callback function returning a specific type value.
usageDocumentation for this function. Console Auto-Documentation
minArgsMinimum number of arguments this function accepts
maxArgsMaximum number of arguments this function accepts
void addConsumer ( ConsumerCallback  consumer)
void addOverload ( const char *  nsName,
const char *  name,
const char *  altUsage 
)
void addPathExpando ( const char *  pExpandoName,
const char *  pPath 
)
bool 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
nameGlobal console variable name to create
typeThe type of the C++ variable; see the ConsoleDynamicTypes enum for a complete list.
pointerPointer to the variable.
See also
ConsoleDynamicTypes
void beginCommandGroup ( const char *  nsName,
const char *  name,
const char *  usage 
)
bool classLinkNamespaces ( Namespace parent,
Namespace child 
)
Note
This should only be called from consoleObject.h
void cls ( void  )

clear the console log

void collapsePath ( char *  pDstPath,
U32  size,
const char *  pSrcPath,
const char *  pWorkingDirectoryHint 
)
void endCommandGroup ( const char *  nsName,
const char *  name 
)
void ensureTrailingSlash ( char *  pDstPath,
const char *  pSrcPath 
)
void errorf ( ConsoleLogEntry::Type  type,
const char *  _format,
  ... 
)
Note
The console window colors warning text as RED.
Parameters
typeAllows you to associate the warning message with an internal module.
_formatA stdlib printf style formatted out put string
...Variables to be written
See also
Con::errorf()
void errorf ( const char *  _format,
  ... 
)
Note
The console window colors warning text as RED.
Parameters
_formatA stdlib printf style formatted out put string
...Variables to be written
const char * evaluate ( const char *  string,
bool  echo = false,
const char *  fileName = NULL 
)

Evaluate an arbitrary chunk of code.

Parameters
stringBuffer containing code to execute.
echoShould we echo the string to the console?
fileNameIndicate what file this code is coming from; used in error reporting and such.
const char * evaluatef ( const char *  string,
  ... 
)

Evaluate an arbitrary line of script.

This wraps dVsprintf(), so you can substitute parameters into the code being executed.

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

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

Parameters
argcNumber of elements in the argv parameter
argvA character string array containing the name of the function to call followed by the arguments to that function.
// Call a Torque script function called mAbs, having one parameter.
char* argv[] = {"abs", "-9"};
char* result = execute(2, argv);
const char * execute ( SimObject object,
S32  argc,
const char *  argv[],
bool  thisCallOnly = false 
)

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

Parameters
objectObject on which to execute the method call.
argcNumber of elements in the argv parameter (must be >2, see argv)
argvA character string array containing the name of the member function to call followed by an empty parameter (gets filled with object ID) followed by arguments to that function.
// Call the method setMode() on an object, passing it one parameter.
char* argv[] = {"setMode", "", "2"};
char* result = execute(mysimobject, 3, argv);
const char * executef ( SimObject ,
S32  argc,
  ... 
)
See also
execute(SimObject *, S32 argc, const char *argv[])
const char * executef ( S32  argc,
  ... 
)
bool expandPath ( char *  pDstPath,
U32  size,
const char *  pSrcPath,
const char *  pWorkingDirectoryHint = NULL,
const bool  ensureTrailingSlash = false 
)

Convert from a relative path to an absolute 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.
  • Expando: ^Project/image/happy.png Paths of this sort are relative to the path defined by the expando, in this case the "Project" expando.
Parameters
pDstPathPointer to string buffer to fill with absolute path.
sizeSize of buffer pointed to by pDstPath.
pSrcPathOriginal, possibly relative path.
char * getArgBuffer ( U32  bufferSize)
char * getBoolArg ( bool  arg)
bool getBoolVariable ( const char *  name,
bool  def = false 
)

Same as getVariable(), but for bools.

Parameters
nameName of the variable.
defDefault value to supply if no matching variable is found.
const char * getData ( S32  type,
void *  dptr,
S32  index,
EnumTable tbl,
BitSet32  flag 
)
char * getFloatArg ( F64  arg)
F32 getFloatVariable ( const char *  name,
F32  def = .0f 
)

Same as getVariable(), but for floats.

Parameters
nameName of the variable.
defDefault value to supply if no matching variable is found.
char * getIntArg ( S32  arg)
S32 getIntVariable ( const char *  name,
S32  def = 0 
)

Same as getVariable(), but for ints.

Parameters
nameName of the variable.
defDefault value to supply if no matching variable is found.
const char * 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
nameLocal console variable name to get
void getLockLog ( ConsoleLogEntry *&  log,
U32 &  size 
)
StringTableEntry getModNameFromPath ( const char *  path)
StringTableEntry getPathExpando ( const char *  pExpandoName)
U32 getPathExpandoCount ( void  )
StringTableEntry getPathExpandoKey ( U32  expandoIndex)
StringTableEntry getPathExpandoValue ( U32  expandoIndex)
char * getReturnBuffer ( U32  bufferSize)

getReturnBuffer lets you allocate stack space to return data in.

char * getReturnBuffer ( const char *  stringToCopy)
const char * getVariable ( const char *  name)

Retrieve the string value of a global console variable

Parameters
nameGlobal Console variable name to query
Returns
The string value of the variable or "" if the variable does not exist.
void 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.
bool isActive ( )

Is the console active at this time?

bool isBasePath ( const char *  SrcPath,
const char *  pBasePath 
)
bool 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.

bool isMainThread ( )

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

bool isPathExpando ( const char *  pExpandoName)
bool linkNamespaces ( const char *  parent,
const char *  child 
)
Namespace * lookupNamespace ( const char *  ns)
void markCommandGroup ( const char *  nsName,
const char *  name,
const char *  usage 
)
void Con::printBlankLine ( void  )
inline

Prints a separator to the console.

void printf ( const char *  _format,
  ... 
)
Parameters
_formatA stdlib printf style formatted out put string
...Variables to be written
void Con::printSeparator ( void  )
inline

Prints a separator to the console.

void removeConsumer ( ConsumerCallback  consumer)
void removePathExpando ( const char *  pExpandoName)
bool removeVariable ( const char *  name)

Remove a console variable.

Parameters
nameGlobal console variable name to remove
Returns
true if variable existed before removal.
void setBoolVariable ( const char *  varName,
bool  value 
)

Same as setVariable(), but for bools.

void setData ( S32  type,
void *  dptr,
S32  index,
S32  argc,
const char **  argv,
EnumTable tbl,
BitSet32  flag 
)
void setFloatVariable ( const char *  varName,
F32  value 
)

Same as setVariable(), but for floats.

void setIntVariable ( const char *  varName,
S32  value 
)

Same as setVariable(), but for ints.

void 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
nameLocal console variable name to set
valueString value to assign to name
void setLogMode ( S32  newMode)
void setVariable ( const char *  name,
const char *  value 
)
void 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.
void 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 stripRepeatSlashes ( char *  pDstPath,
const char *  pSrcPath,
S32  dstSize 
)
U32 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
inputBufferPointer to buffer containing starting data, or last result.
cursorPosLocation 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.
maxResultLengthMaximum amount of result data to put into inputBuffer. This is capped by MaxCompletionBufferSize.
forwardTabShould we go forward to next match or backwards to previous match? True indicates forward.
bool unlinkNamespaces ( const char *  parent,
const char *  child 
)
void unlockLog ( )
void warnf ( ConsoleLogEntry::Type  type,
const char *  _format,
  ... 
)
Note
The console window colors warning text as LIGHT GRAY.
Parameters
typeAllows you to associate the warning message with an internal module.
_formatA stdlib printf style formatted out put string
...Variables to be written
See also
Con::warnf()
void warnf ( const char *  _format,
  ... 
)
Note
The console window colors warning text as LIGHT GRAY.
Parameters
_formatA stdlib printf style formatted out put string
...Variables to be written

Variable Documentation

StringTableEntry gCurrentFile

Current script file name and root, these are registered as console variables.

StringTableEntry gCurrentRoot