1

Topics: Scripting

•What is game scripting

•Scripting Features

•Torque Script

2

Game Scripting is just likes other system scripting language, but mostly concern the connection between game engine and external resources. All modern, complete game engines offer a method of programming game behavior via some sort of scripting language. It allows the developer do not need to recompile the whole game engine but just create game content related script to adapt the game engine function.

What is Game Scripting

3

Scripting Advantages• Prototyping

– During the development of your game, you will often need to test out ideas. Creating these quick tests is called "prototyping". Scripts are great for prototyping because they are so quick to code with, test, and modify

• Debugging– Scripts can be great for debugging too. Since scripts are

easily modified on the fly, you can identify problems, change them, and re-test without having to re-compile.

• Game customization and tweaking – Scripts helps to rapidly test different looks and gameplay

behaviors, as mentioned in the point on prototyping, above. – Scripts also allows your players to customize your game to

their liking

4

Scripting Advantages

• Game-Mods– game mods are very popular and are usually also

based on script coding. Mods allow user completely change the way a game looks and plays.

• Writing non-performance-critical functionality– Really, any piece of functionality which won't have a

big impact on performance can be coded in script. Writing render-pipelines in script isn't a good idea, but writing GUI responses and most gameplay functionality is.

5

Game Scripting Features• Basic programming language features

– The scripting language should provide all of the basic features common to modern programming languages, such as powerful variable types, basic operations (addition, subtraction, etc), standard control-statements (if-then-else, for, while, etc), and sub-programs (functions, file-inclusion).

• Access to engine-structures– This is a critical feature. For a game engine's scripting

environment to be of use, it must provide some kind of interface to manipulate the core engine functionality and structures. The scripting system should allow access to the rendering, audio, physics, AI, and I/O systems, and must allow the creation and deletion of objects, and definition of new functions.

6

Game Scripting Features• Familiar and consistent syntax

– Ideally, the syntax of a scripting language is familiar, meaning it is similar to the syntax of a language many programmers are already familiar with, for example C or C++. Also ideal is that the syntax is consistent with the known language, meaning the same rules which apply to the familiar programming language also apply to the scripting language.

• Object-oriented functionality– Object-oriented programming has been a revolution in the art

and science of software engineering. Scripting languages which provide object-oriented functionality offer many benefits, including: •Encapsulation- Provide a means of limiting access to code

and data. •Inheritance- Provide a means of creating new 'objects' from

engine objects and/or scripted objects. •Polymorphism- Allow us to over-ride the default behavior of

derived object code, whether the object is derived from engine objects or other scripted objects.

7

Game Scripting Features

• 'On-demand' loading and scoping– Scripting languages which allow the dynamic loading

and unloading of pieces of code also make it easy to over-ride a program's functionality on the fly, also save the memory.

• Means of 'speeding-up' scripted code– Scripted code is usually not compiled- it is simply

interpreted at run-time. A feature that many common scripting languages (PERL, TCL, VB Script, Java) provide is the ability to 'compile' scripts into pcode. This pcode is then 'executed' on a virtual machine. The benefits of this are size and speed. Pcode is (normally) smaller than and executes faster than interpreted code.

8

Torque Script

•TorqueScript is the script language for TGE. It is very powerful, flexible language with syntax similar to C++. It provides all of the features listed above.

9

The TorqueScript Language• Type-insensitive

– In TorqueScript, variable types are converted as necessary and can be used interchangeably.

if("1.2" == 1.2) { echo("Same- TorqueScript is type-insensitive"); }

else { echo("different- what!?"); }

• Case-insensitive– TorqueScript ignores case when interpreting variable and

function names. $a = "An example"; echo($a); echo($A);

• Statement termination– Statements are terminated with a semi-colon (;) as in many

modern programming languages (C++, Java, Javascript, etc).$a = "This is a statement";

10

The TorqueScript Language• Full complement of operators

– TorqueScript provides all the basic operators common to most programming languages, along with a few more advanced operators.

• Full complement of control structures– As with any robust language, TorqueScript provides the

standard programming constructs: if-then-else, for, while, and switch.

for($a=0; $a < 5; $a++) { echo($a);

}

• Functions– TorqueScript provides the ability to create functions with the

optional ability to return values. Parameters are passed by-value and by-reference.

11

The TorqueScript Language

• Provides Inheritance and Polymorphism– TorqueScript allows you to inherit from engine

objects and to subsequently extend or override object methods.

• Provides Namespaces– Like C++, TorqueScript supports the concept of

namespaces. Namespaces are used to localize names and identifiers to avoid collisions.

• Provides on-demand loading and unloading of functions– TorqueScript supports a very cool feature, which

allows you to load and unload functions as needed.

12

TorqueScript Syntax

• Variables– Variables come in two flavors in TorqueScript: local and

global.

•Local variables are transient, meaning they are destroyed automatically when they go out of scope.

%local_var = value;

•Global variables, on the other hand, are permanent and exist throughout the entire program they are defined in.

$global_var = value2;– Variable names may contain any number of alpha-

numeric (a..z, A..Z, 0..9) characters but not the first character, as well as the underscore (_) character.

– Both local and global variables can have the same name, but contain different values.

13

TorqueScript Syntax – Data Types

• Numbers:– 123 (Integer) 1.234 (floating point) 1234e-3

(scientific notation) 0xc001 (hexadecimal)

• Booleans:– true (1) false (0)

• Strings:– "abcd" (string) 'abcd' (tagged string)

• String Operators:– "string 1" op "string 2"

•@ (concatenates two strings)

•TAB (concatenation with tab)

•SPC (concatenation with space)

•NL (newline)

14

TorqueScript Syntax – Data Types

•Escape Sequences:– \n (newline) – \r (carriage return) – \t (tab) – \c0...\c9 (colorize subsequent text) – \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)

15

TorqueScript Syntax – Data Types

•Arrays:– $MyArray[n] (Single-dimension) – $MyMultiArray[m,n] (Multi-dimension)– $MyMultiArray[m_n] (Multi-dimension) – Special:

•$a and $a[0] are separate and distinct variables

•$MyArray0 and $MyArray[0] are the same

•Vectors:– "1.0 1.0 1.0 1.0" (4 element vector)

16

TorqueScript Syntax - Operators• = Assigns the value of the second operand to the first operand.• +,-,*,/,% Addition, Subtraction, Multiplication, Division, Modulus• +=,-=,*=,/=,%= Computes the Computational OP of two numbers and assigns

the result to the first. • ++,-- Increment, Decrement.• ~,|,&,^ Bitwise NOT, OR, AND, XOR• <<, >> Left bit shift, Sign-propagating Right bit shift• |=, &=, ^= Computes the Logical OP of two numbers and assigns the

result to the first. • <<=, >>= Computes the Bitwise OP of two numbers and assigns the

result to the first. • ! Evaluates the opposite of the value specified. • && Requires both values to be true for the result to be true. • || Requires only one value to be true for the result to be true. • == Evaluates whether value1 and value2 are equal. • != Evaluates whether value1 and value2 are not equal. • <,>,<=,>= Less than, Greater than, Less than or Equal To,

Greater than or Equal To• >$= Evaluates whether string1 is equal to string2 • !$= Evaluates whether string1 is not equal to string2.

17

TorqueScript Syntax - Control Statements

• Branching Structures: if-then-else– The general structure of the if-then-else statement is:

if(expression) { statements;

} else {

alternate statements; }

– Brackets '{}' are optional for single line statements. (Many programmers find it more helpful to always use brackets.)

– Compound if-then-else-if-then-... statements are perfectly legal (Many programmers find switch statements easier to read for large blocks of related if-cases).

18

TorqueScript Syntax - Control Statements

• Branching Structures: switch– The general structure of the switch statement is:

switch(expression) { case value0: statements;

break; case value1: statements;

break; ... case valueN: statements;

break; default: statements;

}; – switch only (correctly) evaluates numerics. There is a special

statement, 'switch$', for strings. – break statements are superfluous. TorqueScript will only execute

matching cases. – In TorqueScript, switch statements are no faster than if-then-else

statements.

19

TorqueScript Syntax - Control Statements

• Looping Structures– for- The general structure of the for-loop is:

for(expression0; expression1; expression2) {

statement(s); }

– while- The general structure of the while-loop is: while(expression) {

statements; }

20

TorqueScript Syntax - Functions• Basic functions in TorqueScript are defined as follows:

function func_name([arg0],...,[argn]) { statements; [return val;]

}

• TorqueScript does not support function polymorphism in the same way C++ does.– If you define a function and give it the same name as a

previously defined function, even if you define the new function with a different number of parameters, TorqueScript will completely override the old function.

• If you call a function and pass fewer parameters than the function's definition specifies, the un-passed parameters will be given an empty string as their default value.

• TorqueScript supports recursion, and it behaves just as in C++.

21

TorqueScript Syntax - Objects

• In Torque, every item in the game world is an object, and all game world objects can be accessed via script. Objects are created in TorqueScript using the following syntax:

// In TorqueScript %var = new ObjectType(Name : CopySource,

arg0, ..., argn) {<datablock = DatablockIdentifier;> [existing_field0 = InitialValue0;] ... [existing_fieldM = InitialValueM;] [dynamic_field0 = InitialValue0;] ... [dynamic_fieldN = InitialValueN;] };

22

TorqueScript Syntax - Objects• %var

– Is the variable where the object's handle will be stored.

• New– Is a key word telling the engine to create an instance of the

following ObjectType.

• ObjectType– Is any class declared in the engine or in script that has been

derived from SimObject or a subclass of SimObject. SimObject-derived objects are what we were calling "game world objects" above.

• Name (optional)– Is any expression evaluating to a string, which will be used as

the object's name.

• arg0, ..., argn (optional)– Is a comma separated list of arguments to the class

constructor (if it takes any).

23

TorqueScript Syntax - Objects• CopySource (optional)

– The name of an object which is previously defined somewhere in script. Existing field values will be copied from CopySource to the new object being created. Any dynamic fields defined in CopySource will also be defined in the new object, and their values will be copied. Note: If CopySource is of a different ObjectType than the object being created, only CopySource's dynamic fields will be copied.

• Datablock– Many objects (those derived from GameBase, or children of

GameBase) require datablocks to initialize specific attributes of the new object.

• existing_fieldM– In addition to initializing values with a datablock, you may also

initialize existing class members (fields) here. Note: 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.

24

TorqueScript Syntax - Handles and Names

• Every object in the game is identified and tracked by two parameters: – Handle- Every object is assigned a unique numeric ID

upon creation. This is generally referred to as the object's handle.

– Name- Additionally, all objects may have a name.

•Assume an object named MyObject– MyObject.aproperty = 42;– “MyObject”.aproperty = 42;– %handle = MyObject

%handle.aproperty = 42;– %handle = “MyObject”

%handle.aproperty = 42;

25

TorqueScript Syntax - Fields and Commands

• TorqueScript object Fields and Commands are the equivalents of C++ object Members and Methods.

•MyObject.field_name = value;

•%handle.command_name();

• Dynamic Fields– In addition to normal fields, which are common between all

instances of an object type, TorqueScript allows you to create dynamic fields. Dynamic fields are associated with a single instance of an object and can be added and removed at will.

// 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);

26

TorqueScript Syntax - Console Methods

• In addition to supporting the creation of functions, TorqueScript allows you to create methods that have no associated C++ counterpart:

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

statements; [return val;]

}

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

• %this– Is a variable that will contain the handle of the 'calling object'.

• ...– Is any number of additional arguments.

27

TorqueScript Syntax - Namespaces

• Namespaces are means of defining a formal context for variables.

• Using namespaces allows us to use different variables that have the same name without confusing the game engine or ourselves.

• You can arbitrarily assign variables to namespace// Player class Namespace

$Player::HP

• // Not really namespaces function Ver1::doIt() {

... };

28

TorqueScript Syntax - Datablocks

• A datablock is an object that contains a set of characteristics which describe some other type of object. – That means a datablock is a(n) object that can be declared

either in C++ engine code, or in script code ... Each declared datablock can then be used as a "template" to create objects.

• Datablock objects exist simultaneously on the server and all its connected clients. Every copy of a given datablock uses the same handle whether it is on the server or a client.

• Syntaxdatablock ClassIdentifier(NameIdentifier){

InitializationStatements};

datablock ClassIdentifier(NameIdentifier : CopySourceIdentifier)

{InitializationStatements

};

29

TorqueScript Syntax - Packages• A package is a Torque construct that encapsulates that functions that can be

dynamically loaded and unloaded during program execution.package package_name() {

function function_definition0() {

[statements]; } ... function function_definitionN() {

[statements]; }

};

• Packages can be used to dynamically overload functions using parent::function script mechanism in the packaged function.

• Packages can be activated and deactivated:

•ActivatePackage(package_name);

•DeactivatePackage(package_name);

30

Engine-Console Interface Terminology C++-Specific Terms

• C++ Variable– A C++ variable not associated with any class.

• C++ Function– A routine declared and defined in C++, which is not

associated with any class. • Member

– A variable defined and declared in a C++ class. Can only be accessed in association with an instance of an object.

• Method– A routine defined and declared in a C++ class. Can only be

accessed in association with an instance of an object. Script-Specific Terms • 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++. • 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. • Command (deprecated)

– A routine associated with a particular namespace in the Console. Linked with an existing Method. Console Commands are deprecated

• Console Method– A routine associated with a particular namespace in the

Console. Exists only the Console.