Class Signal

Revision as of 13:21, 26 February 2024 (view source) Pw3r (Talk | contribs) ← Older edit		Revision as of 13:22, 26 February 2024 (view source) Pw3r (Talk | contribs) Newer edit →
Line 446:		Line 446:
	{{MethodHeader|public native void SetSignalState(SecurityToken token, int state, string reason)}}		{{MethodHeader|public native void SetSignalState(SecurityToken token, int state, string reason)}}
	;Parameters		;Parameters
−	*'''token''' - A token for the signal owner with rights "signal-state", or null	+	*'''token''' - A token for the signal owner with rights "signal-state", or null.
	*'''state''' - One of the ''[[#Signal States|Signal State]]'' values to set this signal to.		*'''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		*'''reason''' - Reason string to be displayed when a mouse cursor is placed over the signal
Line 462:		Line 462:
	{{MethodHeader|public native void SetSignalState(SecurityToken token, int state, string reason)}}		{{MethodHeader|public native void SetSignalState(SecurityToken token, int state, string reason)}}
	;Parameters		;Parameters
−	*'''token''' - A token for the signal owner with rights "signal-state", or null	+	*'''token''' - A token for the signal owner with rights "signal-state", or null.
	*'''state''' - One of the ''[[#Extended Signal States|Extended Signal State]]'' values to set this signal to.		*'''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		*'''reason''' - Reason string to be displayed when a mouse cursor is placed over the signal

---

Revision as of 13:22, 26 February 2024

• API Hierarchy
  • GSObject *
    • GameObject
      • TrainzGameObject
        • MeshObject
          • MapObject
            • Trackside
            • PropertyObject *
              • 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.

Contents 1 Messages 2 Constants 2.1 Useful Terminology 2.2 Distances 2.3 Signal States 2.4 Extended Signal States 3 Methods 3.1 ApplySpeedLimitForStateEx 3.2 ApplyUpdatedState 3.3 CanDisplayStateEx 3.4 CheckForOncomingTrain 3.5 CheckForTrainInOverlap 3.6 DetermineUpdatedState 3.7 FindApproachingTrain 3.8 FindNearestDisplayableStateEx 3.9 GetIsDistant 3.10 GetIsHome 3.11 GetIsRepeater 3.12 GetOverlap 3.13 GetSignalLit 3.14 GetSignalState 3.15 GetSignalStateEx 3.16 LightSignal 3.17 PerformLogic 3.18 SetSignalOwner 3.19 GetSignalOwner 3.20 SetSignalState 3.21 SetSignalStateEx 4 Related Methods 5 Categories

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

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

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

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

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

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

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

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

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

Parameters

• None

Returned Value

• True if this is a Distant signal, false otherwise

Syntax

bool distant = GetIsDistant();

Notes

GetIsHome

Parameters

• None

Returned Value

• True if this is a Home signal, false otherwise

Syntax

bool home = GetIsHome();

Notes

GetIsRepeater

Parameters

• None

Returned Value

• True if this is a Repeater signal, false otherwise

Syntax

bool repeater = GetIsRepeater();

Notes

GetOverlap

Parameters

• None

Returned Value

• The overlap distance of this signal.

Syntax

float overlap = GetOverlap();

Notes

GetSignalLit

Parameters

• None

Returned Value

• True if the signal is lit, false otherwise.

Syntax

bool showing = GetSignalLit();

Notes

GetSignalState

GetSignalStateEx

LightSignal

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

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

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

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

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

Parameters

• token - A token for the signal owner with rights "signal-state", or null.
• 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

if (!signal.GetSignalOwner())
  signal.SetSignalStateEx(null, Signal.EX_PROCEED_LEFT, "Line to the left 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.

Related Methods

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

Categories