torque script
Download
Skip this Video
Download Presentation
Torque Script

Loading in 2 Seconds...

play fullscreen
1 / 65

Torque Script - PowerPoint PPT Presentation


  • 217 Views
  • Uploaded on

Torque Script. CIS 487/587 Bruce R. Maxim UM-Dearborn. Scripting Advantages. Useful for prototyping without recompilation Makes debugging easier Allows for game customization and tweaking Allows players to make their own total-mod based on an existing game structure

loader
I am the owner, or an agent authorized to act on behalf of the owner, of the copyrighted work described.
capcha
Download Presentation

PowerPoint Slideshow about 'Torque Script' - stillman


An Image/Link below is provided (as is) to download presentation

Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author.While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server.


- - - - - - - - - - - - - - - - - - - - - - - - - - E N D - - - - - - - - - - - - - - - - - - - - - - - - - -
Presentation Transcript
torque script

Torque Script

CIS 487/587

Bruce R. Maxim

UM-Dearborn

scripting advantages
Scripting Advantages
  • Useful for prototyping without recompilation
  • Makes debugging easier
  • Allows for game customization and tweaking
  • Allows players to make their own total-mod based on an existing game structure
  • Any functional component that is not time critical can be written using scripting language rather than a compiled language
necessary features
Necessary Features
  • Basic programming language features (variables, data types, control structures)
  • Access to engine-structures (rendering, audio, physics, AI, I/O, object management)
  • Familiar and consistent syntax
  • Object functionality (encapsulation, inheritance, polymorphism)
  • Dynamic scoping and memory management
  • Compilation of virtual machine “p-code”
using the console
Using the Console
  • Single script statements can typed in the console command line or an entire script can loaded from a file
  • The console window is opened by typing “~” once a Torque application is running
  • Ctrl-V allows pasting from clipboard into command line
  • The echo command can be used
    • echo(“Torque rocks”);
    • echo(1+1);
syntax
Syntax
  • Torque is type insensitive
    • “1.2” == 1.2
  • Torque is case insensitive
    • $a == $A
  • The “;” is used as a statement terminator
    • $a = “a text string”;
torque features
Torque Features
  • Contains C++ arithmetic operators plus a few extra string operators
  • Control structures and function definition are similar to C++
  • Provides engine object inheritance and polymorphism
  • Supports use of Namespaces
  • On-demand loading and unloading of functions
  • Compiles and executes pcode
variables
Variables
  • Variables do not need explicit declaration
  • Variable names begin with letter and contain any number of letters, digits, or “_”
  • Local and global variables
    • %local_var = value;
    • $global_var = value;
basic data types
Basic Data Types
  • Numbers:
    • 123 (Integer)
    • 1.234 (floating point)
    • 1234e-3 (scientific notation)
    • 0xc001 (hexadecimal)
  • Strings
    • "abcd" (string)
    • 'abcd' (tagged string)
  • Booleans
    • true (1)
    • false (0)
tagged strings
Tagged Strings
  • Tagged strings have special numeric data associated with them
  • Tagged strings are used for sending strings across networks more efficiently
  • Tagged strings behave like normal strings
  • Tagged values can only be printed by detagging them after transmission
    • echo(“detagging example “ detag(‘$b’));
string operations
String Operations
  • Syntax
    • “string 1” op “string “
  • Operators
    • @ (concatenates two strings)
    • TAB (concatenation with tab)
    • SPC (concatenation with space)
    • NL (newline between strings)
string escape sequences
String Escape Sequences

\n (newline)

\r (carriage return)

\t (tab)

\c0...\c9 (colorize subsequent text – predefined color)

\cr (reset to default color)

\cp (push current color on color stack)

\co (pop color from color stack)

\xhh (two digit hex value ASCII code)

\\ (backslash)

arrays
Arrays
  • Example
    • $MyArray[n] (Single-dimension)
    • $MyMultiArray[m,n] (Multi-dimension)
    • $MyMultiArray[m_n] (Multi-dimension)
  • Refernces
    • $a != $a[0]
    • $a0 == $a[0]
    • $b[0,0] == $b0_0
vectors
Vectors
  • Allow group of numeric values to be manipulated in sets of 3 or 4
  • Stored as strings, but interpreted as vectors
  • Torque provides a set of script operators for vectors
  • Example
    • “1.0 1.0 1.0 1.0” (4 element vector)
operators
Operators
  • Boolean and arithmetic operators similar to those found in C++
  • The ++ and --operators are used only as postfix operators
  • The string comparison operators are
    • $= (test for string equality)
    • !$= (test for string inequality)
if then else
if-then-else
  • Brackets optional for single line statements
  • Nested if-then-else statements are allowed
  • Example

if(expression)

{ statements; }

else

{ alternate statements; }

switch
switch(expression)

{

case value0:

statements;

break;

case value1: statements;

break;

default:

statements;

};

Switch only works for numeric expressions

Use switch$

The breaks are not really needed since Torque only executes one case

switch
slide17
for
  • Examples

for(expression0; expression1; expression2)

{ statement(s); }

for(%count = 0; %count < 5; %count++)

{

echo(%count);

}

while
while
  • Examples

while(expression)

{ statements; }

%count = 0;

while (%count < 5)

{

echo(%count);

%count++;

}

functions 1
Functions - 1
  • Functions cannot have multiple prototypes (always keeps the most recently defined)
  • Torque does support the concept of packages to work around the duplicate name problem
  • Functions can be recursive
  • If functions are passed fewer actual parameters than the number the defined, the missing parameters will be assigned null string values
functions 2
// function declaration

function echoRepeat (%echoString, %repeatCount)

{

for (%count = 0; %count < %repeatCount; %count++)

{ echo(%echoString); }

}

// function call from console or script

echoRepeat("hello!", 5);

Functions - 2
functions 3
Functions - 3

// recursive function

function echoRepeat (%echoString, %repeatCount)

{

if (%repeatCount > 0)

{

echo(%echoString);

echoRepeat(%echoString, %repeatCount--);

}

}

// calling recursive function

echoRepeat("hello!", 5);

objects 1
Objects - 1
  • Every game item is considered an object
  • Even C++ objects are accessible via scripts
  • Every game object is assigned a numeric ID known as a handle
  • An objects may be assigned a name
  • Torque object data members are called as fields and functional methods are called commands
objects 2
Objects - 2

%var = new ObjectType(Name : CopySource, arg0, ..., argn)

{

[existing_field0 = InitialValue0;]

...

[existing_fieldM = InitialValueM;]

[dynamic_field0 = InitialValue0;]

...

[dynamic_fieldN = InitialValueN;]

};

object 3
Object - 3
  • %var- variable to hold object's handle
  • ObjectType- Is any class declared in the engine or in script that has been derived from SimObject or a subclass of SimObject.
  • Name (optional)- object's name.
  • CopySource (optional)- The name of an object which is previously defined somewhere in script.

Note: If CopySource is of a different ObjectType than the object being created, only CopySource's dynamic fields will be copied.

object 4
Object - 4
  • arg0, ..., argn (optional)- comma separated list of arguments to the class constructor.
  • datablock- Many objects (those derived from GameBase, or children of GameBase) require datablocks to initialize specific attributes of the new object.
object 5
Object - 5
  • existing_fieldM- In addition to initializing values with a datablock, you may also initialize existing class members (fields) here.

Note: In order to modify a member of a C++-defined class, the member must be exposed to the Console.

  • dynamic_fieldN- Lastly, you may create new fields (which will exist only in Script) for your new object. These will show up as dynamic fields in the World Editor Inspector.
object 6
Object - 6

// create a SimObject w/o modifying any fields

$example_object = new SimObject();

// create a SimObject w/ dynamic fields

$example_object = new SimObject()

{

a_new_field = "Hello world!";

};

object 7
Object - 7

// create a StaticShape using a datablock

datablock StaticShapeData(MyFirstDataBlock)

{

shapeFile = "~/data/shapes/player/player.dts";

junkvar = "helloworld";

};

new StaticShape()

{

dataBlock = "MyFirstDataBlock";

position = "0.0 0.0 0.0";

rotation = "1 0 0 0";

scale = "1 1 1";

};

using objects
Using Objects

// assuming the existence of a player called myGuy

// you could type the following in from the Console

$player_name = "myGuy";

$player_id = $player_name.getID();

echo($player_name.position);

echo($player_name.getID());

echo(myGuy.getid());

dynamic fields 1
Dynamic Fields - 1
  • Are associated with specific instances of an object type
  • There are allocated as referenced
  • Assigning a value to field that does not exist creates a new field
  • Trying to read a field that does not exist does not create a new field and a null string is returned
dynamic fields 2
Dynamic Fields - 2

// new_var will not be created because we are only

// 'reading' it

echo($player_id.new_var);

// new_var2 will be created and initialized to "Hello”

$player_id.new_var2 = "Hello";

echo($player_id.new_var2);

console functions 1
Console Functions - 1

function Classname::func_name(%this,[arg0],...,[argn])

{

statements;

return val; // optional

}

The syntax breaks down as follows:

  • function- Is a keyword telling TorqueScript we are defining a new function.
  • ClassName::- Is the class type this function is supposed to work with.
  • func_name- Is the name of the function we are creating.
console functions 2
Console Functions - 2
  • %this- Is a variable that will contain the handle of the 'calling object'.
  • ...- Is any number of additional arguments.

function Player::hi(%this)

{

echo("Player Hello ", %this);

Parent::hi(%this);

}

// assuming Player handle is 1000 we can call

1000.hi();

console functions 3
Console Functions - 3
  • We can force Torque to call a specific instance using

NetObject::hi(1000);

  • New console function definitions override previous definitions with same name
  • Console functions (scripts and packages) can be loaded using the exec command

exec(test_scripts/package_test.cs);

packages 1
Packages - 1
  • Provide dynamic function polymorphism
  • Function definitions from active packages override current function definitions
  • Functions can appear in multiple packages
  • Functions can be packaged datablocks can not be packaged
packages 2
Packages - 2

function demo()

{ echo("Demo definition 0"); }

package DemoPackage1

{

function demo()

{ echo("Demo definition 1"); }

};

package DemoPackage2

{

function demo()

{ echo("Demo definition 2"); }

};

packages 3
Packages - 3
  • To make use of specific functions

demo(); // original version

ActivatePackage(DemoPackage1);

demo(); // package 1 version

ActivatePackage(DemoPackage2);

demo(); // package 2 version

DeactivatePackage(DemoPackage2);

demo(); // package 1 version

DeactivatePackage(DemoPackage1);

demo(); // original version

engine console interface 1
Engine-Console Interface - 1
  • C++ Variable
    • variable not associated with any class.
  • C++ Function
    • function is not associated with any class.
  • Member
    • A variable defined in a C++ class.
  • Method
    • A routine defined and declared in a C++ class.
engine console interface 2
Engine-Console Interface - 2
  • Local or Global Variable
    • A variable in the Console.
    • Global variables may be defined in C++ and linked to a global engine variable.
    • Allowed C++ modifiers: const, static.
  • Function
    • A routine in the Console not associated with any particular namespace.
    • May be defined entirely in script or C++.
engine console interface 3
Engine-Console Interface - 3
  • Field
    • A variable associated with an object in the Console.
    • Linked with a Member.
  • Dynamic Field
    • A variable associated with an object in the Console.
    • Exists only in the Console.
engine console interface 4
Engine-Console Interface - 4
  • Command (deprecated)
    • A routine associated with a particular namespace in the Console.
    • Linked with an existing Method.
    • Console Commands are deprecated-- that is, they should no longer be used. Information on them is provided for reference only.
  • Console Method
    • A routine associated with a particular namespace in the Console.
    • Exists only the Console.
addfield
addField( )
  • This function allows you to link C++ class Members to console object Fields.
  • The rules for using this function are
  • Member to be exposed must be non-dynamic (i.e. not a pointer).
  • Member to be exposed must be non-static.
  • addField() statements must be included in the class initPersistFields( ) method.
addfield43
addField( )

void ConsoleObject::addField

(const char*in_pFieldname, // console var name

const U32 in_fieldType, // from consoleTypes.h

const dsize_t in_fieldOffset, // calc by Offset()

const char* in_pFieldDocs) // text field description

void ConsoleObject::addField

(const char* in_pFieldname,

const U32 in_fieldType,

const dsize_t in_fieldOffset,

const U32 in_elementCount, // # elements at offset

EnumTable *in_table, // table of enum values

// and strings

const char* in_pFieldDocs)

addfieldv
addFieldV( )
  • Specialized version does not handle enums
  • Supports use of validator functions

void ConsoleObject::addFieldV

(const char* in_pFieldname,

const U32 in_fieldType,

const dsize_t in_fieldOffset,

TypeValidator *v) // pointer to TypeValidator

// class

macros 1
Macros -1
  • addField() variants used to give a console field the same name as class member

#define addNamedField

(fieldName,type,className)

\ addField(#fieldName, type,

Offset(fieldName,className))

#define addNamedFieldV

(fieldName,type,className, validator)

\ addFieldV(#fieldName, type,

Offset(fieldName,className), validator)

macros 2
Macros - 2
  • Offset macro calculate position of variable in bytes from beginning of class in memory

Offset(VariableName, // C++ class member name to

// expose to console

ClassName) // name of C++ class

removefield
removeField( )
  • Lets you unlink a member-field pairing
  • Can be used to hide information form player (e.g. not allow position calls for Terrain data)

bool ConsoleObject::removeField

(const char* in_pFieldname)

// in_pFieldname is string specifying string to

// be removed

con addvariable
Con::addVariable
  • This function allows you to expose a global C++ variable or a static Member as a global variable in the console. (See camera.cc.)

Con::addVariable

(const char *name, // string specifying global

// console variable

S32 t, // variable type from

// consoleTypes.h

void *dp); // point to C++ global

// variable or static

// member

consolemethod 1
ConsoleMethod - 1
  • This is a macro that allows you to create a new Console Method from C++.
  • Used to replace clumsy addCommand() calls.
  • The static variant of ConsoleMethod is for methods that you want to call statically. For example, 'GameConnection::getServerConnection()'.

ConsoleMethod(className,scriptname,

returnType,minArgs,maxArgs,usage)

ConsoleStaticMethod(className,scriptname,returnType,minArgs,maxArgs,usage)

consolemethod 2
ConsoleMethod - 2

ConsoleMethod

(className, // class owning C++ method

scriptname, // method name inside console

returnType, // method return type

minArgs, // mini # method arguments

// method name is 1st and handle

// is 2nd

maxArgs, // max # arguments, 0 means any

// number of args can be passed

usage) // help statement used is wrong

// number of args are passed

// in call

consolemethod 3
ConsoleMethod - 3

// From SimBase.cc

// Calls a methos getID() which returns a

// 32 bit value

ConsoleMethod

(SimObject, getId, S32, 2, 2, "obj.getId()")

{

argc;

argv;

return object->getId();

}

consolefunction 1
ConsoleFunction - 1
  • This is a macro that allows you to create a new Console Function from C++.
  • Ex: ShapeBase.cc

ConsoleFunction

(name, // console name for function

returnType, // function return type

minArgs, // function name passed as 1st

maxArgs, // 0 means any number

usage) // help statement for error

consolefunction 2
ConsoleFunction - 2

// From main.cc

// Creates a console function that can be used

// to call the C++ function Sim::getCurrentTime

ConsoleFunction

( getSimTime, S32, 1, 1,

"getSimTime() - Time since game started.")

{

return Sim::getCurrentTime();

}

con getlocalvariable
Con::getLocalVariable( )
  • This function allows you to get the contents of a local variable in the console from within the engine.
  • Note: The value is returned as a char string.

const char *Con::getLocalVariable

(const char* name);

con setlocalvariable
Con::setLocalVariable()
  • This function allows you to set the contents of a local variable in the console from within the engine.
  • Note: all values passed as char strings to the console. The console automatically converts this information as necessary.

Con::setLocalVariable

(const char *name, const char *value);

console printing functions
Console Printing Functions
  • These functions provide the ability to print various levels of information into the console (or log if logging is enabled).
  • *_format is a standard C format string

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

Con::warnf

(ConsoleLogEntry::Type type, const char *_format, ...);

Con::errorf

(ConsoleLogEntry::Type type, const char *_format, ...);

datablocks 1
Datablocks - 1
  • Objects placed in the game world will fall into three broad categories:
    • The object does not have much associated data and/or has few parameters.
    • The object does have a lot of parameters, but these parameters are likely to be unique, or must be allowed to be unique, between instances of the object.
    • The object has a lot of data or parameters, but it is OK for these datum/parameters to be shared between instances.
datablocks 2
Datablocks - 2
  • The first two categories fit the class of objects that do not need and are therefore not created from datablocks.
  • The third category fits the class of objects that could benefit from using datablocks. Why?
    • Unlike normal objects, you are only allowed to have a single instance of any datablock.
    • Furthermore, objects that are created from datablocks all share the same instance of that datablock.
creating datablock objects 1
Creating Datablock Objects - 1
  • The following creates a StaticShape object named TestTarget that uses SimpleTarget0 to initialize the object’s datablock

new StaticShape(TestTarget)

{

position = "0 0 0";

rotation = "1 0 0 0";

scale = "1 1 1";

dataBlock = "SimpleTarget0";

};

creating datablock objects 2
Creating Datablock Objects - 2
  • The following uses inheritance to create a StaticShape object named TestTarget2

new StaticShape(TestTarget2: TestTarget)

{

position = "0 10 0";

};

declaring datablocks 1
Declaring Datablocks - 1
  • Similar to declaring console objects

datablock DataBlockType(Name [: CopySource])

{

category = "CategoryName";

[datablock_field0 = Value0;]

...

[datablock_fieldM = ValueM;]

[dynamic_field0 = Value0;]

...

[dynamic_fieldN = ValueN;]

};

declaring datablocks 2
Declaring Datablocks - 2

// Creates MyTargets and specifies that it should be

// located in the Targets folder in the World Editor tree

datablock StaticShapeData(MyTargets)

{

category = "Targets";

shapeFile = "~/data/shapes/targets/simpletarget0.dts";

};

// Inherits all data from MyTargets and adds new variable

// StartHidden with initial value 1

datablock StaticShapeData(SimpleTarget0 : MyTargets)

{

StartHidden = 1;

};

namespaces
Namespaces
  • There is a Namespace for every Torque object
  • Namespaces are chained
  • Search to resolve names begins with the current object namespace and then works recursively upwards through the parent’s namespace
object namespace 1
Object Namespace - 1

function GameBase::doIt(%this)

{

echo("Calling StaticShape::doIt() ==> on object“

SPC %this);

};

// since doIt is declared in GameBase namespace or

// its children

%myTarget = new StaticShape(CoolTarget)

{

position = "0 0 0";

dataBlock = "SimpleTarget1";

};

%myTarget.doIt();

object namespace 2
Object Namespace - 2
  • When doIt( ) is called, you do not need to pass an argument explicitly, the console uses the argument object tag if we do not
  • The one argument doIt( ) uses is named %this.

Please note:

  • in the cases where we use the name of the object, the name will be passed as the ID. Torque automatically does lookups for names
  • thus in most cases, names can be used interchangeably with IDs, as long as the names are unique.
ad