TrainzOnline - User contributions [en]

Class JunctionBase

2025-03-21T20:21:38Z

Kemal: /* Methods */

*[[TrainzScript Library Reference|API Hierarchy]]
**[[Class JunctionBase|JunctionBase]]

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

==Constants & Messages==

===Junction States===
*These values define the directions possible through a junction object.
 
{{TableHeader|width=95%|margin=15px}}
|width=375|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.
|}
 

==Related Messages==
*Messages sent to and from Junction objects are listed below:
 
{{TableHeader|width=50%|margin=15px}}
|-
|bgcolor="#EEEEEE"|'''Major'''||bgcolor="#EEEEEE"|'''Minor'''||bgcolor="#EEEEEE"|'''Source'''||bgcolor="#EEEEEE" |'''Destination'''
|-
|Junction||Toggled||Junction||Broadcast
|-
|[[Object Messages|Junction]]||Enter||Junction||Train
|-
|[[Object Messages|Junction]]||InnerEnter||Junction||Train
|-
|[[Object Messages|Junction]]||Stopped||Junction||Train
|-
|[[Object Messages|Junction]]||InnerLeave||Junction||Train
|-
|[[Object Messages|Junction]]||Leave||Junction||Train
|-
|[[Object Messages|Object]]||Enter||Train||Junction
|-
|[[Object Messages|Object]]||InnerEnter||Train||Junction
|-
|[[Object Messages|Object]]||Stopped||Train||Junction
|-
|[[Object Messages|Object]]||InnerLeave||Train||Junction
|-
|[[Object Messages|Object]]||Leave||Train||Junction
|}
 

==Methods==

===AllowManualControl===
{{MethodHeader|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
 

===GetDebugString===
{{MethodHeader|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
 

===GetDirection===
{{MethodHeader|public native int GetDirection(void)}}
;Parameters
*None
;Returned Value
*One of the [[#Junction States|Junction State]] constants indicating the current direction of the junction.
;Syntax;
int direction = GetDirection();
;Notes
 

===GetDirectionToTrain===
{{MethodHeader|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 States|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.
 

===GetGameObject===
{{MethodHeader|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.
 

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

===GetManualControl===
{{MethodHeader|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
 

===GetMapObject===
{{MethodHeader|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.
 

===JunctionInnerReEnter===
{{MethodHeader|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.
 

===JunctionReEnter===
{{MethodHeader|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.
 

===RequestPermit===
{{MethodHeader|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 [[Class Permit|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.
 

===SetDirection===
{{MethodHeader|public native bool SetDirection(SecurityToken token, int direction)}}
;Parameters
*'''token''' - A token for the junction owner with rights "junction-state", 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.
 

===SetJunctionOwner===
{{MethodHeader|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 [[Class InterlockingTower|Interlocking Towers]].
 

===SwitchForTrain===
{{MethodHeader|public native bool SwitchForTrain(SecurityToken token, Train train, int direction)}}
;Parameters
*'''token''' - A token for the junction owner with rights "junction-state", or null.
*'''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
*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.
 

===ToggleJunction===
{{MethodHeader|public native bool ToggleJunction(SecurityToken token)}}
;Parameters
*'''token''' - A token for the junction owner with rights "junction-state", 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.
 

==Related Methods==
[[Class SceneryWithTrack#GetAttachedJunctions|SceneryWithTrack.GetAttachedJunctions()]] 
[[Class World#GetJunctionList|World.GetJunctionList()]] 
 

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

Class GSTrackSearch

2014-12-07T17:56:20Z

Kemal: /* Code Examples */

*[[TrainzScript Language Reference|API Hierarchy]]
**GSTrackSearch
 

*A class enabling the searching of a length of track for [[class Trackside|Trackside]] items.
*The GSTrackSearch class provides an interface to access certain items along a track in a specified direction from an existing trackside item.
*A GSTrackSearch object can be obtained by calling the [[Class Trackside#BeginTrackSearch|BeginTrackSearch()]] method on the [[class Trackside|Trackside]] item that you want to start your search from.
*The SearchNext() and GetMapObject() methods are provided to get a reference to a discovered [[class Trackside|Trackside]] object.
*The reference returned by these methods can be cast to [[class Trackside|Trackside]] child classes to find out if that item is in fact a [[class Signal|Signal]] or a [[class Junction|Junction]] for instance. As the script code doesn't know what the next item will be, always verify the cast.
*Since [[class Vehicle|Vehicles]] and [[Class Locomotive|Locomotives]] descend from [[class Trackside|Trackside]], searches can be initiated from rolling stock and rolling stock will be returned.
*GSTrackSearch methods will also find [[Class SceneryWithTrack|SceneryWithTrack]] and descendants, although the information which can be obtained from them is limited and these objects cannot be used to initiate a search.
*The search will continue (following the direction set by any junctions) until it is blocked by:
**A junction set against the track
**A turntable.
**A crossing. *** ? "crossing" appears to mean a track (diamond, etc), rather than a road (grade, level) crossing, since the function appears to work properly across road crossings.
**The end of the line.
 
*See [[TrackSearch]] for details of enhancements being developed for future versions of the game.
 

==Trackside.BeginTrackSearch==
{{MethodHeader|public native GSTrackSearch Trackside.BeginTrackSearch(bool direction)}}
*This method is called on objects descending from the [[class Trackside|Trackside]] class to obtain a GSTrackSearch object in the specified search direction.
*See [[Class Trackside#BeginTrackSearch|Trackside.BeginTrackSearch()]] for details.
 

==GetDistance==
{{MethodHeader|public native float GetDistance(void)}}
;Parameters
*None
;Returned Value
*The distance in metres from the origin of the search to the object at which the search cursor is currently pointing.
;Syntax
float distance = gst.GetDistance();
;Notes
*See [[#Code Examples|Code Examples]]
 

==GetFacingRelativeToSearchDirection==
{{MethodHeader|public native bool GetFacingRelativeToSearchDirection(void)}}
;Parameters
*None
;Returned Value
*True if the returned object orientation matches the direction of search, false otherwise.
;Syntax
bool facing = gst.GetFacingRelativeToSearchDirection();
;Notes
*Note that it is the direction of the search that matters, not the facing direction of the search origin.
*A search forwards from a fixed object such as a [[Class Trigger|Trigger]] will return '''true''' for any returned trigger which has the same orientation as the source.
*A search backwards from a fixed object such as a [[Class Trigger|Trigger]] will return '''false''' for any returned trigger which has the same orientation as the source.
 

==GetMapObject==
{{MethodHeader|public native MapObject GetMapObject(void)}}
;Parameters
*None
;Returned Value
*A reference to a MapObject or null if nothing has been found.
;Syntax
MapObject mo = gst.GetMapObject();
;Notes
*MapObject returns Trackside descendants including Vehicles and SceneryWithTrack descendants including Industries.
*Ensure that you attempt a cast to SceneryWithTrack and Trackside if you want the maximum possible amount of information from the search.
 

==SearchNext==
{{MethodHeader|public native MapObject SearchNext(void)}}
;Parameters
*None
;Returned Value
*A reference to a MapObject or null if nothing has been found.
;Syntax
MapObject mo = gst.GetMapObject();
;Notes
*SearchNext moves the search cursor to the next object if such an object exists.
 

==Known Issues==
*GSTrackSearch will return a null reference if it finds certain types of [[Class Crossing|Crossing]] objects, but will continue searching beyond them if asked. As a result of this it is often necessary to make repeated calls to SearchNext following a null return to decide whether you have reached the end of the track or whether your search has simply been interrupted by one or more crossings.
 

==Code Examples==
*This code fragment implements a search forwards from a locomotive. The distance from the locomotive to any discovered object is printed to ''jetlog.txt''
*The process continues until the search returns a null value (which might be a crossing or the end of the track) or the distance from the train exceeds 1km.
GSTrackSearch gst = Loco.BeginTrackSearch(true); // obtain a GSTrackSearch object
MapObject mo = gst.SearchNext(); // initiate the search
while (mo) { // continue as long as objects are present
float distance = gst.GetDistance(); // how far ahead the object is
if (distance > 1000.0) break; // break from the loop if the distance exceeds 1km
Interface.Print("object found at " distance " metres"); // print out the results
mo = gst.SearchNext(); // search for the next object
}
 

==Related Methods==
[[Class Trackside#BeginTrackSearch|Trackside.BeginTrackSearch()]]

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

KIND Product-category

2014-01-05T23:00:13Z

Kemal: /* Example config.txt */

{{ORP-top}}
==KIND Hierarchy==
'''KIND Product-category'''' provides categorization support for [[KIND Product]] assets. The [[KIND Product-category]] asset is referenced from the [[KIND Product]] asset using the "product-category" tag.

* Products instances of different categories cannot co-exist in the same [["queues" Container]] (product queue) when setting up an asset..

===Parent Classes===
* [[KIND TrainzBaseSpec]]
* [[KIND Product]]s
===Child Classes===
* ''none.''
==Supported Tags==
A [[KIND Product-category]] asset supports no custom tags. Third-party product categories may be created, and simply act as a label which can be applied to [[KIND Product]] assets.

===Builtins===
The built-in [[KIND Product-category]] assets include:

* <KUID:-3:10040> "Bulk Load" - Products of this category must supply a 'product-texture'.
* <KUID:-3:10042> "Container"
* <KUID:-3:10044> "Liquid Load"
* <KUID:-3:10091> "Passenger"

===Example [[config.txt]]===
* After standard boilerplate definitions of [[KIND TrainzBaseSpec]]...

{| style={{pseudo-table|width=80%}}
! This is a built-in asset, and cannot be modified locally.
|-
|
{|
! style="width:40%; text-align:left; font-size:110%;"|Tag names
! style="width:40%; text-align:left; font-size:110%;"|Defined defaulted values
|-
|  
|  
|-
| kind || "product-category"
|-
| kuid || <kuid:-3:10040>
|-
| username || "Bulk Load"
|-
| username-cn || "????"
|-
| asset-filename || "bulk_load_category"
|-
|
|-
| username-es || "Carga a granel"
|-
| username-it || "Carico pesante"
|-
| username-fr || "Charge volumineuse"
|-
| username-nl || "Bulkgoederen"
|-
| username-pl || "Towar luzem"
|-
| username-de || "Massengut"
|-
| username-cz || "Objemný náklad"
|-
| username-hu || "Ömlesztett rakomány"
|-
| username-ru || "Сыпучие грузы"
|}
|}

===Downloads===
''Attach sample files here''
{{Sect-stub}}

==Categories==
[[Category:Asset KIND]]
{{ORP-bot|Product-category,KIND}}

KIND Controlset

2013-04-28T16:55:25Z

Kemal:

[[KIND Controlset]] defines a set of user-input controls. Support currently exists for keyboard input only, but this may be extended in the future. Individual controls are defined in the [[controls container]].

==KIND Hierarchy==
===Parent Classes===
* [[KIND TrainzBaseSpec]]
===Child Classes===
* ''none.''

==Supported Tags==
Each controlset asset supports the following tags. The trainz-build tag should be greater than or equal to 3.6.

controls
{
}

====controls====
:Type: [[Controls_container|Controls container]]
:Desc: Specifies the various controls. Documented separately [[Controls_container|here]].

==Example Config.txt==
Sample [[config.txt file]] for a controlset asset, with the standard tags excluded for brevity:

kuid <kuid:401543:1100>
kind "controlset"
username "Menu Controls"
trainz-build 3.6
category-class "CS"
description "Keyboard shortcuts used within the Trainz menus"

thumbnails
{
1
{
image "thumbnail.jpg"
width 240
height 180
}
}

controls
{
routes-menu
{
name-token "routes-name"
desc-token "routes-desc"
event "routes-menu"
default-keys "r"
context "Menu"
}

new-route
{
name-token "new-route-name"
desc-token "new-route-desc"
event "new-route"
default-keys "n,c"
context "Menu"
}
}

string-table
{
routes-name "Routes Menu"
routes-desc "Opens the routes menu"
new-route-name "New Route"
new-route-desc "Creates a new route in Surveyor"
}

==Categories==
[[Category:Asset KIND]]

KIND Controlset

2013-04-26T05:39:20Z

Kemal: /* Supported Tags */

[[KIND Controlset]] defines a set of user-input controls. Support currently exists for keyboard input only, but this may be extended in the future. Individual controls are defined in the [[controls container]].

=KIND Hierarchy=
==Parent Classes==
* [[KIND TrainzBaseSpec]]
==Child Classes==
* ''none.''

==Supported Tags==
Each controlset asset supports the following tags. The trainz-build tag should be greater than or equal to 3.6.

controls
{
}

====controls====
:Type: [[Controls_container|Controls container]]
:Desc: Specifies the various controls. Documented separately [[Controls_container|here]].

==Example Config.txt==
Sample [[config.txt file]] for a controlset asset, with the standard tags excluded for brevity:

kuid <kuid:401543:1100>
kind "controlset"
username "Menu Controls"
trainz-build 3.6
category-class "CS"
description "Keyboard shortcuts used within the Trainz menus"

thumbnails
{
1
{
image "thumbnail.jpg"
width 240
height 180
}
}

controls
{
routes-menu
{
name-token "routes-name"
desc-token "routes-desc"
event "routes-menu"
default-keys "r"
context "Menu"
}

new-route
{
name-token "new-route-name"
desc-token "new-route-desc"
event "new-route"
default-keys "n,c"
context "Menu"
}
}

string-table
{
routes-name "Routes Menu"
routes-desc "Opens the routes menu"
new-route-name "New Route"
new-route-desc "Creates a new route in Surveyor"
}

==Categories==
[[Category:Asset KIND]]

KIND Engine

2013-01-16T00:34:22Z

Kemal: /* Supported Tags */

[[KIND Engine]] assets contain diesel or electric loco engine performance characteristics.

==KIND Hierarchy==
===Parent Classes===
* ''none.''
===Child Classes===
* ''none.''

==Supported Tags==

kind "engine"
[[throttle-power_container|throttle-power]]
{
}
[[dynamic-brake_container|dynamic-brake]]
{
}
[[pressure_container|pressure]]
{
}
[[mass_container|mass]]
{
}
[[motor_container|motor]]
{
}
[[flowsize_container|flowsize]]
{
}
[[volume_container|volume]]
{
}
scale ""
epbrakes ""
autopilot-stop-distance 5.0
autopilot-crawl-distance 20.0
autopilot-caution-speed-multiplier 0.5
throttle-adjustment-rate 0.01

====throttle-power====
:Type: [[throttle-power_container|throttle-power Container]]
:Desc: Acceleration variables in cabin mode.

====dynamic-brake====
:Type: [[dynamic-brake_container|dynamic-brake Container]]
:Desc: Deceleration variables while dynamic braking in cabin mode.

====pressure====
:Type: [[pressure_container|pressure Container]]
:Desc:

====mass====
:Type: [[mass_container|mass Container]]
:Desc:

====motor====
:Type: [[motor_container|motor Container]]
:Desc:

====flowsize====
:Type: [[flowsize_container|flowsize Container]]
:Desc:

====volume====
:Type: [[volume_container|volume Container]]
:Desc:

====scale====
:Type: Obsolete
:Desc: Obsolete

====epbrakes====
:Type: Obsolete
:Desc: Obsolete

====autopilot-stop-distance====
:Type: float
:Desc: How far (in meters) in front of a typical obstruction (red light, etc.) the AI will attempt to stop the train. Changing this value can help fine-tune the accuracy of the AI's movement, however attempting to make the train stop too close to a target may result in overruns in some cases. This tag is intended for special-case usage only.

====autopilot-crawl-distance====
:Type: float
:Desc: Once this distance (in meters) from the intended stopping position has been reached, the AI will 'crawl' rather than attempt to speed up to reach its destination. Changing this value can help fine-tune the accuracy of the AI's movement, however attempting to make the train stop too close to a target may result in overruns in some cases. This tag is intended for special-case usage only.

====autopilot-caution-speed-multiplier====
:Type: float
:Desc: The AI will slow to this multiple of the speed limit when operating under caution conditions. This can be set to 1.0 in order to effectively remove caution-speed driving, however this can increase the risk of overruns in some cases

====throttle-adjustment-rate====
:Type: float
:Desc: Defines the adjustment rate at which the engine's throttle will adjust to match the train's throttle. Increasing this rate will make the engine more responsive at the possible cost of audio or driving realism. In DCC mode, a minimum value of 0.1 is used.

==Example Config.txt==
Sample [[config.txt file]] for an enginespec asset, with the Standard Tags excluded for brevity:

''TBD''

==Downloads==
''Attach sample files here?''

==Categories==
[[Category:Asset KIND]]

KIND FixedTrack

2012-10-12T15:38:40Z

Kemal: Redirected page to KIND Fixedtrack

#redirect [[KIND Fixedtrack]]

"attached-track" Container

2012-10-12T11:01:45Z

Kemal: Redirected page to "Attached-track" container

#redirect [["Attached-track" container]]