uptaded the 5th of june 2006

Architecture of the Torque script

This document is based on the demonstartion starter.fps and racing.fps. The organisation of the script is used as a basis od the architecture script.

Target

This user guide explains the Torque script architecture and how to customise the code when several missions are used.

To do that in an effcient way it is important to know how the scripts are organised in order to put the right information at the right place and avoid redoundancy.
One of the other point to take into account , it is the load and end of the mission , the risk after several missions is to overlaod the memory with script and data as terrain, shape, texture , ... and slow down the game until it is impossible to play.

The folowing chapters describe step by step the different level of the architecture , all the programs, functions listed could be updated in order to get the result excpected.

Architecture level 0 : launch the game from Opertaing System

This describes the main functions used to put in place the game environment.
In this part you have to put in place what is common to all the game and could be reused at any time in the game.

Architecture level 1 : Torque game environment

The scripts launched (and consequently functions laoded ) are common to all the game.
It is in this part that the client/server should be customised.

Architecture level 2 : client server base initialisation

Architecture level 3 : the main menu

Architecture level 4 : load the mission

Architecture level 5 : the game

Architecture level 0 : launch the game from Opertaing System

$mod = name of the directory where the scripts and data of the game are stored.

The user launched the script below in unix window :

./runtorque.sh :

The environment is set and the parameters are controlled

./torqueDemo.bin -nohomedir

./main.cs : is automatically called by torqueDemo.bin, the folowing code is launched by main.cs

This variables managed the game and the mod to load

$defaultGame = "game";
name of the main mod

$userMods = "creator;" @ $defaultGame;

You can add mod to this variable or remove if needed. DeafultGame should be the last one.

"creator" should be removed when the final version of the game is released.

This script is done to launch a torque game whatever the game is , also no customisation are needed at this level, only parameters could be set as :

-Open a separate console

-Logging behavior
-Saving event game play log into journal
-Play back a journal

Loaddir("common")

Execute the main.cs script in the directory send in parameters

Loadmods($usermods)

this function excutes all the "mains.cs" scripts belonging to the directory set in $userMods

onStart()

this function call all the onStart() function belonging to $userMods/main.cs at the condition that the function onStart() in the $userMods/main.cs are declared as "Parent::onStart()".

Torque is launched and wait for the events ( mouse, click , keyboard , scheduler, .... )

The events are defined in the script launched by the onStart() function below.

Architecture level 1 : Torque game environment

All the scripts are launch by loaddir and loadmod.

The list of scripts launched is done by ./main.cs script.

./common/main.cs

This function load the function needed to manage the client/server

OnStart() : parent of Onstart() in ./main.cs

This function load the very basic functions used everywhere in order :

to manage the dialog (GUI).
to manage the audio

onExit() : parent of onExit() in ./main.cs

Save different parameters in common. But It seems redundant with game. I don't understand very well.

./game/main.cs

list of main scripts launched :

./client/defaults.cs

the default value of parameters specific to the client are loaded in memory.

./server/defaults.cs

the default value of parameters specific to the server are loaded in memory.

./client/prefs.cs

the value of parameters specific to the client to save at the end of the game are loaded in memory.
This parameters could supersseed the ./client/defaults.cs

./server/prefs.cs

The value of parameters specific to the server to save at the end of the game are loaded in memory.
This parameters could supersseed the ./server/defaults.cs

activagepackage() {

on start()

./client/init.cs
./server/init.cs
./data/init.cs
$mod/server/init.cs initServer()
if ($Server::Dedicated)
initDedicated()
else
$mod/client/init.cs initClient()

The function initServer and initClient are launched

on exit()

   save ./client/prefs.cs
   save ./client/config.cs
   save ./server/prefs.cs
   save ./server/banlist.cs

}

./creator.main.cs

OnStart() : parent of Onstart() in ./main.cs

This function load the functions used by the Torque editor

This function could be updated in order to improve the editor.

Architecture level 2 : client server base initialisation

The function initServer and initClient are launched by the OnStart function

$mod/server/init.cs

$mod/server/init.cs initServer()

Initialise the server : it is just the basement. The hosting of the game is done later on.
If you have only one mission the scripts could be loaded at this stage. But in case of several missions you have to do it later and the call of the scripts relative to the mission shouled be put in comment.

$mod/client/init.cs

$mod/client/init.cs initClient()

Initialise :

-The client basement. The connection to teh server is done later on

-The GUI game environement.
-The configuration and parameters of the client are loaded as saved last time.

If you have only one mission the scripts could be loaded at this stage. But in case of several missions you have to do it later and the call of the scripts relative to the mission shouled be put in comment.

If $JoinGameAddress is set the client connect directly to the game and the main menu is displayed.
If it is not the case the GUI to choose the game host , or join server is displayed => loadStartup() is launched

$mod/client/init.cs loadMainMenu()

This function call the MainMenuGui.gui scripts

$mod/data/init.cs

Data common to all the game could be downloaded

$mod/client/ui/StartUpGui.gui

The function loadStartup() displayed a picture during a period of time and launch the main menu

Customise this function if you want to change the splash screen displayed when the game starts.

Architecture level 3 : the main menu

This level displays the main menu GUI used by the players and launch the different actions in order :

to host a game,
or to connect to a hosted game
or to play solo.

$mod/client/ui/MainMenuGui.gui

$mod/client/ui/JoinServerGui.gui

$mod/client/ui/optionsDlg.gui

$mod/client/ui/startMissionGui.gui

This program display the list of mission that could be loaded.

$mod/client/ui/startMissionGui.gui SM_start()

This function is updated in order to load and start the mission selected

Architecture level 4 : load the mission

$mod/client/StartMisssion.cs startMissionGame

This new program is created in order to load and start the mission in different context :

- from a menu
- after an event during the game : the new mission is loade automatically in function of an event in the game ( a trigger )

This function delete the context of the previous mission and create the new one

$mod/client/StartMisssion.cs startMissionInit

This function initilaise and load the .cs file specific to use by the game :

/client/scripts/" mission selected "/mission.cs" ;
/server/scripts/" mission selected "/mission.cs" ;

The scripts specifics to the mission should be stored into a directory with the same name than the name of the mission file.

$mod/client/StartMisssion.cs startMissionSchedule

This function should be used to launch the game after an event. The "startMissionGame" is scheduled.

Architecture level 5 : the game

All the actions of the players on the game are based on 2 principles :

the actions on the keyboard, mouse
the triggers

$mod/client/scripts/default.bind.cs

The player actions on key or mouse call spefici function defined in this scripts

$mod/server/scripts/"mission"/mission.cs"

this script calls the other scripts needed by the missions

$mod/server/scripts/"mission"/* when the scripts are specific to a mission

$mod/server/scripts/* when the scripts are common to all the missions.

The trigger is started automatically by the core torque in function of events.
The trigger could be associated to one of the datablocks defined with the editor or defined manually when they are the moving objects or characters or AI or ...

If a new mission should be lauched , depending on the context, the function tiggered should be updated in order to call the mission to load :

$mod/client/StartMisssion.cs startMissionSchedule("mission")