Class Signal

From TrainzOnline
(Difference between revisions)
Jump to: navigation, search
(Added reason strings)
m (Change link to library reference, not language reference)
Line 1: Line 1:
*[[TrainzScript Language Reference|API Hierarchy]]
+
*[[TrainzScript Library Reference|API Hierarchy]]
 
**[[Class GSObject|GSObject]] *
 
**[[Class GSObject|GSObject]] *
 
***[[Class GameObject|GameObject]]
 
***[[Class GameObject|GameObject]]

Revision as of 23:45, 28 December 2020



Contents

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
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
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.
  • numSignals = How many signals to look past when trying to find a train.
  • maxDistance = How far down the track graph to look for a train
Returned Value
  • A reference to a train, if one is found within the defined limits, null otherwise.
Syntax
train = findApproachingTrain(Signal1,false,2,200.0);
Notes


FindNearestDisplayableStateEx

public int FindNearestDisplayableStateEx(int state)
Parameters
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


GetSignalStateEx


LightSignal

public native void LightSignal(bool show)
Parameters
  • 'show = If true, turn the signal's lights on, else turn them off.
Returned Value
  • None
Syntax
signal.LightSignal(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()


SetSignalState

public native void SetSignalState(int state, string reason)
Parameters
  • 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
signal.SetSignalState(Signal.GREEN,"Line is clear");
Notes


SetSignalStateEx

public native void SetSignalState(int state, string reason)
Parameters
  • state = One of the Extended 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
signal.SetSignalStateEx(Signal.EX_PROCEED_LEFT,"Line to the left is clear");
Notes


Related Methods

Trackside.GetSignalState()
Trackside.GetSignalStateEx()
Trackside.GetSpeedLimit()
Trackside.SetSpeedLimit()
World.GetSignalList()

Categories

Personal tools