John Cletheroe's
Trainz Hintz - A Step-By-Step Guide To Making A Very Simple TRS2004 Scenario

TRS2004 Scenario Creation Tutorial - Part Sixteen: Some More GameScript/TrainzScript Functions And Facilities To Explore

This final section of the main tutorial briefly lists some of the numerous other GameScript/TrainzScript functions and facilities which can be used in scenarios. Details of their syntax, parameters and usage can be found in the TRS2004 API but in some cases considerable experimentation may be required in order to discover the best way to make use of them.

These features are listed here very roughly in order of how often they are likely to be used in scenarios and how advanced they are. The later entries in this section of the tutorial are really intended to whet your appetite for the huge range of possibilities offered by GameScript/TrainzScript.

World.SetGameTime
Set the time as displayed by the scenario. 0 is noon; 0.125 is 3pm; 0.25 is 6pm and so on until 0.875 is 9am and 1 is Noon again. This function has no effect on the computer's system clock.

World.SetCameraAngle
Set the external camera angles and distance. This function must be preceded by World.SetCamera. Angles are specified in degrees if they are integers, or as radians if they are floating point, which is extremely confusing. A radian is slightly less than 60 degrees. To convert from degrees to radians multiply by 3.1415926 / 180 (i.e. pi/180). A horizontal angle of 0 degrees looks at the lefthand side of the train (from the left, looking rightwards), 90 degrees at the rear of the train (from the rear, looking in the direction the train is travelling), 180 degrees at the right and 270 degrees at the front. Negative vertical angles look down from above. Positive vertical angles values look up from below, if that is possible (for example, when the train is on a bridge, embankment, ledge, etc). If it is not possible, then with positive vertical angles the camera looks along the ground horizontally. This command can be placed within a FOR loop to make the camera move.

Navigate.OnJunction
Wait for a junction event (train approaches the junction, reaches the junction, stops in the junction, etc).

Navigate.LockJunction
Change a junction's direction, and if desired prevent the user from being able to change it.

Interface.Print
Display a message to the user in the radio message box.

Interface.SetMessageWindowVisible
Show or hide the radio message box.

SetAutopilotMode
Set a train to be under the control of the scenario, the user, or Trainz.

Navigate.SetSignal
Change a signal's state. Signals are automatically changed by junctions and trains. This function overrides that default behaviour, for example it could be used to set a signal at the end of a station platform to red until the train is permitted to depart.

Navigate.Station
Handle a station stop.

GetVehicles
Get the vehicles in a train as an array. Individual vehicles can then be turned round, etc.

if (TrainUtil.IsTrainInTrigger(me, PlayerTrain, cast<Trigger> Router.GetGameObject("TRG14")) == true)
Check if any part of a train is in a trigger (without waiting until it is). In the above, "TRG14" is an example of a name of a trigger.

World.SetCamera(cast<MapObject>Router.GetGameObject("Station1"));
Point the camera at a non-train object. Only certain types of objects can be specified, including industries, junctions, and signals. In the above, "Station1" is an example. This function is useful to provide a suitable background when displaying instructions at the start of a scenario, or a message at its conclusion.

Math.Rand
Generate a random number, on which a decision or event controlled by the scenario can be based.

To set an initial speed limit at the start of a scenario, add the following statements just before setting the player train to manual control:

PlayerTrain.GetVehicles()[0].SetSpeedLimit(20 * 0.278);
Sleep(0.1);
PlayerTrain.GetVehicles()[0].SetSpeedLimit(0);

The above example sets the limit to 20kph. The multiplication by 0.278 converts kph to metres per second. This very ingenious trick is courtesy of DaveRP of the Razorback Railway.

SetCouplingMask and SetDecouplingMask
Specify whether rolling stock vehicles can be coupled and decoupled.

The GameScript/TrainzScript mini-browser facility provides a means of displaying a large text box in a scenario. A very limited range of HTML tags can be used to format the text.

AddHandler
Set up a mechanism which will cause a handler function to be obeyed when a specified event occurs. This is extremely useful for controlling asynchronous operations such as the movements of AI trains. When coding AddHandler functions, do not include any unnecessary spaces as doing so can cause them to be ignored without any error messages (which is confusing and difficult to debug). Handler functions themselves should only perform operations which can be completed very quickly, because processing will be diverted from the main part of the program while they are being obeyed. Do not include the Router.PostMessage function in a handler function because that will cause a scenario to crash. Sleep and StopTrainGently functions are ignored (with no error messages) if they are included in handler functions.

Schedules are another sophisticated method of controlling the behaviour of AI trains.

SetMeshAnimationState
Open and close the doors of passenger carriages, and operate similar rolling stock vehicle animations. Only a limited range of vehicles have the animations required by this function.

A scenario can set the amount of a product being carried by a rolling stock vehicle without the vehicle having to visit an industry. This is useful in situations such as a wagon starting the scenario with a full load. A scenario can also set an industry's parameters such its input and output stock levels, consumption rates and production rates.

Internally, Trainz game objects send each other messages whenever events in which they are involved occur. These messages can be intercepted and simulated by scenario coding. These internal messages are not seen by the user. This is a very advanced concept and documentation of it in the TRS2004 API is poor. However, many of the more advanced tricks in scenarios rely on the use of this internal messaging system.

It is possible for a scenerio to accept text input from the user but I have not yet investigated how this is done.

Programming experts may wish to explore the possibilities offered by highly advanced features such as classes and threads. With sufficient skill, GameScript/TrainzScript can be made to do some extraordinary things.

This is the last section of the main part of this tutorial. It has only concentrated on the programming aspects of scenario creation but it is important to stress that the devising of an interesting and original story or driving challenge is equally if not more important. Other aspects of the scenario creation process could include the making of instruction slides using a program such as PhotoShop, and the recording of speech and sound effect audio files to be played in the scenario.

The lower part of the index to this section lists some additional articles on the subject of scenario creation which you may find of interest.

Index

Part Fifteen: Trigger Coding

Overall Site Home Page

About this personal web site JohnCletheroe

EMail me

Most recently modified 16-Apr-10