Class Crossing

Revision as of 15:58, 24 August 2022 (view source) Christopher824 (Talk | contribs) m (→‎SetCrossingAutomatic) ← Older edit		Revision as of 14:55, 26 February 2024 (view source) Pw3r (Talk | contribs) Newer edit →
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 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(SecurityToken, 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(token, Crossing.CROSSING_STATE_CLOSED);	+	SetCrossingState(null, Crossing.CROSSING_STATE_CLOSED);
	;Notes		;Notes
−	*Allows the crossing to be opened or closed by a script call.	+	*
−	*Before using this method you should call ''SetCrossingAutomatic(token, false);''	+	*If you intend to alter the crossing state you should first disable automatic control (See SetCrossingAutomatic)
−	*If you do not include the SecurityToken, the call will be flagged obsolete	+	*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]]

---

Revision as of 14:55, 26 February 2024

• API Hierarchy
  • GSObject
    • GameObject
      • TrainzGameObject
      • PropertyObject
        • MeshObject
          • MapObject
            • SceneryWithTrack
              • Crossing

• 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 1 Constants & Messages 1.1 Crossing States 1.2 Related Messages 2 Methods 2.1 GetCrossingAutomatic 2.2 GetCrossingHasNearbyTrain 2.3 GetCrossingOwner 2.4 GetCrossingState 2.5 SetCrossingAutomatic 2.6 SetCrossingOwner 2.7 SetCrossingState 3 Categories

Constants & Messages

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.

Related Messages

---

• Messages sent to and from Crossings objects are listed below:
• Note that these are only a subset of the messages exchanged by the parent SceneryWithTrack class.

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

Methods

GetCrossingAutomatic

Parameters

• None

Returned Value

• Whether the crossing operating in automatic mode.

Syntax

bool bIsAutomaticMode = crossing.GetCrossingAutomatic();

Notes

GetCrossingHasNearbyTrain

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.

GetCrossingOwner

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].

GetCrossingState

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.

SetCrossingAutomatic

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.

SetCrossingOwner

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 [[Class InterlockingTower|Interlocking Towers].

SetCrossingState

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.

Categories