Torque script l.jpg
This presentation is the property of its rightful owner.
Sponsored Links
1 / 65

Torque Script PowerPoint PPT Presentation


  • 172 Views
  • Uploaded on
  • Presentation posted in: General

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

Download Presentation

Torque Script

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 l.jpg

Torque Script

CIS 487/587

Bruce R. Maxim

UM-Dearborn


Scripting advantages l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

if-then-else

  • Brackets optional for single line statements

  • Nested if-then-else statements are allowed

  • Example

    if(expression)

    { statements; }

    else

    { alternate statements; }


Switch l.jpg

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 l.jpg

for

  • Examples

    for(expression0; expression1; expression2)

    { statement(s); }

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

    {

    echo(%count);

    }


While l.jpg

while

  • Examples

    while(expression)

    { statements; }

    %count = 0;

    while (%count < 5)

    {

    echo(%count);

    %count++;

    }


Functions 1 l.jpg

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 l.jpg

// 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 l.jpg

Functions - 3

// recursive function

function echoRepeat (%echoString, %repeatCount)

{

if (%repeatCount > 0)

{

echo(%echoString);

echoRepeat(%echoString, %repeatCount--);

}

}

// calling recursive function

echoRepeat("hello!", 5);


Objects 1 l.jpg

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 l.jpg

Objects - 2

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

{

<datablock = DatablockIdentifier;>

[existing_field0 = InitialValue0;]

...

[existing_fieldM = InitialValueM;]

[dynamic_field0 = InitialValue0;]

...

[dynamic_fieldN = InitialValueN;]

};


Object 3 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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 l.jpg

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.


  • Login