This describes the CScript macro programming language used by the CScript macro processor / code generator.

--------------------------------------------------------------------------------------------------------------------

CScript macro processing language synatx description

CScript macro processor / code generator

(C) 1996-2013 Rockland Software Productions

--------------------------------------------------------------------------------------------------------------------

--------------------------------------------------------------------------------------------------------------------

What is CScript ?

--------------------------------------------------------------------------------------------------------------------

CScript is a macro processor and code generator for C++.

Its also the name of the macro processor langauage used by the CScript macro processor / code generator.

The CScript macro processor translates CScript code into C++ code.

It takes a CScript source file as input, and generates a C++ source file as output, ready to compile.

CScript is designed to help speed up code entry.

If you can think in code at light-speed, but your fingers can only type in code at sub-light speed,

CScript is designed with you in mind.

The syntax is designed to reduce the number of keystrokes requied for code entry.

The keywords of the language are designed to be short, quick, and easy to type in, but still be mnemonic.

A CScript source file can contain both CScript and C++ code feely mixed together.

Any line that does not begin with a CScript keyword is assumed to be C++ code,

and is automatically passed through unaltered, and written to the C++ output file.

This lets you use CScript for fast code entry of common everyday C++ code,

and true C++ for synatx that CScript doesn't handle directly.

--------------------------------------------------------------------------------------------------------------------

CScript statements

--------------------------------------------------------------------------------------------------------------------

CScript statements consist of a keyword and optional tokens, separated by whitespace.

--------------------------------------------------------------------------------------------------------------------

CScript tokens

--------------------------------------------------------------------------------------------------------------------

Tokens are similar to function or macro parameters. in C++.

There are two types of tokens in CScript: string tokens and non-string tokens.

A string token is a string enclosed by double quotes: "this is a string token"

A string token may contain whitespace between the double quotes.

A non-string token is any string of non-whitespace charaters, not enclosed in double quotes.

Cscript statements are whitespace delimited, so a token can't have whitespace in it.

Only string tokens enclosed in double quotes can have whitespace in them.

If a token not enclosed in double quotes has whitespace in it, CScript treats it as two separate tokens .

CScript treats tokens enclosed in double quotes as C++ string literals.

So the double quotes are passed along with the string to the C++ output file:

c printf "%s\n" "this is a test"

printf("%s\n","this is a test");

--------------------------------------------------------------------------------------------------------------------

Example tokens:

--------------------------------------------------------------------------------------------------------------------

1 / / a literal value

-0.084f // a token can include type info!

"this is a string" / / a string

my_var // a variable name

SomeFunctionCall(param1,param2,param3) // a function call

if((a>b)&&(c

x-=3*y+b // a code statement

ANYTHING that can be expressed in C++ code as a string with no whitespace can be a token!

Anything that uses double quotes can also be a token.

--------------------------------------------------------------------------------------------------------------------

CScript macro processing language synatx description

--------------------------------------------------------------------------------------------------------------------

In the following syntax desciptions, A , B, etc, represent tokens.

a "code block" is simply a set of statements, such as would normally be enclosed in squiggly brackets in C++.

The syntax descriptions use the following format:

Keyword name: the name of the keyword - such as "if equals" or "limit".

Keyword symbol: the keyword symbol that gets typed in at the start of a new line to begin this type of CScript statement.

What it does: a short descrription of what the keyword does.

Syntax: the CSript sytax for using the keyword.

Translates to: the C++ code geenrated by the CScript syntax.

Notes: special notes about the keyword, such as only working with specific data types,

or being part of the Cscript langauge extensions for a particular library such as directX.

Examples: examples of Cscript code usng the keyword, and the C++ code generated in the output file.

--------------------------------------------------------------------------------------------------------------------

Comment statements

--------------------------------------------------------------------------------------------------------------------

keyword name: COMMENT LINE

keyword symbol: ' (apostrophe)

what it does: the line is treated as a comment. it is not translated or passed through to the C++ output file.

syntax: ' your comment goes here

translates to: nothing - no line is genrate as output. the comment line is stripped out of the C++ output file.

example: ' this is a comment

Keyword name: BEGIN COMMENT BLOCK

Keyword symbol: [

What it des: same as /* in C++

Syntax: [

Translates to: /*

Example: [

this is a comment block

]

Keyword name: END COMMENT BLOCK

Keyword symbol: [

What it des: same as */ in C++

Syntax: ]

Translates to: */

Example: [

this is a comment block

]

--------------------------------------------------------------------------------------------------------------------

C++ preprocessor statements

--------------------------------------------------------------------------------------------------------------------

Keyword name: DEFINE

Keyword symbol: #d

What it des: C++ #define preprocessor directive

Syntax: #d A B

where A is the symbol name, and B is its value.

Translates to: #define A B

Example: #d g -32.0f

#define g -32.0f // define acceleration of gravity

Keyword name: INCLUDE

Keyword symbol: #i

What it des: C++ #include preprocessor directive

Syntax: #i A

where A is the include file.

Translates to: #include A

Example: #i

#include

--------------------------------------------------------------------------------------------------------------------

Data declaration statements

--------------------------------------------------------------------------------------------------------------------

Keyword name: INT

Keyword symbol: i

What it does: declares integers

Syntax: i A B C .....

Translates to: int A, B, C;

Examples: i myint

int myint;

i joe fred[100] *james **tom harold[max_this][max_that]

int joe, fred[100], *james, **tom, harold[max_this][max_that];

Keyword name: FLOAT

Keyword symbol: f

What it does: declares a float

Syntax: f A B ....

Translates to: float A, B, .... ;

Example: f et fps vec3[3] *f-addr

float et, fps, vec3[3], *f_addr ;

Keyword name: STRING

Keyword symbol: s

What it does: declares a string

Syntax: s A B ......

Translates to: char A[100] B[100]

Example: s s s2 ( 6 keystrokes )

char s[100],s2 [100]; ( 21 keystrokes )

Keyword name: STRUCT

Keyword symbol: st

What it does: declares a struct

Syntax: st A

/ code block - variable declarations

.st / .st ends a struct

where A is the name of the struct

Translates to: struct A

{

// code block

} ;

Example: st postion

f x

f y

f z

.st

struct postion

{

float x;

float y;

float z;

};

Keyword name: END STRUCT

Keyword symbol: .st

What it does: ends a struct declaration

Syntax: st A

/ code block - variable declarations

.st / .st ends a struct

where A is the name of the struct

Translates to: struct A

{

// code block

} ;

Example: st postion

f x

f y

f z

.st

struct postion

{

float x;

float y;

float z;

};

--------------------------------------------------------------------------------------------------------------------

Math statements

--------------------------------------------------------------------------------------------------------------------

keyword name: SET

keyword symbol: =

what it does: sets a value

syntax: = A B

translates to: A = B ;

where A and B are any two tokens that evluate to comptabel typs

keyword name: ADD

keyword symbol: +

what it does: adds two values

syntax: + A B

translates to: A += B ;

keyword name: SUBTRACT

keyword symbol: -

what it does: subtracts two values

syntax: - A B

translates to: A -= B ;

keyword name: MULTIPLY

keyword symbol: *

what it does: multiply two values

syntax: * A B

translates to: A *= B ;

keyword name: DIVIDE / DIV

keyword symbol: /

what it does: division

syntax: / A B

translates to: A /= B ;

NOTE: this does div or divide depending on what A is ( IE float or int type token).

keyword name: MOD

keyword symbol: %

what it does: modulus

syntax: % A B

translates to: A = A % B ;

keyword name: INC

keyword symbol: ++

what it does: increment

syntax: ++ A

translates to: A++;

keyword name: DEC

keyword symbol: --

what it does: decrement

syntax: -- A

translates to: A--;

--------------------------------------------------------------------------------------------------------------------

If then else statments

--------------------------------------------------------------------------------------------------------------------

keyword name: IF

keyword symbol: ?

what it does: if statement

syntax: ? A

// code block goes here

. / / a preiod ends the code block

translates to: if ( A )

{

// code block

}

NOTE: the period is required at the end of the statement block, even if there are no statments or just one statement !

keyword name: ELSEIF

keyword symbol: e?

what it does: a non-last else in an "if then else" statement

syntax: e?

translates to: else

use it before the second and subsequent else-ifs in an if-then-else statement.

exaample: == A B // if a == b

/ code block

.

e? // else

!= A C // if a != c

/ code block

.

el // else

/ code block

.

keyword name: ELSE

keyword symbol: el

what it does: last else in an "if then else" statement

syntax: el

/ code block

.

translates to:

else

{

// code block

}

NOTE: the period is required at the end of the code block, even if there are no statments or just one statement !

example: == A B

/ code block

.

el

/ code block

.

keyword name: DOUBLE EQUALS

keyword symbol: ==

what it does: compares two values to see if they are equal

syntax: == A B

// code block goes here

. / / a preiod ends the statement block

translates to: if ( A == B )

{

// code block

}

NOTE: the period is required at the end of the statement block, even if there are no statments or just one statement !

keyword name: NOT EQUAL

keyword symbol: !=

what it does: compares two values to see if they are unequal

syntax: != A B

/ code block

.

translates to: if ( A !+ B )

{

// code block

}

NOTE: the period is required at the end of the statement block, even if there are no statments or just one statement !

keyword name: GREATER THAN

keyword symbol: >

what it does: compares two values to see if one is greater

syntax: > A B

/ code block

.

translates to: if ( A > B )

{

// code block

}

NOTE: the period is required at the end of the statement block, even if there are no statments or just one statement !

keyword name: LESS THAN

keyword symbol: >

what it does: compares two values to see if one is lesser

syntax: < A B

/ code block

.

translates to: if ( A < B )

{

// code block

}

NOTE: the period is required at the end of the statement block, even if there are no statments or just one statement !

keyword name: GREATER THAN OR EQUAL

keyword symbol: >=

what it does: compares two values to see if one is greater than or equal to the other

syntax: > = A B

/ code block

.

translates to: if ( A >= B )

{

// code block

}

NOTE: the period is required at the end of the statement block, even if there are no statments or just one statement !

keyword name: LESS THAN OR EQUAL

keyword symbol: <=

what it does: compares two values to see if one is lesser than or equal to the other

syntax: < = A B

/ code block

.

translates to: if ( A <= B )

{

// code block

}

NOTE: the period is required at the end of the statement block, even if there are no statments or just one statement !

keyword name: STRING EQUALS

keyword symbol: s=

what it does: ccompares two strings

syntax: S= A B

/ code block

.

translates to: if ( strcmp( A, B) == 0 )

{

// code block

}

NOTE: the period is required at the end of the statement block, even if there are no statments or just one statement !

--------------------------------------------------------------------------------------------------------------------

Switch statements

--------------------------------------------------------------------------------------------------------------------

Keyword name: SWITCH

Keyword symbol: sw

What it does: switch statement

Syntax: sw A

ca B

/ code block

.

ca C

/ code block

.

ca D ......

.

Translates to: switch( A )

{

case B:

// code block

break;

case C:

// code block

break;

case D:

.....

}

Example: sw menu(3)

ca 1

c newgame

.

ca 2

c loadgame

.

ca 3

ret

.

switch(menu(3))

{

case 1: newgame();

break;

case 2: loadgame();

break;

case 3: return;

break; // a break; statement gets generated for each case statement automatically.

// in this case its redundant, but its ok, because its still legal syntax.

}

Keyword name: CASE

Keyword symbol: ca

What it does: case statement

Syntax: sw A

ca B

/ code block

.

ca C

/ code block

.

ca D ......

.

Translates to: switch( A )

{

case B:

// code block

break;

case C:

// code block

break;

case D:

.....

}

Example: sw menu(3)

ca 1

c newgame

.

ca 2

c loadgame

.

ca 3

ret

.

switch(menu(3))

{

case 1: newgame();

break;

case 2: loadgame();

break;

case 3: return;

break; // a break; statement gets generated for each case statement automatically.

// in this case its redundant, but its ok, because its still legal syntax.

}

--------------------------------------------------------------------------------------------------------------------

Do loop statemements

--------------------------------------------------------------------------------------------------------------------

Keyword name: DO

Keyword symbol: do

What it does: a do loop

Syntax: do A

// code block goes here

.do

Translates to: do

{

// code block goes here

}

while ( A );

Example: = quitgame 0

do !quitgame

c input

c update

c render

.do

quitgame=0;

do

{

input();

update();

render();

}

while ( !quitgame );

Keyword name: END DO

Keyword symbol: .do

What it does: ends a do loop

Syntax: do A

/ code block

.do

Translates to: do

{

// code block

}

while ( A );

Example: = a 0

do !eof(f)

cr var[a] readfileint f

++ a

.do

a=0;

do

{

var[a]=readfileint(f);

a++;

}

while (!eof(f));

--------------------------------------------------------------------------------------------------------------------

While statements

--------------------------------------------------------------------------------------------------------------------

keyword name: WHILE

keyword symbol: wh

what it does: while loop

syntax: wh A

/ code block

.

translates to: while ( A )

{

// code bock

}

NOTE: the period is required at the end of the code block, even if there are no statments or just one statement !

example: wh !quitgame

/ main game loop code block goes here

.

--------------------------------------------------------------------------------------------------------------------

For loop statements

--------------------------------------------------------------------------------------------------------------------

keyword name: FOR

keyword symbol: 4

what it does: a for loop

syntax: 4 A B

/ code block

.

NOTE: the period is required at the end of the code block, even if there are no statments or just one statement !

translates to: for ( A=0; A < B; A ++ )

{

/ code block

}

example: 4 a max_entities

c update_each a

.

for (a=0; a

{

update_each(a);

}

--------------------------------------------------------------------------------------------------------------------

Flow control statements

--------------------------------------------------------------------------------------------------------------------

Keyword name: END ( code block )

Keyword symbol: . ( period )

What it does: adds the close squiggly at the end of a code block.

The END symbol (period) is used by many CScript statements that use code blocks.

It can also be used alnoe to inject a closed squiggly into the C++ output file if desired.

Syntax: .

Translates to : }

Example: 4 a 5

c somefunc

. / END code block

for (a=0; a<5; a++)

{

somefunc();

} // this squiggly is generated by the END symbol (a period).

Keyword name: CONTINUE

Keyword symbol: >>

What it does: inserts a continue; statement

Syntax: >>

Translates to: continue;

Example: 4 a maxtgts

? !tgt[a].active

>>

.

// do some stuff with tgt a

.

for (a=0; a

{

if ( ! tgt[a].active )

{

continue;

}

// do some stuff with tgt a

}

Keyword name: BREAK

Keyword symbol: brk

What it does: inserts a break; statement into the C++ code generated.

Syntax: brk

Translates to: break;

Example: 4 i 0 maxtgts

? !tgt.active

brk

.

' CScript comment line. i is now the index of the first inactive target.

// C++ comment line. i is now the index of the first inactive target.

for (i=0; i

{

if ( ! tgt.active )

{

break;

}

}

// C++ comment line. i is now the index of the first inactive target.

Note that the Cscript comment line does not appear in the C++ output file.

Keyword name: RETURN

Keyword symbol: ret

What it does: inserts a return() call in the C++ optut file

Syntax: ret - or - ret A

where A is an optional return value.

Translates to: return; if "ret" appears by itself on the line.

return ( A ); if a token "A " appears after the "ret" keyword.

Example: fn v movetgt i ID

? !tgt[ID].active

ret

.

' tgt is active, so move it accrding to game specific "flight model"

// TODO: code goes here

.

void movetgt( int ID )

{

if ( !tgt[ID].active )

{

return;

}

// TODO: code goes here

}

--------------------------------------------------------------------------------------------------------------------

Function statements

--------------------------------------------------------------------------------------------------------------------

keyword name: FUNCTION

keyword symbol: fn

what it does: declares a function

syntax: fn type1 A type2 B type2 C ....

/ code block

.

where type1 can be: v for void, i for int, or f for float,

and type2 can be i for int, f for f loat, or c for char.

A is the funciton name. B, C, etc are parameter names

line length is the only limit on the nunber of paramters.

NOTE: the period is required at the end of the code block, even if there are no statments or just one statement !

translates to: void | float | int A ( int | float | char B, int | float | char C, ... )

{

// code block

}

examples:

fn v myfunc i myint f myfloat c *mystring

/ code block

.

void myfunc ( int myint, float myfloat, char *mystring )

{

// code block

}

fn i myfunc i myint f myfloat c *mystring

/ code block

.

int myfunc ( int myint, float myfloat, char *mystring )

{

// code block

}

fn f myfunc i myint f myfloat c *mystring f x f y f z

/ code block

.

float myfunc ( int myint, float myfloat, char *mystring , float x,float y,float z)

{

// code block

}

Keyword name: CALL

Keyword symbol: c

What it does: calls a function

Syntax: c A [ B C D .... ]

where A is the function name, and B, C, etc are optional parameters.

Translates to: A(B,C,D...);

Example: c update_each cur_entity

update_each(cur_entity);

Keyword name: CALL WITH RETURN

Keyword symbol: cr

What it does: calls a function that returns a value

Syntax: cr A B [ C D .... }

where A is the variable to receive the return value, B is the function name, and C, D, etc are optional parameters.

Translates to: A = B ( C, D, .... );

Example: cr y heightmap x z

y=heightmap(x,z);

--------------------------------------------------------------------------------------------------------------------

String manipulation statements

--------------------------------------------------------------------------------------------------------------------

Keyword name: SET STRING

Keyword symbol: ss

What it does: strcpy

Syntax: ss A B

Translates to: strcpy_s( A, 100, B );

NOTE : A and B are expected to be tokens of type char[100]

Example: ss menu[0] "File exists - overwrite?"

ss menu[1] "Yes"

ss menu[2] "No"

== menu(2) 2

ret

.

strcpy_s(menu[0],100,"File exists -overwrite?");

strcpy_s(menu[1],100,"Yes");

strcpy_s(menu[2],100,"No");

if (menu(2)==2)

{

return;

}

Keyword name: STRING ADD

Keyword symbol: s+

What it does: concatenate two strings together

Syntax: s+ A B

where A and B are tokens that reslove to type char[100]

Translates to: strcat_s( A, 100, B )

Example: s s s2

ss s "Health: "

c i2s item_health s2

s+ s s2

tx 700 400 s

char s[100], s2[100];

strcpy_s(s,100,"Health: ");

i2s(item_health,s2); // convert int to string

strcat_s(s,100,s2);

Ztext3d(700,400,s); // display string

In this example, i2s and Ztext3d are routines in the Z3D game library.

The "tx" keyword on the last line of CScript code is part of the Cscript langauge extenstions for the Z3D game library.

--------------------------------------------------------------------------------------------------------------------

CScript language extenstions for DirectX

--------------------------------------------------------------------------------------------------------------------

Keyword name: V3

Keyword symbol: v3

What it does: declares a D3DXVECTOR3

Syntax: v3 A B C .....

Translates to: D3DXVECTOR3 A, B, C, ..... ;

NOTE D3DXVECTOR3 is a data structure defined in the D3DX library in DirectX .

Examples: v3 v

D3DXVECCTOR3 v;

// used in a struct declaration....

st axes

v3 fwd up right

.st

struct axes

{

D3DXVECTOR3 fwd, up, right;

};

Keyword name: V4

Keyword symbol: v4

What it does: declares a D3DXVECTOR4

Syntax: v4 A B C .....

Translates to: D3DXVECTOR4 A, B, C, ..... ;

NOTE D3DXVECTOR4 is a data structure defined in the D3DX library in DirectX .

Examples: v4 v

D3DXVECCTOR4 v;

// used in a struct declaration....

st homogeneous_axes

v3 fwd up right

.st

struct homogeneous_axes

{

D3DXVECTOR4 fwd, up, right;

};

Keyword name: MATRIX

Keyword symbol: mat

What it does: declares a D3DXMATRIX

Syntax: mat A B C .....

Translates to: D3DXMATRIX A, B, C, ...... ;

NOTE D3DXMATRIX is a data structure defined in the D3DX library in DirectX .

Example: mat m1 m2

D3DXMATRIX m1, m2;

--------------------------------------------------------------------------------------------------------------------

CScript langauage extensions for the Z3D Game Library

--------------------------------------------------------------------------------------------------------------------

Keyword name: LOWER LIMIT

Keyword symbol: min

What it does: limits an integer variable to a minimum integer value, basically a floor function.

Syntax: min A B

where A and B are integer type tokens

Translates to: a function call to llim(&A, B), whch implements: if ( A < B ) A = B ;

Note: llim() is part of the Z3D game library.

Example: -= heath damage ' health -=damage;

min health 0 ' llim (&health,0); implements ===> if (health < 0) health = 0;

== health 0 ' if (health==0) {

// He's dead Jim!

. ' }

Keyword name: UPPER LIMIT

Keyword symbol: max

What it does: limits an integer variable to a maximum integer value, basically a ceiling function.

Syntax: max A B

where A and B are integer type tokens

Translates to: a function call to ulim(&A, B), whch implements: if ( A > B ) A = B ;

Note: ulim() is part of the Z3D game library.

Example: += heath heal_amnt ' health += heal_amnt;

min health 0 ' llim (&health,0); implements ===> if (health < 0) health = 0;

== health 0 ' if (health==0) {

// He's dead Jim!

. ' }

Keyword name: LIMIT

Keyword symbol: lim

What it does: limits an integer variable to an integer range, basically a floor and ceiling function all in one.

Syntax: max A B C

where A , B, and C are integer type tokens.

Translates to: a function call to limit(&A, B,C), whch implements: if ( A < B ) A = B ; if ( A > C ) A = C ;

Note: limit() is part of the Z3D game library.

Example: += spd delta // delta can be negative!

lim spd 0 maxspd

spd+=delta;

limit(&spd,0,maxspd); // implements : if (spd<0) spd=0; if (spd>maxspd) spd=maxspd;

Keyword name: GETMOUSE

Keyword symbol: gm

What it does: gets current mouse state

Syntax: gm A B C

where A, B, and C resolve to pointers to ints.

Translates to: Zgetmouse(&A, &B, &C); x=A. y=B. C: 1=Lbutton 2= Rbutton 3=both 0=none.

Note: Zgetmouse is part of the Z3D game library.

Example: gm &x &y &b

== b 1

tx x y "You clicked here!"

.

Zgetmouse(&x,&y,&b);

if (b == 1)

{

Ztext3d(x, y, "You clicked here!");

}

Keyword name: TEXT

Keyword symbol: tx

What it does: displays text

Syntax: tx X Y S

Translates to: Ztext3d( X, Y, S );

where X,Y are the screen coordinates, and S is a string.

Example: tx 700 400 "Hello world!"

Ztext3d(x,y,"Hello world!");

Keyword name: NEWMENU

Keyword symbol: m0

What it does: initilaizes the Z3D menu system.

Syntax: m0 A

where A resolves to a string. A is the menu title / prompt for the new menu.

Translates to: Znewmenu(A);

Example: m0 "Main menu:"

m+ "New game"

m+ "Load game"

m+ "Quit"

sw menu(3)

ca 1

c newgame

.

ca 2

c loadgame

.

ca 3

= quit 1

.

.

Znewmenu("Main menu:");

Zaddmenu("New game");

Zaddmenu("Load game");

Zaddmenu("Quit");

switch ( menu(3) )

{

case 1: newagme();

break;

case 2: loadgame();

break;

case 3: quit=1;

break;

}

Keyword name: ADDMENU

Keyword symbol: m+

What it does: adds a menu option string to the Z3D menu system

Syntax: m+ A

where A resolves to a string. A is the menu option text.

Translates to: Zaddmenu(A);

Example: m0 "Main menu:"

m+ "New game"

m+ "Load game"

m+ "Quit"

sw menu(3)

ca 1

c newgame

.

ca 2

c loadgame

.

ca 3

= quit 1

.

.

Znewmenu("Main menu:");

Zaddmenu("New game");

Zaddmenu("Load game");

Zaddmenu("Quit");

switch ( menu(3) )

{

case 1: newagme();

break;

case 2: loadgame();

break;

case 3: quit=1;

break;

}

Keyword name: GETSTRING

Keyword symbol: gs

What it does: gets string input

Syntax: gs A B

Translates to: Zgetstring(A, B);

where A and B resolve to strings. A is the prompt string, and B is the retrn value (the string entered by the user).

NOTE: Zgetstring is part of the Z3d game library.

Example: s item_name s

gs "Enter a name..." item_name

ss s "You entered "

s+ s item_name

tx 700 400 s

char item_name[100], s[100];

Zgetstring("Enter a name...", item_name);

strcpy_s(s,100,"You entered ");

strcat(s,100,item_name);

Ztext3d(700,400,s);

Keyword name: MESSAGE

Keyword symbol: msg

What it des: diplays a one line message. waits for the user to click "Ok".

Syntax: msg A

where A resolves to a string.

Translates to: Zmsg2( A );

NOTE: Zmsg2 is part of the Z3D game library.

Example: ? !filefound(s)

msg "Fiel not found!"

ret

.

if ( ! filefound( s) )

{

Zmsg2("File not found!");

return;

}

Keyword name: NOBUTON

Keyword symbol: nb

What it des: waits until no mouse buttons are pressed

Syntax: nb

Translates to: nobtton();

NOTE: nobutton is part of the Z3D game library.

Example: tx 700 400 "Click to continue..."

nb

p

Ztext3d(700,400,"Click to contine...");

nobutton(); // wait for no button, in case they're still holding one down.

pause(); // wait for a mosue click

Keyword name: PAUSE

Keyword symbol: p

What it des: waits for a mouse click

Syntax: p

Translates to: pause();

NOTE: pause() is part of the Z3D game library.

Example: tx 700 400 "Click to continue..."

nb

p

Ztext3d(700,400,"Click to contine...");

nobutton(); // wait for no button, in case they're still holding one down.

pause(); // wait for a mosue click

keyword name: ISIN

keyword symbol: in

what it does: checks if a 2d point IS IN a rectangle

syntax: is A B C D E F

/ code block

.

translates to: if ( isin( A,B,C,D,E,F ) )

{

// code block

}

NOTES:

1. the period is required at the end of the statement block, even if there are no statments or just one statement !

2. the isin function is part of the Z3D game library

keyword name: KEYPRESSED

keyword symbol: kb

what it does: check for a key being pressed

syntax: kb A

/ code block

.

where A is a vitrual keycode

translates to: if ( ZKeypressed( A ) )

{

// code block

}

NOTES:

1. the period is required at the end of the statement block, even if there are no statments or just one statement !

2. the Zkeypressed function is part of the Z3D game library.

Z3D String manipulator keywords ----------------------------------------------------------------------------------------

The String Manipulator in the Z3D game library implements a 1000 character

string "register" with get, set, add string, add int, and add float operations.

Its a handy tool for building up strings of text for display.

Keyword name: SET STRING ( string manipulator )

Keyword symbol: Ss

What it des: Sets the string manipulator to a value

Syntax: Ss A

where A is a string type token.

Translates to: Ss( A );

NOTE: Ss() is part of the string manipulator API in the Z3D game library.

Example: f fps

Ss ""

Saf fps

Sa " fps"

tx 700 400 S

float fps;

Ss(""); // set string a manipulator to "". IE clear it.

Saf(fps); // convert fps to string and concatenate onto the end of the string manipulator string

Sa(" fps"); // concatenate " fps" onto the end of the string manipulator string

Ztext3d(400,700,S); // display the string manipulator string "S".

Keyword name: STRING ADD ( string manipulator )

Keyword symbol: Sa

What it des: concatenates a string onto the end of the string manipulator string

Syntax: Sa A

where A is a string type token.

Translates to: Sa( A );

NOTE: Sa() is part of the string manipulator API in the Z3D game library.

Example: f fps

Ss ""

Saf fps

Sa " fps"

tx 700 400 S

float fps;

Ss(""); // set string a manipulator to "". IE clear it.

Saf(fps); // convert fps to string and concatenate onto the end of the string manipulator string

Sa(" fps"); // concatenate " fps" onto the end of the string manipulator string

Ztext3d(400,700,S); // display the string manipulator string "S".

Keyword name: STRING ADD INT ( string manipulator )

Keyword symbol: Sai

What it des: converts an integer to a string, then concatenates it onto the end of the string manipulator string

Syntax: Sai A

where A is an integer type token.

Translates to: Sai( A );

NOTE: Sai() is part of the string manipulator API in the Z3D game library.

Example: i hp;

Ss ""

Sai hp

Sa " hit points"

tx 700 400 S

int hp;

Ss(""); // set string a manipulator to "". IE clear it.

Sai(hp); // convert hp to string and concatenate it onto the end of the string manipulator string

Sa(" hitpoints"); // concatenate " hit points" onto the end of the string manipulator string

Ztext3d(400,700,S); // display the string manipulator string "S".

Keyword name: STRING ADD FLOAT ( string manipulator )

Keyword symbol: Saf

What it des: converts a float to a string, then concatenates it onto the end of the string manipulator string

Syntax: Saf A

where A is a float type token.

Translates to: Saf( A );

NOTE: Saf() is part of the string manipulator API in the Z3D game library.

Example: f fps

Ss ""

Saf fps

Sa " fps"

tx 700 400 S

float fps;

Ss(""); // set string a manipulator to "". IE clear it.

Saf(fps); // convert fps to string and concatenate onto the end of the string manipulator string

Sa(" fps"); // concatenate " fps" onto the end of the string manipulator string

Ztext3d(400,700,S); // display the string manipulator string "S".

Z3D Matrix Manipulator keywords --------------------------------------------------------------------------------------------------------

The Matrix Manipulator in the Z3D game library implements a D3DXMATRIX

"register" with operations like get, set, clear, scale, rotate, translate, and transform vertex.

Its handy for concatenating matrices together for drawing or transforming points.

Keyword name: Mstart

Keyword symbol: M0

What it does: sets the Matrix Manipulator to identity.

Syntax: M0

Translates to: Mstart();

Example: mat mWorld

M0

Ms 1.0f 1.5f 2.5f

Mrr 0 item.xr

Mrr 1 item.yr

Mm item.x item.y item.z

= mWorld Mmat

D3DXMATRIX mWorld;

Mstart();

Mscale(1.0f,1.5f,2.5f); // scale mesh

MrotateRADS(0,item.xr); // rotate around world axis zero ( the x axis)

MrotateRADS(1,item.yr); // rotate around world axis one ( the y axis)

Mmove(item.x, item.y, item.z); // move to items location in the world

mWolrd=Mmat; // set mWorld to the matrix manipulator's matrix

Keyword name: Mscale

Keyword symbol: Ms

What it does: post-multiplies the Matrix Manipulator matrix by a scaling matrix

Syntax: Ms A B C

where A B C are the x,y,z scaling values and are float tokens .

Translates to: Mscale(A, B, C);

Example: mat mWorld

M0

Ms 1.0f 1.5f 2.5f

Mrr 0 item.xr

Mrr 1 item.yr

Mm item.x item.y item.z

= mWorld Mmat

D3DXMATRIX mWorld;

Mstart();

Mscale(1.0f,1.5f,2.5f); // scale mesh

MrotateRADS(0,item.xr); // rotate around world axis zero ( the x axis)

MrotateRADS(1,item.yr); // rotate around world axis one ( the y axis)

Mmove(item.x, item.y, item.z); // move to items location in the world

mWolrd=Mmat; // set mWorld to the matrix manipulator's matrix

Keyword name: Mrotate

Keyword symbol: Mr

What it does: post-multiplies the Matrix Manipulator matrix by a rotation matrix

Syntax: Mr A B

where A is the world axis of rotation ( 0=x, 1=y, 2=z) and B is the integer rotation amount in degrees.

Translates to: Mrotate(A, B);

Example: mat mWorld // delare a matrix mWorld

M0 // set the matrix maanipulator to identity

Ms 10.0f 15.0f 25.0f // scale the mesh

Mr 0 tgt.angle // rotate around world x by "downward inclination angle"

Mr 1 tgt.heading // rotate around world y by "compass heading in degrees"

Mm tgt.x tgt.y tgt.z // move to target's location in the world

= mWorld Mmat // set mWolrd to the matrix manipulator's matrix.

D3DXMATRIX mWorld;

Mstart();

Mscale(10.0f,15.0f,25.0f); // scale mesh

Mrotate(0,tgt.angle); // rotate around world axis zero ( the x axis)

Mrotate(1,tgt.heading); // rotate around world axis one ( the y axis)

Mmove( tgt.x, tgt.y, tgt.z ); // move to target's location in the world

mWolrd=Mmat; // set mWorld to the matrix manipulator's matrix

Keyword name: MrotateRADS

Keyword symbol: Mrr

What it does: post-multiplies the Matrix Manipulator matrix by a rotation matrix

Syntax: Mrr A B

where A is the world axis of rotation ( 0=x, 1=y, 2=z) and B is the floating point rotation amount in radians.

Translates to: MrotateRADS(A, B);

Example: f x y z

M0

Ms 1.0f 1.5f 2.5f

Mrr 0 item.xr

Mrr 1 item.yr

Mm item.x item.y item.z

= x 0.0f

= y 0.0f

= z 10.0f

Mt &x &y &z

// x,y,z is now a point 10 units in front of the item in the world.

float x,y,z;

Mstart();

Mscale(1.0f,1.5f,2.5f);

MrotateRADS(0,item.xr); // rotate around world axis zero ( the x axis)

MrotateRADS(1,item.yr); // rotate around world axis one ( the y axis)

Mmove(item.x, item.y, item.z);

x=0.0f;

y=0.0f;

z=10.0f;

Mtrans(&x,&y,&z); // transform x,y,z by the Matrix Manipulator matrix

// x,y,z is now a point 10 units in front of the item in the world.

Keyword name: Mmove

Keyword symbol: Mm

What it does: post-multiplies the Matrix Manipulator matrix by a translation matrix

Syntax: Mm A B C

where A , B, and C are the amounts to translate in x, y, and z. A, B, and C are expected to be float type tokens.

Translates to: Mmove(A, B,C);

Example: mat mWorld // delare a matrix mWorld

M0 // set the matrix maanipulator to identity

Ms 10.0f 15.0f 25.0f // scale the mesh

Mr 0 tgt.angle // rotate around world x by "downward inclination angle"

Mr 1 tgt.heading // rotate around world y by "compass heading in degrees"

Mm tgt.x tgt.y tgt.z // move to target's location in the world

= mWorld Mmat // set mWolrd to the matrix manipulator's matrix.

D3DXMATRIX mWorld;

Mstart();

Mscale(10.0f,15.0f,25.0f); // scale mesh

Mrotate(0,tgt.angle); // rotate around world axis zero ( the x axis)

Mrotate(1,tgt.heading); // rotate around world axis one ( the y axis)

Mmove( tgt.x, tgt.y, tgt.z ); // move to target's location in the world

mWolrd=Mmat; // set mWorld to the matrix manipulator's matrix

Keyword name: Mtrans

Keyword symbol: Mm=t

What it does: transforms a 3d point by the matrix manipulator's matrix.

Syntax: Mt A B C

where A , B, and C are the x,y,z coordinates of the point. A, B, and C are expected to be float type tokens.

Translates to: Mtrans(&A, &B,&C);

Example: f x y z

M0

Ms 1.0f 1.5f 2.5f

Mrr 0 item.xr

Mrr 1 item.yr

Mm item.x item.y item.z

= x 0.0f

= y 0.0f

= z 10.0f

Mt &x &y &z

// x,y,z is now a point 10 units in front of the item in the world.

float x,y,z;

Mstart();

Mscale(1.0f,1.5f,2.5f);

MrotateRADS(0,item.xr); // rotate around world axis zero ( the x axis)

MrotateRADS(1,item.yr); // rotate around world axis one ( the y axis)

Mmove(item.x, item.y, item.z);

x=0.0f;

y=0.0f;

z=10.0f;

Mtrans(&x,&y,&z); // transform x,y,z by the Matrix Manipulator matrix

// x,y,z is now a point 10 units in front of the item in the world.