Class Signal

2010-02-28T15:00:25Z

Duckblaster: Added reason strings

*[[TrainzScript Language Reference|API Hierarchy]]
**[[Class GSObject|GSObject]] *
***[[Class GameObject|GameObject]]
****[[Class TrainzGameObject|TrainzGameObject]]
****[[Class PropertyObject|PropertyObject]] *
*****[[Class MeshObject|MeshObject]]
******[[Class MapObject|MapObject]]
*******[[Class Trackside|Trackside]]
********Signal

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

==Messages==
*Messages sent to and from Signal objects are listed below:
 
{{TableHeader|width=50%|margin=15px}}
|-
|bgcolor="#EEEEEE"|'''Major'''||bgcolor="#EEEEEE"|'''Minor'''||bgcolor="#EEEEEE"|'''Source'''||bgcolor="#EEEEEE" |'''Destination'''
|-
|[[Signal Messages|Signal]]||StateChanged||Signal||Broadcast
|-
|[[Signal Messages|Train]]||Entered red signal||Signal||Train
|-
|[[Signal Messages|Train]]||Entered red signal notify||Train||Broadcast
|}
 

==Constants==

===Useful Terminology===
 
{{TableHeader|width=75%|margin=15px}}
|-
|width=100|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===
 
{{TableHeader|width=95%|margin=15px}}
|bgcolor=#EEEEEE|Miscellaneous Distance Constants||bgcolor=#EEEEEE|
|-
|width=375|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.
 

{{TableHeader|width=95%|margin=15px}}
|width=375 bgcolor="#EEEEEE"|Signal States||bgcolor="#EEEEEE"|
|-
|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.
 

{{TableHeader|width=95%|margin=15px}}
|width=375 bgcolor="#EEEEEE"|Shared States||bgcolor="#EEEEEE"|
|-
|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.
|}
 

{{TableHeader|width=95%|margin=15px}}
|width=375 bgcolor="#EEEEEE"|Route Signalling Specific States||bgcolor="#EEEEEE"|
|-
|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.
|}
 

{{TableHeader|width=95%|margin=15px}}
|width = 375 bgcolor="#EEEEEE"|Speed Signalling Specific States||bgcolor="#EEEEEE"|
|-
|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===
{{MethodHeader|public void ApplySpeedLimitForStateEx(int state)}}
;Parameters
*'''state'' = One of the ''[[#Extended Signal States|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===
{{MethodHeader|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===
{{MethodHeader|public bool CanDisplayStateEx(int state)}}
;Parameters
*'''state'' = One of the ''[[#Extended Signal States|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===
{{MethodHeader|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===
{{MethodHeader|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===
{{MethodHeader|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.
{{TableHeader|width=50%|margin=15px}}
|-
|bgcolor="#EEEEEE"|'''String'''||bgcolor="#EEEEEE"|'''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===
{{MethodHeader|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===
{{MethodHeader|public int FindNearestDisplayableStateEx(int state)}}
;Parameters
*'''state'' = One of the ''[[#Extended Signal States|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===
{{MethodHeader|public native bool GetIsDistant(void)}}
;Parameters
*None
;Returned Value
*True if this is a ''Distant'' signal, false otherwise
;Syntax
bool distant = GetIsDistant();
;Notes
 

===GetIsHome===
{{MethodHeader|public native bool GetIsHome(void)}}
;Parameters
*None
;Returned Value
*True if this is a ''Home'' signal, false otherwise
;Syntax
bool home = GetIsHome();
;Notes
 

===GetIsRepeater===
{{MethodHeader|public native bool GetIsRepeater(void)}}
;Parameters
*None
;Returned Value
*True if this is a ''Repeater'' signal, false otherwise
;Syntax
bool repeater = GetIsRepeater();
;Notes
 

===GetOverlap===
{{MethodHeader|public native float GetOverlap(void)}}
;Parameters
*None
;Returned Value
*The overlap distance of this signal.
;Syntax
float overlap = GetOverlap();
;Notes
 

===GetSignalLit===
{{MethodHeader|public native bool GetSignalLit(void)}}
;Parameters
*None
;Returned Value
*True if the signal is lit, false otherwise.
;Syntax
bool showing = GetSignalLit();
;Notes
 

===GetSignalState===
{{MethodHeader|See [[Class Trackside#GetSignalState|Trackside.GetSignalState()]]}}
 

===GetSignalStateEx===
{{MethodHeader|See [[Class Trackside#GetSignalStateEx|Trackside.GetSignalStateEx()]]}}
 

===LightSignal===
{{MethodHeader|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===
{{MethodHeader|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===
{{MethodHeader|public native void SetSignalState(int state, string reason)}}
;Parameters
*'''state''' = One of the ''[[#Signal States|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===
{{MethodHeader|public native void SetSignalState(int state, string reason)}}
;Parameters
*'''state''' = One of the ''[[#Extended Signal States|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==
[[Class Trackside#GetSignalState|Trackside.GetSignalState()]] 
[[Class Trackside#GetSignalStateEx|Trackside.GetSignalStateEx()]] 
[[Class Trackside#GetSpeedLimit|Trackside.GetSpeedLimit()]] 
[[Class Trackside#SetSpeedLimit|Trackside.SetSpeedLimit()]] 
[[Class World#GetSignalList|World.GetSignalList()]] 
 

==Categories==
[[Category:Script Class]]

TrainzOnline - User contributions [en]

Class Signal