Contents

Engine Interfacing

The engine provides a powerful set of tools to expose the core engine functionality and structures in the console (to TorqueScript). In addition, usage of these console functions and classes sometimes involves enumerated types. The following problem-solution matrix summarizes tasks relating to the Console and how to accomplish them.


Need to… Solution
Expose Member as Field. addField()
addFieldV()
Expose named Member as Field. addNamedField()
addNamedFieldV()
Expose/Remove global C++ Variable or static Member as Local Variable Con::addVariable()
Con::removeVariable()
Create Console Function from C++ ConsoleFunction()
Create a Console Class's Method from C++. ConsoleMethod()
Create a Console Class from C++ IMPLEMENT_CONOBJECT()
Create a Console Datablock from C++ IMPLEMENT_CO_DATABLOCK()
Invoke a Console Callback Method from C++ Con::executef( this, ... )
Invoke a Console Callback Function from C++ Con::executef( ... )
Create a Enumerated Data Type from C++ EnumTable::Enums


addField

Purpose Provides a means to expose C++ class members as TorqueScript object fields. This function is normally called in a class’ initPersistFields() method.

Syntax

addField(
const char * in_pFieldname ,
const U32in_fieldType,
const dsize_tin_fieldOffset,
const char *in_pFieldDocs,
)


addField(
const char * in_pFieldname ,
const U32in_fieldType,
const dsize_tin_fieldOffset,
const U32 in_elementCount,
EnumTable *in_table,
const char *in_pFieldDocs,
)

where,

  • in_pFieldname - String specifying variable name as used in console.
  • in_fieldType - The variable type. (Types specified in consoleTypes.h).
  • in_fieldOffset - Numeric value calculated using the Offset() macro.
  • in_elementCount - Number of elements at offset. The default value is 1, but if you are referencing an array, then this value will be the number of elements in the array.
  • in_table - This argument is used when the field type is TypeEnum. In this special case, you need to define an EnumTable containing a map of the ENUM values and the strings to represent them in the console.
  • in_pFieldDocs - A short string describing the field in plain English. This field is used in Torque’s automatic Console documentation functionality.


Example: Class GuiControl
In ./gui/core/guiControl.h:

class GuiControl : public SimGroup
{
 ...
   StringTableEntry mClassName;
   StringTableEntry mSuperClassName;
 ...
}

In ./gui/core/guiControl.cc:

void GuiControl::initPersistFields()
{
 ...
   addField( "class",      TypeString, Offset( mClassName,      GuiControl), 
      "Script Class of object."         ) ; 
   addField( "superclass", TypeString, Offset( mSuperClassName, GuiControl), 
      "Script SuperClass of object." ) ; 
 ...
}

See Also
addFieldV, addNamedField, addNamedFieldV


addFieldV

Purpose Augments addField with ‘Type Validator’ classes.

Type Validator Classes are used to restrict the values a field may be given. If illegal values are assigned to a validated field, the validator function will print an error to the console and set the field to a valid value.

The two most commonly used Type Validator Classes are FRangeValidator and IRangeValidator. New validators may be derived from either of these, or their base class TypeValidator.

Note: addFieldV does not support arrays or enumerated types.

Syntax

addFieldV(
const char *in_pFieldname ,
const U32in_fieldType,
const dsize_tin_fieldOffset,
TypeValidator *validator,
)

where

  • in_pFieldname - String specifying variable name as used in console.
  • in_fieldType - The variable type. (Types specified in consoleTypes.h).
  • in_fieldOffset - Numeric value calculated using the Offset() macro.
  • validator - Pointer to a TypeValidator class instance of which there are several derived types to choose from.

Example: Field lightRadius
From projectile.cc, around line 126. The validator will limit the field to between 1.0 and 20.0, inclusive:

addFieldV( "lightRadius", 
           TypeF32, 
           ProjectileData,  
           new FRangeValidator(1, 20) );

See Also
addField, addNamedField, addNamedFieldV


addNamedField

Purpose The addNamedField is a macro that makes use of the simple version addField function and provides a short-hand method of adding fields. It does not support enumerated types or arrays. Also, it does not provide a means of adding documentation strings. It is worth noting that the macro uses the same name for the field as the variable.

Syntax

addNamedField( fieldname , type , className ) ;
  • fieldname - Name of variable to expose. Will be used as name of field.
  • type - The variable type. (Types are specified in consoleTypes.h).
  • className - Name of C++ class containing variable.
addNamedField( isBallistic , TypeBool , ProjectileData );

See Also
addField, addFieldV, addNamedFieldV


addNamedFieldV

Purpose The addNamedField is a macro that makes use of the addFieldV function and provides a short-hand method of adding validated fields.

Syntax

addNamedFieldV( fieldname , type, className,  validator ); 
  • fieldname - Name of variable to expose. Will be used as name of field.
  • type - The variable type. (Types are specified in consoleTypes.h).
  • className - Name of C++ class containing variable.
  • validator - This is a pointer to a TypeValidator class instance of which there are several derived types to choose from.
addNamedFieldV( lightRadius, 
               TypeF32, 
               ProjectileData, 
               new FRangeValidator( 1 , 20 ) );

See Also
addField, addFieldV, addNamedField


addVariable

Purpose The Con::addVariable() function provides a means to expose global C++ variables or static class Members as Torque Script global variables. This function is normally called in a class’ consoleInit () method.

Syntax

Con::addVariable( const char * name , t ,  void * dp );
  • name - String specifying name of global variable (in console).
  • t - The variable type. (Types are specified in consoleTypes.h).
  • dp - A pointer to the global C++ variable, or static Member.
// From camera.cc
Con::addVariable( "Camera::movementSpeed" , TypeF32 , &mMovementSpeed );

See Also
Con::removeVariable


removeVariable

Purpose The Con::removeVariable function provides a means to un-expose global C++ variables or static class Members previously exposed as Torque Script global variables with Con::addVariable.

This call is global. i.e. Once we remove a variable, we cannot put it back.

Syntax

removeField( const char* in_pFieldname );
  • in_pFieldname - String specifying field to be removed.
// 1. TerrainBlock is inherited from SceneObject.
// 2. SceneObject links member mObjToWorld to the 
//    Torque Script field position.
// 3. TerrainBlock undoes this(in terrData.cc)

removeField( "position" );

See Also
Con::addVariable


ConsoleFunction

Purpose The ConsoleFunction macro provides a means to create function from C++ in the console.

Syntax

ConsoleFunction(  name , returnType , minArgs , maxArgs , usage ) 
{

// Function body

}
  • name - This is the name of the function as it will be used in the console.
  • returnType - Is the return type of the function.
  • minArgs - Minimum arguments this function can accept. 1 is the minimum, because the name of the function is automatically passed as the first argument.
  • maxArgs - Maximum arguments this function can accept. If you put 0 in this field, it means any number of arguments may be passed to the function.
  • usage - Is a string that will be printed as a help statement if someone later attempts to use this function with the wrong number of arguments.
// From main.cc
ConsoleFunction( getSimTime , S32 , 1 , 1, 
                "getSimTime() – Time since game started.")
{
  return Sim::getCurrentTime();
}

See Also
ConsoleMethod


ConsoleMethod

Purpose The ConsoleMethod macro provides a means to create a Console Method from C++ in the console. The static variant of ConsoleMethod is for methods that you want to be able to call statically. For example:, GameConnection::getServerConnection().

Syntax

ConsoleMethod( 
   className , scriptname , returnType , 
   minArgs , maxArgs , usage 
) 
{
   // Method body
}

or

ConsoleStaticMethod( 
   className , scriptname , returnType , 
   minArgs , maxArgs , usage ) 
{
 	// Method body
}
  • className - The name of the class the method is in.
  • scriptname - The name the method will be given in the console (i.e. used by TorqueScript).
  • returntype - The return type of the method.
  • minargs - The minimum arguments this method takes. The minimum is 2, because the name of the console method is automatically passed as the first argument and the object’s handle is automatically passed as the second argument.
  • maxargs - The maximum number of args that can be passed to this method. If you put 0 in this field, it means any number of arguments may be passed to the method.
  • usage - A string that will be printed as a help statement if someone later attempts to use this method with the wrong number of arguments. This usage is also when you use the obj.dump() command.

From SimBase.cc:

ConsoleMethod( SimObject , getId , S32 , 2 , 2 , "obj.getId()" )
{
  argc; argv;
  return object->getId();
}

See Also
ConsoleMethod


IMPLEMENT_CONOBJECT

Purpose The C++ macro-instruction used to define a Console Class. In TGB, there are over 170 such classes.

In ./gui/core/guiControl.cc, the console class GuiControl is defined:

IMPLEMENT_CONOBJECT(GuiControl);

See Also
IMPLEMENT_CO_DATABLOCK


IMPLEMENT_CO_DATABLOCK

Purpose The C++ macro-instruction used to define a Console Datablock. In TGB, there are about a dozen such classes.

In ./source/T2D/t2dBaseDatablock.cc, the console datablock t2dBaseDatablock is defined:

IMPLEMENT_CO_DATABLOCK_V1(t2dBaseDatablock);

See Also
IMPLEMENT_CONOBJECT


executef

Purpose Class method Con::executef() invokes a console callback function.

In .game/net/serverQuery.cc, the console function onServerQueryStatus is invoked:

static void processMasterServerQuery( U32 session )
{
...
   Con::executef( 4, "onServerQueryStatus", "update", "Switching master servers...", "0" );
...
}

See Also
executef(this)


executef(this)

Purpose Class method Con::executef(this...) invokes a console class's callback method.

bool GuiControl::onWake( ) 
{
   ...
   if ( isMethod( "onWake" ) )
      Con::executef( this, 1, "onWake" ) ; 
   ...
}

See Also
executef


EnumTable::Enums

Purpose Declare a new static variable in the EnumTable::Enums scope for use as an enumerated data type. For example, in ./gui/containers/guiStackCtrl.cc:

static EnumTable::Enums stackTypeEnum[] =
{
	{ GuiStackControl::stackingTypeVert, "Vertical"  },
	{ GuiStackControl::stackingTypeHoriz,"Horizontal" },
	{ GuiStackControl::stackingTypeDyn,"Dynamic" }
};
static EnumTable gStackTypeTable(3, &stackTypeEnum[0]);

Note that employing the table in the console requires further work; consult the source code.