Class Crossing

From TrainzOnline
(Difference between revisions)
Jump to: navigation, search
(→‎SetCrossingAutomatic)
(→‎SetCrossingState)
 
(8 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
*[[TrainzScript Library Reference|API Hierarchy]]
 
*[[TrainzScript Library Reference|API Hierarchy]]
−
**[[Class GSObject|GSObject]] *
+
**[[Class GSObject|GSObject]]
 
***[[Class GameObject|GameObject]]
 
***[[Class GameObject|GameObject]]
 
****[[Class TrainzGameObject|TrainzGameObject]]
 
****[[Class TrainzGameObject|TrainzGameObject]]
−
****[[Class PropertyObject|PropertyObject]] *
+
****[[Class PropertyObject|PropertyObject]]
 
*****[[Class MeshObject|MeshObject]]
 
*****[[Class MeshObject|MeshObject]]
 
******[[Class MapObject|MapObject]]
 
******[[Class MapObject|MapObject]]
 
*******[[Class SceneryWithTrack|SceneryWithTrack]]
 
*******[[Class SceneryWithTrack|SceneryWithTrack]]
−
********Crossing
+
********[[Class Crossing|Crossing]]
 
<br>
 
<br>
  
−
*An interface to operate a level crossing or similar object.
+
*A script class to represent a level crossing or similar object.
−
*By default a crossing is automatically controlled by trains.
+
*By default a crossing is automatically controlled by Trainz native code.
−
*When a train is within 200 meters of the crossing, it will be closed and road traffic will not cross the the track.
+
*The crossing will close when a train is within the trigger distance of the crossing (as specified by the asset).
−
*The crossing will reopen for traffic when there are no trains within 200 meters.
+
*The crossing will reopen to road traffic when there are no trains within the trigger disance.
−
*This class allows a crossing asset with custom scripted behavior to be created so the default behavior described above can be disabled and a script can take control.
+
 
<br>
 
<br>
  
Line 21: Line 20:
 
===Crossing States===
 
===Crossing States===
 
----
 
----
−
*These values define the current state of the crossing.
+
*These values define the possible state of a crossing.
−
*Note that values 1 and 3 are transient and will occur if the crossing is interrogated in the act of opening or closing.
+
 
{{TableHeader|width=95%|margin=15px}}
 
{{TableHeader|width=95%|margin=15px}}
 
|width=375|public define int CROSSING_STATE_OPEN = 0||Crossing is open to road traffic.
 
|width=375|public define int CROSSING_STATE_OPEN = 0||Crossing is open to road traffic.
Line 37: Line 35:
 
----
 
----
 
*Messages sent to and from Crossings objects are listed below:
 
*Messages sent to and from Crossings objects are listed below:
−
*Note that these are only a subset of the messages exchanged by the parent [[Class SceneryWithTrack|SceneryWithTrack]] class.
+
*Note that more messages are also posted by the parent [[Class SceneryWithTrack|SceneryWithTrack]] class.
 
<br>
 
<br>
 
{{TableHeader|width=50%|margin=15px}}
 
{{TableHeader|width=50%|margin=15px}}
Line 46: Line 44:
 
|-
 
|-
 
|[[Object Messages|Object]]||Leave||Crossing||Crossing
 
|[[Object Messages|Object]]||Leave||Crossing||Crossing
 +
|-
 +
|Crossing||StateChanged||Crossing||Crossing
 
|}
 
|}
 
<br>
 
<br>
Line 56: Line 56:
 
*None
 
*None
 
;Returned Value
 
;Returned Value
−
*True if crossing is operating in default automatic mode, false if under script control.
+
*Whether the crossing operating in automatic mode.
 
;Syntax
 
;Syntax
−
  bool Auto = MyCrossing.GetCrossingAutomatic();
+
  bool bIsAutomaticMode = crossing.GetCrossingAutomatic();
 
;Notes
 
;Notes
 
<br>
 
<br>
Line 67: Line 67:
 
*None
 
*None
 
;Returned Value
 
;Returned Value
−
*True if any trains are found within the 200 metre trigger radius, false otherwise.
+
*Whether any trains are within the trigger radius (default 200m, overridable by the asset).
 
;Syntax
 
;Syntax
−
  bool TrainPresent = MyCrossing.GetCrossingHasNearbyTrain();
+
  bool bHasNearbyTrain = crossing.GetCrossingHasNearbyTrain();
 
;Notes
 
;Notes
 +
*This function will continue to operate when the crossing is in manual script mode.
 +
*The default crossing trigger distance is 200 metres, but this can be overridden by the asset config.
 +
*The crossing trigger distance cannot be overridden by script.
 +
<br>
 +
 +
===GetCrossingOwner===
 +
{{MethodHeader|public native TrainzGameObject GetCrossingOwner(void)}}
 +
;Parameters
 +
*None
 +
;Returned Value
 +
*The crossing owner, or null.
 +
;Syntax;
 +
if (crossing.GetCrossingOwner())
 +
  return; // The crossing is owned, so we cannot alter state.
 +
;Notes
 +
*Returns the crossing owner, if any.
 +
*Owned crossings cannot have their state altered by any script except the owner, including the crossing itself.
 +
*Introduced for [[Class InterlockingTower|Interlocking Towers]].
 
<br>
 
<br>
  
Line 80: Line 98:
 
*One of the crossing state constants indicating the current condition of the crossing.
 
*One of the crossing state constants indicating the current condition of the crossing.
 
;Syntax
 
;Syntax
−
  int State = MyCrossing.GetCrossingState();
+
  switch(GetCrossingState())
 +
{
 +
case CROSSING_STATE_OPEN:
 +
  // Crossing is open to road traffic.
 +
  break;
 +
 +
case CROSSING_STATE_CLOSING:
 +
case CROSSING_STATE_CLOSED:
 +
case CROSSING_STATE_OPENING:
 +
  // Crossing is NOT open to road traffic.
 +
  break;
 +
}
 
;Notes
 
;Notes
−
*If the crossing is in automatic mode the returned state is only valid at the time of the call and can change without script intervention.
+
*A "Crossing","StateChanged" message will be posted to the crossing whenever this value changes.
 
<br>
 
<br>
  
 
===SetCrossingAutomatic===
 
===SetCrossingAutomatic===
−
{{MethodHeader|public native void SetCrossingAutomatic(SecurityToken, bool auto)}}
+
{{MethodHeader|public native void SetCrossingAutomatic(SecurityToken token, bool auto)}}
 
;Parameters
 
;Parameters
−
*'''auto''' = True to select automatic mode, false to allow a script to take over.
+
*'''token''' = A token for the crossing owner with rights "crossing-state", or null.
 +
*'''auto''' = True to select automatic mode, false to disable automatic control.
 
;Returned Value
 
;Returned Value
 
*None
 
*None
 
;Syntax
 
;Syntax
−
  MyCrossing.SetCrossingAutomatic(token, false);
+
  SetCrossingAutomatic(null, false);
 +
;Notes
 +
*The token is unused if the crossing is unowned, and can be passed as null.
 +
<br>
 +
 
 +
===SetCrossingOwner===
 +
{{MethodHeader|public native void SetCrossingOwner(SecurityToken token, TrainzGameObject owner)}}
 +
;Parameters
 +
*'''token''' - A token for the crossing owner (new and current, if applicable) with rights "crossing-owner".
 +
*'''owner''' - New owner to set, may be null.
 +
;Returned Value
 +
*Whether the call succeeded, and the crossing owner was changed.
 +
;Syntax;
 +
string[] rights = new string[1];
 +
rights[0] = "crossing-owner";
 +
SecurityToken token = IssueSecurityToken(GetAsset().GetKUID(), rights);
 +
 
 +
crossing.SetCrossingOwner(token, me);
 
;Notes
 
;Notes
−
If you do not include the SecurityToken, the call will be flagged obsolete
+
*Updates the crossing 'owner', which is used to lock access to various functions.
 +
*Owned crossings cannot have their state altered by any script except the owner, including the crossing itself.
 +
*Introduced for [[Class InterlockingTower|Interlocking Towers]].
 
<br>
 
<br>
  
 
===SetCrossingState===
 
===SetCrossingState===
−
{{MethodHeader|public native void SetCrossingState(int state)}}
+
{{MethodHeader|public native void SetCrossingState(SecurityToken token, int state)}}
 
;Parameters
 
;Parameters
 +
*'''token''' = A token for the crossing owner with rights "crossing-state", or null.
 
*'''state''' = One of the crossing state constants indicating which state to set.
 
*'''state''' = One of the crossing state constants indicating which state to set.
 
;Returned Value
 
;Returned Value
 
*None
 
*None
 
;Syntax
 
;Syntax
−
  MyCrossing.SetCrossingState(Crossing.CROSSING_STATE_CLOSED);
+
  SetCrossingState(null, Crossing.CROSSING_STATE_CLOSED);
 
;Notes
 
;Notes
−
*Allows the crossing to be opened or closed by a script call.
+
*If you intend to alter the crossing state you should first disable automatic control (See SetCrossingAutomatic)
−
*Before using this method you should call ''SetCrossingAutomatic(false);''
+
*The crossing state will be altered as requested even if the crossing is under automatic control, but native code may quickly change it back.
 +
*The token is unused if the crossing is unowned, and can be passed as null.
 
<br>
 
<br>
  
 
==Categories==
 
==Categories==
 
[[Category:Script Class]]
 
[[Category:Script Class]]

Latest revision as of 15:02, 26 February 2024


  • A script class to represent a level crossing or similar object.
  • By default a crossing is automatically controlled by Trainz native code.
  • The crossing will close when a train is within the trigger distance of the crossing (as specified by the asset).
  • The crossing will reopen to road traffic when there are no trains within the trigger disance.


Contents

[edit] Constants & Messages


[edit] Crossing States

  • These values define the possible state of a crossing.
public define int CROSSING_STATE_OPEN = 0 Crossing is open to road traffic.
public define int CROSSING_STATE_CLOSING = 1 Crossing is in the act of closing.
public define int CROSSING_STATE_CLOSED = 2 Crossing is closed to road traffic.
public define int CROSSING_STATE_OPENING = 3 Crossing is in the act of opening.


[edit] Related Messages

  • Messages sent to and from Crossings objects are listed below:
  • Note that more messages are also posted by the parent SceneryWithTrack class.


Major Minor Source Destination
Object Enter Crossing Crossing
Object Leave Crossing Crossing
Crossing StateChanged Crossing Crossing


[edit] Methods

[edit] GetCrossingAutomatic

public native bool GetCrossingAutomatic(void)
Parameters
  • None
Returned Value
  • Whether the crossing operating in automatic mode.
Syntax 
bool bIsAutomaticMode = crossing.GetCrossingAutomatic();
Notes


[edit] GetCrossingHasNearbyTrain

public native bool GetCrossingHasNearbyTrain(void)
Parameters
  • None
Returned Value
  • Whether any trains are within the trigger radius (default 200m, overridable by the asset).
Syntax 
bool bHasNearbyTrain = crossing.GetCrossingHasNearbyTrain();
Notes
  • This function will continue to operate when the crossing is in manual script mode.
  • The default crossing trigger distance is 200 metres, but this can be overridden by the asset config.
  • The crossing trigger distance cannot be overridden by script.


[edit] GetCrossingOwner

public native TrainzGameObject GetCrossingOwner(void)
Parameters
  • None
Returned Value
  • The crossing owner, or null.
Syntax; 
if (crossing.GetCrossingOwner())
 return; // The crossing is owned, so we cannot alter state.
Notes
  • Returns the crossing owner, if any.
  • Owned crossings cannot have their state altered by any script except the owner, including the crossing itself.
  • Introduced for Interlocking Towers.


[edit] GetCrossingState

public native int GetCrossingState(void)
Parameters
  • None
Returned Value
  • One of the crossing state constants indicating the current condition of the crossing.
Syntax 
switch(GetCrossingState())
{
case CROSSING_STATE_OPEN:
  // Crossing is open to road traffic.
  break;

case CROSSING_STATE_CLOSING:
case CROSSING_STATE_CLOSED:
case CROSSING_STATE_OPENING:
  // Crossing is NOT open to road traffic.
  break;
}
Notes
  • A "Crossing","StateChanged" message will be posted to the crossing whenever this value changes.


[edit] SetCrossingAutomatic

public native void SetCrossingAutomatic(SecurityToken token, bool auto)
Parameters
  • token = A token for the crossing owner with rights "crossing-state", or null.
  • auto = True to select automatic mode, false to disable automatic control.
Returned Value
  • None
Syntax 
SetCrossingAutomatic(null, false);
Notes
  • The token is unused if the crossing is unowned, and can be passed as null.


[edit] SetCrossingOwner

public native void SetCrossingOwner(SecurityToken token, TrainzGameObject owner)
Parameters
  • token - A token for the crossing owner (new and current, if applicable) with rights "crossing-owner".
  • owner - New owner to set, may be null.
Returned Value
  • Whether the call succeeded, and the crossing owner was changed.
Syntax; 
string[] rights = new string[1];
rights[0] = "crossing-owner";
SecurityToken token = IssueSecurityToken(GetAsset().GetKUID(), rights);

crossing.SetCrossingOwner(token, me);
Notes
  • Updates the crossing 'owner', which is used to lock access to various functions.
  • Owned crossings cannot have their state altered by any script except the owner, including the crossing itself.
  • Introduced for Interlocking Towers.


[edit] SetCrossingState

public native void SetCrossingState(SecurityToken token, int state)
Parameters
  • token = A token for the crossing owner with rights "crossing-state", or null.
  • state = One of the crossing state constants indicating which state to set.
Returned Value
  • None
Syntax 
SetCrossingState(null, Crossing.CROSSING_STATE_CLOSED);
Notes
  • If you intend to alter the crossing state you should first disable automatic control (See SetCrossingAutomatic)
  • The crossing state will be altered as requested even if the crossing is under automatic control, but native code may quickly change it back.
  • The token is unused if the crossing is unowned, and can be passed as null.


[edit] Categories

Retrieved from "https://online.ts2009.com/mediaWiki/index.php?title=Class_Crossing&oldid=40147"
Personal tools