Adding your own console methods and functions

Adding Script Functions and Methods via C++ Source

The first thing that must be clarified is the difference between a function and a method. A function is universal and is not called by an object. A method on the other hand is called by an object and is aware of that object. More often than not, you will be using methods.

Console methods are actually surprisingly easy to implement. As a simple example, let's examine item.cc. Starting on line 931, there are five defined console methods: isStatic, isRotating, setCollisionTimeout, getLastStickPos, and getLastStickyNormal. Take a look at how isStatic is defined:

ConsoleMethod(Item, isStatic, bool, 2, 2, "()"
              "Is the object static (ie, non-movable)?")

What's going on here?

The first argument is the class name. Only objects of this class can call this method. This argument is not part of ConsoleFunction.

Next is the method name, which is what you'd be calling in script. (%itemObj.isStatic())

Then we have what type of data it returns (bool, int, float, etc.)

Next is the minimum number of arguments, then the maximum number.

But waitisStatic doesn't have any arguments!
As far as calling it from script goes, it has no arguments. However, ConsoleMethod considers the name of the method and the object calling it to be arguments, therefore all ConsoleMethods must have a minimum of two arguments. ConsoleFunctions only have a minimum of one because they are not called by any one object.

Finally, we have the doco field, which is used for documentation.

Never underestimate the power of console methods. Because they are located in the source code, they have full access to all source code level functions, which allows them to do a variety of complex tasks not possible in script alone.

Now how does this all work together?

Did you know that many objects in Torque can render shadows(StaticShape takes a little more tweaking than what is shown here, for TSStatics, buy the lighting pack. Thanks for pointing that out Brett)? The reason they don't is because by default, up in ShapeBaseData, mGenerateShadow is set to false. Let's write a console method that will allow us to turn shadows on and off for individual objects.

Open up shapeBase.cc and scroll down to the beginning of the ConsoleMethod declarations (line 3519). At the very beginning of these, we'll add ours. Let's call it "switchShadowState". It will only need two arguments, the name and the ID of the object that called it. So, first the declaration

ConsoleMethod( ShapeBase, switchShadowState, void, 2, 2, "")

Here we have a method that any ShapeBase object can call named switchShadowState. It returns nothing, and no arguments are passed from the script call. Continuing

{
   object->switchShadowState();
}

Notice how we didn't set the variable directly in the console method.

Now, for this to work, somewhere after IMPLEMENT_CONETOBJECT in your code you need to add

ShapeBase::switchShadowState()
{
   mGenerateShadow = !mGenerateShadow;
}

And you're done! Go ahead and try it out in starter.fps. Get the handle of a health pack and in the console call switchShadowState on it. You should see a shadow being cast from it now. Cool, no?

Notes: The object calling the method is always the first argument, the name of the method is always the last argument. All other arguments you may include are in the middle.

All arguments are passed to ConsoleMethod as strings. To extract useful data from these strings, you need to use dAtoi for ints, dAtof for floats, or dAtob for bools. For a complete list of various functions you can use with strings, refer to this (Don't you just love DOxygen docs?)

ConsoleFunction works in a similar manner, only it is not aware of the object calling it, greatly reducing it's usefulness in many situations.

C++ functions can not call console methods or functions. However, you can call functions defined in script via C++ using Con::executef(). The setup for this is

Con::executef(object, argc, name, arg[1], arg[2]);

Where object is the SimObject calling the function(usually mDatablock or this Note: This field is only necessary if the function belongs to a namespace), argc is the number of arguments, name is the name of the script function, and arg[1], etc. are the arguments to be passed. A very useful function that can be used with this is scriptThis() which will return the ID of the SimObject. There is always 1 argument (the name of the function) but the calling object does not count as a second argument.(Thanks Stephen. Hope I got that right)


More Console Stuff DIY. You always learn more that way.

Here is another resource on adding console methods and functions.