Class JunctionBase

From TrainzOnline
(Difference between revisions)
Jump to: navigation, search
m (RequestPermit)
 
(6 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 JunctionBase|JunctionBase]]
***[[Class GameObject|GameObject]]
+
****[[Class TrainzGameObject|TrainzGameObject]]
+
****[[Class PropertyObject|PropertyObject]] *
+
*****[[Class MeshObject|MeshObject]]
+
******[[Class MapObject|MapObject]]
+
*******JunctionBase *
+
 
+
  
 
<br>
 
<br>
Line 68: Line 61:
 
{{MethodHeader|public native voidAllowManualControl(bool allow)}}
 
{{MethodHeader|public native voidAllowManualControl(bool allow)}}
 
;Parameters
 
;Parameters
*'''allow''' = True to allow the user to toggle the junction, false otherwise.
+
*'''allow''' - True to allow the user to toggle the junction, false otherwise.
 
;Returned Value
 
;Returned Value
 
*None
 
*None
Line 101: Line 94:
 
{{MethodHeader|public native int GetDirectionToTrain(Train train)}}
 
{{MethodHeader|public native int GetDirectionToTrain(Train train)}}
 
;Parameters
 
;Parameters
*'''train''' = A reference to a train located within 15 track stretches of the junction.
+
*'''train''' - A reference to a train located within 15 track stretches of the junction.
 
;Returned Value
 
;Returned Value
 
*One of the [[#Junction States|Junction State]] constants indicating the track on which the train was found.
 
*One of the [[#Junction States|Junction State]] constants indicating the track on which the train was found.
Line 122: Line 115:
 
*For an embedded junction in a fixed track junction the object returned is the embedded junction node.
 
*For an embedded junction in a fixed track junction the object returned is the embedded junction node.
 
*In either case null is returned on failure.
 
*In either case null is returned on failure.
 +
<br>
 +
 +
===GetJunctionOwner===
 +
{{MethodHeader|public native TrainzGameObject GetJunctionOwner(void)}}
 +
;Parameters
 +
*None
 +
;Returned Value
 +
*The junction owner, or null.
 +
;Syntax;
 +
if (junction.GetJunctionOwner())
 +
  return; // The junction is owned, so we cannot alter state.
 +
;Notes
 +
*Returns the junction owner, if any.
 +
*Owned junctions cannot have their direction altered by any script except the owner, including the junction itself.
 +
*Introduced for [[Class InterlockingTower|Interlocking Towers]].
 
<br>
 
<br>
  
Line 152: Line 160:
 
{{MethodHeader|public native bool JunctionInnerReEnter(int node)}}
 
{{MethodHeader|public native bool JunctionInnerReEnter(int node)}}
 
;Parameters
 
;Parameters
*'''node''' = Node Id of train as returned by Train.GetId().
+
*'''node''' - Node Id of train as returned by Train.GetId().
 
;Returned Value
 
;Returned Value
 
*None
 
*None
Line 164: Line 172:
 
{{MethodHeader|public native bool JunctionReEnter(int node)}}
 
{{MethodHeader|public native bool JunctionReEnter(int node)}}
 
;Parameters
 
;Parameters
*'''node''' = Node Id of train as returned by Train.GetId().
+
*'''node''' - Node Id of train as returned by Train.GetId().
 
;Returned Value
 
;Returned Value
 
*None
 
*None
Line 174: Line 182:
  
 
===RequestPermit===
 
===RequestPermit===
{{MethodHeader|public native Permit RequestPermit(SecrityToken sToken, GameObject obj, int direction)}}
+
{{MethodHeader|public native Permit RequestPermit(SecrityToken token, GameObject obj, int direction)}}
 
;Parameters
 
;Parameters
*'''obj''' = Object requesting the [[Class Permit|Permit]].
+
*'''token''' - A token for the junction owner with rights "junction-permit", or null.
 +
*'''obj''' - Object requesting the [[Class Permit|Permit]].
 +
*'''direction''' - The junction direction for the permit.
 
;Returned Value
 
;Returned Value
*Returns a Permit for ''obj'' to control the junction.  
+
*Permit - A Permit for ''obj'' to drive through the junction, in the direction request.
 
;Syntax;
 
;Syntax;
  Permit permit = RequestPermit(sToken, train, 0);
+
  Permit permit = RequestPermit(null, train, JunctionBase.DIRECTION_LEFT);
 
;Notes
 
;Notes
*Although a Permit is always returned, it may not necessarily be granted.
+
*The token is unused if the junction is unowned, and can be passed as null.
*
+
*Although a Permit is always returned, it may not initially be granted.
 
<br>
 
<br>
  
===RequestTrackPermit===
+
===SetDirection===
{{MethodHeader|public native Permit RequestTrackPermit(GameObject obj, int direction)}}
+
{{MethodHeader|public native bool SetDirection(SecurityToken token, int direction)}}
 
;Parameters
 
;Parameters
*'''obj''' = Object requesting the [[Class Permit|Permit]].
+
*'''token''' - A token for the junction owner with rights "junction-dir", or null.  
*'''direction''' = One of the [[#Junction States|Junction State]] constants indicating the direction of the track relative to the current junction.
+
*'''direction''' - New direction to set.
 
;Returned Value
 
;Returned Value
*Returns a Permit for ''obj'' to control the specified track.  
+
*Whether the junction was changed to the direction requested.
 
;Syntax;
 
;Syntax;
  Permit permit = RequestTrackPermit(train, DIRECTION_LEFT);
+
  junction.SetDirection(null, JunctionBase.DIRECTION_LEFT);
 
;Notes
 
;Notes
*Although a Permit is always returned, it may not necessarily be granted.
+
*The token is unused if the junction is unowned, and can be passed as null.
 
<br>
 
<br>
  
===SetDirection===
+
===SetJunctionOwner===
{{MethodHeader|public native bool SetDirection(SecurityToken myToken, int direction)}}
+
{{MethodHeader|public native bool SetJunctionOwner(SecurityToken token, TrainzGameObject owner)}}
 
;Parameters
 
;Parameters
*'''direction''' = New direction to set.
+
*'''token''' - A token for the junction owner (new and current, if applicable) with rights "junction-owner".
 +
*'''owner''' - New owner to set, may be null.
 
;Returned Value
 
;Returned Value
*True if the junction is changed, False if the direction is unchanged or if the specified direction was invalid for this junction.
+
*Whether the call succeeded, and the junction owner was changed.
 
;Syntax;
 
;Syntax;
  if (junction.SetDirection(myToken, DIRECTION_LEFT)) Interface.Print("Junction now set to the left");
+
  string[] rights = new string[1];
 +
rights[0] = "junction-owner";
 +
SecurityToken token = IssueSecurityToken(GetAsset().GetKUID(), rights);
 +
 
 +
junction.SetJunctionOwner(token, me);
 
;Notes
 
;Notes
*This method switches the junction unconditionally, disregarding any Permits that may exist.
+
*Updates the junction 'owner', which is used to lock access to various functions.
*If you do not include the SecurityToken, the method will be marked Obsolete.
+
*Owned junctions cannot have their direction altered by any script except the owner, including the junction itself.
 +
*Introduced for [[Class InterlockingTower|Interlocking Towers]].
 
<br>
 
<br>
  
 
===SwitchForTrain===
 
===SwitchForTrain===
{{MethodHeader|public native bool SwitchForTrain(Train train, int direction)}}
+
{{MethodHeader|public native bool SwitchForTrain(SecurityToken token, Train train, int direction)}}
 
;Parameters
 
;Parameters
*'''train''' = Train that is to pass over the junction.
+
*'''token''' - A token for the junction owner with rights "junction-dir", or null.
*'''direction''' = One of the [[#Junction States|Junction State]] constants indicating the current position of the train relative junction.
+
*'''train''' - Train that is to pass over the junction.
 +
*'''direction''' - One of the [[#Junction States|Junction State]] constants indicating the current position of the train relative junction.
 
;Returned Value
 
;Returned Value
*True if the junction is changed, False if the direction is unchanged or if the specified direction was invalid for this junction.
+
*Whether the junction was changed to the direction requested.
 
;Syntax;
 
;Syntax;
  junction.SwitchForTrain(train,DIRECTION_BACKWARD);
+
  junction.SwitchForTrain(null, train, JunctionBase.DIRECTION_BACKWARD);
 
;Notes
 
;Notes
 
*The new direction must be on the opposite side of the junction to the train's current position.
 
*The new direction must be on the opposite side of the junction to the train's current position.
*This method switches the junction unconditionally, disregarding any Permits that may exist.
+
*The token is unused if the junction is unowned, and can be passed as null.
 +
<br>
 +
 
 +
===ToggleJunction===
 +
{{MethodHeader|public native bool ToggleJunction(SecurityToken token)}}
 +
;Parameters
 +
*'''token''' - A token for the junction owner with rights "junction-dir", or null.
 +
;Returned Value
 +
*Whether the junction was changed.
 +
;Syntax;
 +
junction.ToggleJunction(null);
 +
;Notes
 +
*Toggles the junction to the 'next' valid direction.
 +
*The token is unused if the junction is unowned, and can be passed as null.
 
<br>
 
<br>
  

Latest revision as of 14:57, 26 February 2024


  • Interface methods to control and obtain information about the status of Junction objects.
  • This class relates equally to switch levers controlling spline track junctions and to the junction nodes attached to Fixed Track Junction objects.


Contents

[edit] Constants & Messages

[edit] Junction States

  • These values define the directions possible through a junction object.


public define int DIRECTION_LEFT = 0 Left junction direction.
public define int DIRECTION_FORWARD = 1 Forward junction direction (straight on for three way points).
public define int DIRECTION_RIGHT = 2 Right junction direction.
public define int DIRECTION_BACKWARD = -1 Backward junction direction (leading approach).
public define int DIRECTION_NONE = 3 No junction direction or error condition.


[edit] Related Messages

  • Messages sent to and from Junction objects are listed below:


Major Minor Source Destination
Junction Toggled Junction Broadcast
Junction Enter Junction Train
Junction InnerEnter Junction Train
Junction Stopped Junction Train
Junction InnerLeave Junction Train
Junction Leave Junction Train
Object Enter Train Junction
Object InnerEnter Train Junction
Object Stopped Train Junction
Object InnerLeave Train Junction
Object Leave Train Junction


[edit] Methods

[edit] AllowManualControl

public native voidAllowManualControl(bool allow)
Parameters
  • allow - True to allow the user to toggle the junction, false otherwise.
Returned Value
  • None
Syntax;
AllowManualControl(true);
Notes


[edit] GetDebugString

public string GetDebugString(void)
Parameters
  • None
Returned Value
  • A string that contains the node ID and name of the MapObject associated with this junction. If successful, the returned string will include the node ID and name of the MapObject. Otherwise an error string will be returned instead.
Syntax;
Interface.Print(GetDebugString());
Notes


[edit] GetDirection

public native int GetDirection(void)
Parameters
  • None
Returned Value
  • One of the Junction State constants indicating the current direction of the junction.
Syntax;
int direction = GetDirection();
Notes


[edit] GetDirectionToTrain

public native int GetDirectionToTrain(Train train)
Parameters
  • train - A reference to a train located within 15 track stretches of the junction.
Returned Value
  • One of the Junction State constants indicating the track on which the train was found.
Syntax;
int approachPath = GetDirectionToTrain(train);
Notes
  • DIRECTION_NONE is returned if the train is not within range.


[edit] GetGameObject

public native GameObject GetGameObject(void)
Parameters
  • None
Returned Value
  • A reference to the GameObject associated with this junction.
Syntax;
GameObject go = junction.GetGameObject();
Notes
  • For a trackside spline junction this method returns the junction lever object.
  • For an embedded junction in a fixed track junction the object returned is the embedded junction node.
  • In either case null is returned on failure.


[edit] GetJunctionOwner

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


[edit] GetManualControl

public native bool GetManualControl(void)
Parameters
  • None
Returned Value
  • True if the user is allowed to toggle this junction, false otherwise.
Syntax;
bool locked = !GetManualControl();
Notes


[edit] GetMapObject

public native MapObject GetMapObject(void)
Parameters
  • None
Returned Value
  • A reference to the MapObject associated with this junction.
Syntax;
MapObject mo = junction.GetMapObject();
Notes
  • For a trackside spline junction this method returns the junction lever object.
  • For an embedded junction in a fixed track piece the object returned is the fixed track parent object.
  • In either case null is returned on failure.


[edit] JunctionInnerReEnter

public native bool JunctionInnerReEnter(int node)
Parameters
  • node - Node Id of train as returned by Train.GetId().
Returned Value
  • None
Syntax;
junction.JunctionInnerReEnter(train);
Notes
  • The effect of this method is to cause a new Junction,InnerEnter message to be sent to the Junction if any part of the train is within the inner trigger radius.


[edit] JunctionReEnter

public native bool JunctionReEnter(int node)
Parameters
  • node - Node Id of train as returned by Train.GetId().
Returned Value
  • None
Syntax;
junction.JunctionReEnter(train);
Notes
  • The effect of this method is to cause a new Junction,Enter message to be sent to the Junction if any part of the train is within the default outer trigger radius.


[edit] RequestPermit

public native Permit RequestPermit(SecrityToken token, GameObject obj, int direction)
Parameters
  • token - A token for the junction owner with rights "junction-permit", or null.
  • obj - Object requesting the Permit.
  • direction - The junction direction for the permit.
Returned Value
  • Permit - A Permit for obj to drive through the junction, in the direction request.
Syntax;
Permit permit = RequestPermit(null, train, JunctionBase.DIRECTION_LEFT);
Notes
  • The token is unused if the junction is unowned, and can be passed as null.
  • Although a Permit is always returned, it may not initially be granted.


[edit] SetDirection

public native bool SetDirection(SecurityToken token, int direction)
Parameters
  • token - A token for the junction owner with rights "junction-dir", or null.
  • direction - New direction to set.
Returned Value
  • Whether the junction was changed to the direction requested.
Syntax;
junction.SetDirection(null, JunctionBase.DIRECTION_LEFT);
Notes
  • The token is unused if the junction is unowned, and can be passed as null.


[edit] SetJunctionOwner

public native bool SetJunctionOwner(SecurityToken token, TrainzGameObject owner)
Parameters
  • token - A token for the junction owner (new and current, if applicable) with rights "junction-owner".
  • owner - New owner to set, may be null.
Returned Value
  • Whether the call succeeded, and the junction owner was changed.
Syntax;
string[] rights = new string[1];
rights[0] = "junction-owner";
SecurityToken token = IssueSecurityToken(GetAsset().GetKUID(), rights);
junction.SetJunctionOwner(token, me);
Notes
  • Updates the junction 'owner', which is used to lock access to various functions.
  • Owned junctions cannot have their direction altered by any script except the owner, including the junction itself.
  • Introduced for Interlocking Towers.


[edit] SwitchForTrain

public native bool SwitchForTrain(SecurityToken token, Train train, int direction)
Parameters
  • token - A token for the junction owner with rights "junction-dir", or null.
  • train - Train that is to pass over the junction.
  • direction - One of the Junction State constants indicating the current position of the train relative junction.
Returned Value
  • Whether the junction was changed to the direction requested.
Syntax;
junction.SwitchForTrain(null, train, JunctionBase.DIRECTION_BACKWARD);
Notes
  • The new direction must be on the opposite side of the junction to the train's current position.
  • The token is unused if the junction is unowned, and can be passed as null.


[edit] ToggleJunction

public native bool ToggleJunction(SecurityToken token)
Parameters
  • token - A token for the junction owner with rights "junction-dir", or null.
Returned Value
  • Whether the junction was changed.
Syntax;
junction.ToggleJunction(null);
Notes
  • Toggles the junction to the 'next' valid direction.
  • The token is unused if the junction is unowned, and can be passed as null.


[edit] Related Methods

SceneryWithTrack.GetAttachedJunctions()
World.GetJunctionList()

[edit] Categories

Personal tools