Class Signal

API Hierarchy
- GSObject
  - GameObject
    - TrainzGameObject
    - PropertyObject
      - MeshObject
        MapObject
        Trackside
        Signal

Provides control over trackside signal objects.
Methods to get a signal's state GetSignalState() and GetSignalStateEx() can be found in the parent Trackside class.

Messages

Messages sent to and from Signal objects are listed below:

Major	Minor	Source	Destination
Signal	StateChanged	Signal	Broadcast
Train	Entered red signal	Signal	Train
Train	Entered red signal notify	Train	Broadcast

Constants

Useful Terminology

In Advance	Signal 2 is said to be "In Advance" of signal 1 if a driver at signal 1 will arrive at signal 2 later ie: signal 2 is currently ahead of him.
In Rear	Signal 1 is said to be "In Rear" of signal 2 if a driver at signal 2 has already passed signal 1 ie: signal 1 is behind him.
On	A signal is said to be "On" if it is showing it's most restrictive aspect
Off	A signal is said to be "Off" if it is showing it's least restrictive aspect

Distances

Miscellaneous Distance Constants
public define int HALF_A_CAR_LENGTH = 20	A 50m long traincar (sic)
public define int MINIMUM_SIGNAL_SPACING = 50	Signals must be placed more than 50m apart to increment state.
public define int PORTAL_LENGTH = 300	Just how far after finding a portal do we keep looking for trains? This is because users may attach track to both ends of a portal.
public define int DEFAULT_OVERLAP = 25	Default. Overridden by 'overlap' in the config.txt.

Signal States

Define the possible states for a track side signal.
For more complex states, the Extended Signal States are used.

Signal States
public define int AUTOMATIC = -1	Signal state is automatically handled by Trainz.
public define int RED = 0	Signal is red (stop state).
public define int YELLOW = 1	Signal is yellow (caution state).
public define int GREEN = 2	Signal is green (clear state).

Extended Signal States

Values specifying an extended signal state.
These are extra signal states for more specialist purposes that are defined in addition to the standard Signal States.
Note: Not all signals may necessarily support the extended signal states.

Shared States
public define int EX_STOP = 0	Extended stop state. Signal is red.
public define int EX_STOP_THEN_CONTINUE = 1	Alternative for stop - asset specific.
public define int EX_CAUTION = 4	The next signal is red.
public define int EX_ADVANCE_CAUTION = 7	The next signal is yellow.
public define int EX_PROCEED = 8	Extended proceed state. Signal is green.

Route Signalling Specific States
public define int EX_CAUTION_LEFT = 2	The next junction is left and the next signal is red.
public define int EX_CAUTION_RIGHT = 3	The next junction is right and the next signal is red.
public define int EX_CAUTION_LEFT_2 = 13	The next junction is 2nd left and the next signal is red.
public define int EX_CAUTION_RIGHT_2 = 14	The next junction is 2nd right and the next signal is red.
public define int EX_CAUTION_LEFT_3 = 15	The next junction is 3rd left and the next signal is red.
public define int EX_CAUTION_RIGHT_3 = 16	The next junction is 3rd right and the next signal is red.
public define int EX_ADVANCE_CAUTION_LEFT = 11	The next junction is left and the next signal is yellow.
public define int EX_ADVANCE_CAUTION_RIGHT = 12	The next junction is right and the next signal is yellow.
public define int EX_ADVANCE_CAUTION_LEFT_2 = 17	The next junction is 2nd left and the next signal is yellow.
public define int EX_ADVANCE_CAUTION_RIGHT_2 = 18	The next junction is 2nd right and the next signal is yellow.
public define int EX_ADVANCE_CAUTION_LEFT_3 = 19	The next junction is 3rd left and the next signal is yellow.
public define int EX_ADVANCE_CAUTION_RIGHT_3 = 20	The next junction is 3rd right and the next signal is yellow.
public define int EX_PROCEED_LEFT = 5	The next junction is left and the next signal is green.
public define int EX_PROCEED_RIGHT = 6	The next junction is right and the next signal is green.
public define int EX_PROCEED_LEFT_2 = 21	The next junction is 2nd left and the next signal is green.
public define int EX_PROCEED_RIGHT_2 = 22	The next junction is 2nd right and the next signal is green.
public define int EX_PROCEED_LEFT_3 = 23	The next junction is 3rd left and the next signal is green.
public define int EX_PROCEED_RIGHT_3 = 24	The next junction is 3rd right and the next signal is green.

Speed Signalling Specific States
public define int EX_SLOW = 9	Proceed at slow speed.
public define int EX_MEDIUM = 10	Proceed at medium speed.
public define int EX_RESTRICTED = 25	Proceed at restricted speed.
public define int EX_LIMITED = 26	Proceed at limited speed.
public define int EX_APPROACH_LIMITED = 27	Approach next signal at limited speed.
public define int EX_APPROACH_MEDIUM = 28	Approach next signal at medium speed.
public define int EX_APPROACH_SLOW = 29	Approach next signal at slow speed.
public define int EX_APPROACH_RESTRICTED = 30	Approach next signal at restricted speed.
public define int EX_LIMITED_APPROACH = 31	Proceed at Limited speed prepared to stop at next signal
public define int EX_MEDIUM_APPROACH = 32	Proceed at Medium speed prepared to stop at next signal
public define int EX_SLOW_APPROACH = 33	Proceed at Slow speed prepared to stop at next signal
public define int EX_LIMITED_APPROACH_MEDIUM = 34	Proceed at Limited speed, approach next signal at Medium speed
public define int EX_LIMITED_APPROACH_SLOW = 35;	Proceed at Limited speed, approach next signal at Slow speed
public define int EX_LIMITED_APPROACH_RESTRICTED = 36	Proceed at Limited speed, approach next signal at Restricted speed
public define int EX_MEDIUM_APPROACH_SLOW = 37;	Proceed at Medium speed, approach next signal at Slow speed
public define int EX_MEDIUM_APPROACH_RESTRICTED = 38	Proceed at Medium speed, approach next signal at Restricted speed
public define int EX_SLOW_APPROACH_RESTRICTED = 39	Proceed at Slow speed, approach next signal at Restricted speed

Methods

ApplySpeedLimitForStateEx

public void ApplySpeedLimitForStateEx(int state)

Parameters

state - One of the Extended Signal State values.

Returned Value

None

Syntax

ApplySpeedLimitForState(Signal.EX_PROCEED_LEFT);

Notes

Sets the line speed limit to the value defined
Any existing limit is rescinded if there is no applicable setting.

ApplyUpdatedState

void ApplyUpdatedState(Soup signalStateSoup)

Parameters

signalStateSoup - Soup in the format returned by DetermineUpdatedState().

Returned Value

None

Syntax

ApplyUpdatedState(stateSoup);

Notes

Signals can apply speed limits so check to see if this signal has a limit specified for this state.
If there is a limit you can use ApplySpeedLimitForStateEx(signalState) to implement it.

CanDisplayStateEx

public bool CanDisplayStateEx(int state)

Parameters

state - One of the Extended Signal State values.

Returned Value

True if the given state can be displayed by this signal, false otherwise

Syntax

bool CanShow = CanDisplayStateEx(Signal.EX_CAUTION_LEFT_2);

Notes

CheckForOncomingTrain

public bool CheckForOncomingTrain(GSTrackSearch gst)

Parameters

gst - GSTrackSearch object to use in search.

Returned Value

True if a train is found, false otherwise.

Syntax

bool trainFound = CheckForOncomingTrain(gst);

Notes

Called after CheckForTrainInOverlap() using the same GSTrackSearch object.
The GSTrackSearch cursor will be moved on by this method.

CheckForTrainInOverlap

public bool CheckForTrainInOverlap(GSTrackSearch gst, float overlap)

Parameters

gst - GSTrackSearch object to use in search.
overlap - Overlap distance to search.

Returned Value

True if a train is found within the signal's overlap, false otherwise

Syntax

bool trainFound = CheckForTrainInOverlap(gst,overlap);

Notes

The GSTrackSearch cursor will be moved on by this method and left in te correct position for use by CheckForOncomingTrain().

DetermineUpdatedState

public Soup DetermineUpdatedState(void)

Parameters

None

Returned Value

A Soup object defining the new signal state, containing "state" and "reason" tags.

Syntax

Soup signalStateSoup = mySignal.DetermineUpdatedState();

Notes

This method sets a state for the signal based on the results of a serach along the line and the configuration of the signal object.
The method can be overridden in a subclassed object to change behavior to suit your own particular prototype, however the method is called frequently for every signal on the map, which makes it very easy to destroy performance.
Make sure that your code is as efficient as possible and does not make unneccessary calls, In particular, if you need to read config.txt do this in Init() and cache the result.

Reason Strings

These will automatically show in the users selected language.

String	Result (English)
$signal_endofline_lbl	Line terminates or is closed
$signal_nextblockbusy_lbl	Line ahead is occupied by another train
$signal_nextsignalred_lbl	Line ahead is clear for one block
$signal_nsrdoubleblock_lbl	Line ahead is reserved as a safety block
$signal_nextsignalyellow_lbl	Line ahead is clear for two blocks
$signal_idle_lbl	No train approaching
$signal_unsignalled_lbl	Line ahead is unsignalled
$signal_lineclear_lbl	Line ahead is clear
$signal_repeater_lbl	Repeating State of signal ahead
$signal_overlapoccupied_lbl	Overlap of block ahead is occupied
$signal_oncomingtrain_lbl	Line ahead is reserved for an oncoming train
$signal_tooclose_lbl	Signal ahead is within the overlap distance
$signal_unknownstate_lbl	Signal ahead is in an unknown state!
$signal_aidirectionmarker_lbl	Line ahead has a track direction marker facing against us
$signal_lineclearportal_lbl	Line ahead is clear into Portal
$signal_apprel_lbl	Signal is waiting for train to approach
$signal_undecided_lbl	Signal undecided on what to do
$signal_trainapproaching_lbl	Train is approaching but not within this block

FindApproachingTrain

public Train FindApproachingTrain(Signal start, bool direction, int numSignals, float maxDistance)

Parameters

start - The signal to start searching from.
direction - Direction in which to search (true- forwards, false- backwards).
numSignals - How many signals to look past when trying to find a train. Zero means stop at the first signal, one means stop at the second signal, etc. Negative means infinite.
maxDistance - How far down the track to search before giving up.

Returned Value

The first train found in the search direction specified, or null if no train was found.

Syntax

train = findApproachingTrain(signal1, false, 2, 2000.0);

Notes

FindNearestDisplayableStateEx

public int FindNearestDisplayableStateEx(int state)

Parameters

state - One of the Extended Signal State values.

Returned Value

The nearest approximation to the specified state which this signal can display.

Syntax

int stateToShow = findNearestDisplayableState(Signal.EX_PROCEED_RIGHT);

Notes

If a sensible approximation can't be found the method returns the first state defined in config.txt.

GetIsDistant

public native bool GetIsDistant(void)

Parameters

None

Returned Value

True if this is a Distant signal, false otherwise

Syntax

bool distant = GetIsDistant();

Notes

GetIsHome

public native bool GetIsHome(void)

Parameters

None

Returned Value

True if this is a Home signal, false otherwise

Syntax

bool home = GetIsHome();

Notes

GetIsRepeater

public native bool GetIsRepeater(void)

Parameters

None

Returned Value

True if this is a Repeater signal, false otherwise

Syntax

bool repeater = GetIsRepeater();

Notes

GetOverlap

public native float GetOverlap(void)

Parameters

None

Returned Value

The overlap distance of this signal.

Syntax

float overlap = GetOverlap();

Notes

GetSignalLit

public native bool GetSignalLit(void)

Parameters

None

Returned Value

True if the signal is lit, false otherwise.

Syntax

bool showing = GetSignalLit();

Notes

GetSignalState

See Trackside.GetSignalState()

GetSignalStateEx

See Trackside.GetSignalStateEx()

LightSignal

public native void LightSignal(SecurityToken token, bool show)

Parameters

token - A token for the signal owner (new and current, if applicable) with rights "signal-owner".
show - If true, turn the signal's lights on, else turn them off.

Returned Value

None

Syntax

signal.LightSignal(null, false);

Notes

AI trains will still read the signal state, even if it is switched off.

PerformLogic

final Soup PerformLogic(void)

Parameters

None

Returned Value

A Soup object defining the new signal state, containing "state" and "reason" tags.

Syntax

mySignal.PerformLogic();

Notes

Calls ApplyUpdatedState() with a Soup object obtained by a call to DetermineUpdatedState()

SetSignalOwner

public native bool SetSignalOwner(SecurityToken token, TrainzGameObject owner)

Parameters

token - A token for the signal owner (new and current, if applicable) with rights "signal-owner".
owner - The desired owner to set.

Returned Value

None

Syntax

signal.SetSignalOwner(m_ownershipToken, me);

Notes

Updates the signal 'owner', which is used to lock access to various functions.
Introduced for Interlocking Towers.

GetSignalOwner

public native TrainzGameObject GetSignalOwner(void)

Parameters

None

Returned Value

TrainzGameObject - The current signal owner, or null if unowned.

Syntax

if (signal.GetSignalOwner())
  return; // Signal is owned, so state cannot be altered.

Notes

Returns the current signal owner, if any.
Owned signals cannot have their signal aspect altered by any script except the owner, including the signal itself.
Introduced for Interlocking Towers.

SetSignalState

public native void SetSignalState(SecurityToken token, int state, string reason)

Parameters

token - A token for the signal owner with rights "signal-state", or null.
state - One of the Signal State values to set this signal to.
reason - Reason string to be displayed when a mouse cursor is placed over the signal

Returned Value

None

Syntax

if (!signal.GetSignalOwner())
  signal.SetSignalState(null, Signal.GREEN, "Line is clear");

Notes

If the signal is owned then a SecurityToken must be passed or an exception will be triggered.
The token is unused if the signal is unowned, and can be passed as null.

SetSignalStateEx