In this page we summarize all the capabilities of the scripts feature, divided by layout element type.

Signals

Signals can be referred to using the following syntax:

  • implicitly in the actions linked to the signals.
  • by specifying the signal's coordinates:   Signal(x,y)
  • by using the word "next", to refer to the next signal.
  • by using the name associated with the signal
Property Type Meaning Changeable?
aspect string Name associated to each aspect the signal can take Yes
auto number The signal is an automatic signal Yes
enabled number For automatic signals, a zero value means that the signal is in manual mode; a 1 value means that the signal is in automatic mode. Yes
switchThrown number A 1 value means that the next switch's position leads to a branch line. No
nextLimit number The value of the next speed limit that the train will see once it travels past the current signal. No
nextLength number The distance (in meters) of the next signal. No
nextApproach signal The distant signal that the train will see once it travels past the current signal. No
nextStation string The station that the train will reach once it travels past the current signal. No
redDistance number Distance in meter to the next red signal. The distance includes all cleared blocks (green signals) after the current signal. No
fleeted number Setting this value to 1, the signal is set to automatic mode. Yes
departure number Setting this value to 1, the signal is defined as a departure from station signal. Yes
click number Setting this value to any number simulates a click of the mouse on this signal. Yes
controls Track The track element controlled by this signal, that is the first element of the path protected by the signal. No
fixedred number A 1 value means that the signal has only the red aspect and cannot be changed; a zero value means that the signal's aspect can be changed by a click by the user. Yes
nopenalty number A 1 value means that no penalty points are recorded when a train is stopped by this signal being red. A zero value means that penalties are recorded. Yes
noclickpenalty number A 1 value means that no penalty points are recorded when the user changes the aspect of the signal needlessly. A zero value means that penalties are recorded. Yes
trainApproachingDistance number The distance in meters that a train getting close to the signal (in the previous block) needs to travel before reaching the signal, or -1 if there are no trains in the previous block. No
trainApproaching string The name of the train getting close to the signal (in the previous block), or the value @None if there are no trains traveling towards the signal in the previous block. No

The following actions can be associated to each signal:

Action Executed when...
OnClick: the user clicks on the signal, regardless on the current aspect of the signal.
OnCleared: the signal has been changed by the user from red to another aspect.
OnUncleared: the signal has been changed by the user from any aspect to red (if the signals is turned to red by the passage of a train, the OnCross: action is called).
OnInit: the layout is loaded for the first time.
OnRestart: the simulation has been restarted.
OnUpdate: another signal has changed its aspect.
OnAuto: the signal is being set to automatic mode.
OnCross: the signal is crossed by a train.

Trains

Trains can be referred to with the following syntax:

  • implicitly, in the actions associated with the train.
  • by specifying the train's coordinates   Train(x,y)
  • by using the name associated with the train:   Train(name)
Property Type Meaning Changeable?
name string name of the train No
status string the current state of the train. Possible values are:
ready, running, stopped, waiting, arrived, shunting, derailed, delayed		 No
type number the type of the train (from 0 to 9) No
speed number the current train speed. No
length number the train length (if set in the .sch file) No
arrived number a 1 value means the train arrived at its final destination. No
stopped number a 1 value means the train is stopped at a station. No
direction  number the train's direction (e-w = 0, w-e = 1, n-s = 16, s-n = 17). The use of other direction values is discouraged, due to internal limits of the program. No
entry  string Entry point of the train (or station of origin). No
exit  string Exit point of the train (or final destination station). No
stock  string Name of the train that will receive this train's rolling stock. No
waitfor  string Name of the train we must wait for (for example to assign the rolling stock). No
nextStation  string Name of the next station where the train will stop at. No
shunt number the train will start shunting when the value of this property is set.
(that is, it's only possible to write a value, not read it)		 Yes
wait number when a train is stopped, assigning a value to this property will defer the train's departure by the value (in seconds). This can be used to create delays in a train's schedule. This is also a write-only property. Yes
Track. track The track where the head of the train is positioned; useful to interrogate the track's properties. For example: Track.station to know the name of the station where the train is currently at. No

The following actions can be associated to each train:

Action Executed when the train...
OnEntry: enters the territory.
OnAssign: is assigned to another train.
OnStop: stops at a station.
OnStart: starts running from a station or a signal.
OnWaiting: stops at a red signal.
OnReverse: reverse its direction.
OnShunt: starts shunting.
OnMerged: this train is joined with another.
OnExit: exist from the territory
OnArrived: arrives at its final destination (without exiting from the territory)

Tracks and Switches

Tracks can be referred to with the following syntax:

  • implicitly, in the actions associated with the track.
  • by specifying the track's coordinates   Track(x,y)
  • by specifying the track's name   Track(name)
Property Type Meaning Changeable?
length number length (in meter) of the track. No
name number Name associated with the switch, or name of the station. No
color string the color of the track. Possible values:
black, white, orange, red, green, blue		 Yes
busy number a 1 value means that the track is reserved No
free number a 1 value means that the track is free (black color) No
thrown number for switches, a 1 value means that the switch is not in the straight position. No
linked element the layout element (track, signal, icon, button) linked to this element (track, signal, icon, button). No
click number Setting this value to any number simulates a click of the mouse on this track. This is especially useful to throw switches from a script. Yes
pathdir number the direction of the path cleared by the preceding signal, i.e. the direction the train will travel when crossing the track element. Valid only after the signal has been cleared. Direction values: e-w = 0, w-e = 1, n-s = 16, s-n = 17 - the use of other direction values is discouraged, due to internal limits of the program.
 No
Train. train The train that triggered the event. Only valid for the following events: OnEnter:, OnExit:, OnCrossed:, OnArrived:, OnStopped:. Useful to interrogate the train's properties. For example: Train.type to know the type of the train occupying this track element. No

The following actions can be associated to each track element:

Action Executed when...
OnInit: the scenario is loaded for the first time.
OnRestart: the simulation has been restarted.
OnSetBusy: the track is being reserved to allow a train's passage.
OnSetFree: the track is being freed (it is not reserved to allow a train's passage anymore).
OnEnter: a train enters in the track.
OnExit: a train leaves the track.
OnClicked: the user clicks on the track
OnStopped: a train stopped at this station
OnArrived: a train arrived at this (final) station

Itineraries

The itineraries can be referred to with the following syntax:

  • implicitly, in the actions associated with the itinerary.
  • by specifying the itinerary's coordinates:   Itinerary(x,y)
  • by using the itinerary's name:  Itinerary(name)
The following actions can be associated to each itinerary:

Action Executed when...
OnInit: the scenario is loaded for the first time.
OnClicked: the itinerary is activated by the user.

Triggers

Triggers can be referred to with the following syntax:

  • implicitly, in the actions associated with the trigger.
  • by specifying the trigger's coordinates:   Trigger(x,y)
Property Type Meaning Changeable?
Train. train the train that has activated the trigger No
Track. track the track that has activated the trigger No

The following actions can be associated with a trigger:

Action Executed when...
OnInit: the scenario is loaded for the first time.
OnCrossed: a train activates the trigger.

Icons

Icons are special types of "tracks", and therefore can be referenced in the same way as regular tracks:

  • implicitly in the actions associated with the icon.
  • by specifying the icon's coordinates: Track(x,y)
Property Type Meaning Changeable?
.linked signal or switch the signal or switch linked to this icon. No
.icon string name of the .xpm file with the image to show Yes

The following actions can be associated to each icon:

Action Executed when...
OnInit: the scenario is loaded for the first time.
OnClicked: the user clicked on the upper-left corner of the icon.
OnIconUpdate: An event may require updating the icon, such as when any signal on the layout has a new aspect.

Look at the "linkedImages.trk" layout included in the Train Director download package for an example on how to use icons linked to signals or switches.

 

Back to the main script page