Class Train

2010-04-13T23:40:39Z

PEV: fixed errors in GetHighBeams

*[[TrainzScript Language Reference|API Hierarchy]]
**[[Class GSObject|GSObject]] *
***[[Class GameObject|GameObject]]
****Train

 
*A train is a collection of vehicles in TRS.
*They act as a single entity and may be controlled using this class.
*A train is placed on a track in script by using [[Class World#CreateTrain|World.CreateTrain()]] or [[Class TrainUtil#CreateTrainFromSoup|TrainUtil.CreateTrainFromSoup()]].
*Trainz will automatically create a Train object for each consist that appears in the game.
*When an existing train is uncoupled and split up into two separate consists a new train object is created.
*Similarly when two trains couple one of the train objects is destroyed.
 

==Messages==
*Messages sent to and from Train objects are listed below:
 
{{TableHeader|width=50%|margin=15px}}
|-
|bgcolor="#EEEEEE"|'''Major'''||bgcolor="#EEEEEE"|'''Minor'''||bgcolor="#EEEEEE"|'''Source'''||bgcolor="#EEEEEE" |'''Destination'''
|-
|Schedule||Abort||Train||Train
|-
|Schedule||Complete||Train||Broadcast
|-
|Schedule||Touch||Train||Train
|-
|[[Train Messages|Train]]||Deleted||Train||
|-
|[[Signal Messages|Train]]||Entered red signal notify||Train||Broadcast
|-
|[[Signal Messages|Train]]||Entered red signal||Signal||Train
|-
|[[Object Messages|Train]]||EnterTrack||Track||Train
|-
|[[Object Messages|Train]]||InnerEnterTrack||Track||Train
|-
|[[Object Messages|Train]]||InnerLeaveTrack||Track||Train
|-
|[[Object Messages|Train]]||LeaveTrack||Track||Train
|-
|[[Train Messages|Train]]||Over advisory speed limit||Train||Broadcast
|-
|[[Train Messages|Train]]||Over floating speed limit||Train||Broadcast
|-
|[[Train Messages|Train]]||Over speed limit||Train||Broadcast
|-
|[[Train Messages|Train]]||ReachedTarget||Train||Train
|-
|[[Train Messages|Train]]||SlowingForTarget||Train||Train
|-
|[[Train Messages|Train]]||StartedMoving||Train||Train
|-
|[[Train Messages|Train]]||StoppedMoving||Train||Train
|-
|[[Train Messages|Train]]||Under advisory speed limit||Train||Broadcast
|-
|[[Train Messages|Train]]||Under floating speed limit||Train||Broadcast
|-
|[[Train Messages|Train]]||Under speed limit||Train||Broadcast
|}
 

==Constants==
 
===Train Control Modes===
 
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int CONTROL_MANUAL = 1||User controls train, script can change settings.
|-
|public define int CONTROL_AUTOPILOT = 2||Autopilot controls train.
|-
|public define int CONTROL_AUTOMANUAL = 3||User controls train, autopilot takes over when train is not currently 'focused'.
|-
|public define int CONTROL_SCRIPT = 4||Only the script can control the train.
|}
 
===Reverser Traction Modes===
 
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int TRACTION_FORWARD = 2||Reverse is in forward setting.
|-
|public define int TRACTION_NEUTRAL = 1||Reverser is in neutral.
|-
|public define int TRACTION_REVERSE = 0||Reverser is in reverse.
|}
 
===Train Brake Modes===
 
{{TableHeader|width=95%|margin=15px}}
|width=375|public define float TRAIN_BRAKE_RELEASE = 0.0||Train brakes are released.
|-
|public define float TRAIN_BRAKE_INITIAL = 1.0||Train brakes are in initial mode.
|-
|public define float TRAIN_BRAKE_APPLICATION = 2.0||Train brakes are applied.
|-
|public define float TRAIN_BRAKE_HANDLE_OFF = 3.0||Train brake handle is off.
|-
|public define float TRAIN_BRAKE_EMERGENCY = 4.0||Train brakes are in emergency stop position.
|-
|public define float TRAIN_BRAKE_LAP = 5.0||Train brakes are in the lap position, not available for all trains.
|}
 
===Dynamic Brake States===
 
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int DYNAMIC_BRAKE_TRACTION = 0||Dynamic brakes in traction mode.
|-
|public define int DYNAMIC_BRAKE_NEUTRAL = 1 ||Dynamic brakes in neutral.
|-
|public define int DYNAMIC_BRAKE_BRAKE = 2 ||Dynamic brakes are on.
|}
 

===Found Results===
 
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int RESULT_NONE = 0||Item not found.
|-
|public define int RESULT_FORWARD = 1||Item is in front of train.
|-
|public define int RESULT_INSIDE = 2||Item is within the train, ie between the front and the rear limits.
|-
|public define int RESULT_BACKWARD = 3||Item is behind the train.
|}
 
===Measurement Conversion Multipliers===
 
{{TableHeader|width=95%|margin=15px}}
|width=375|public define float KPH_TO_MPS = 0.278||Kilometres per hour -> Metres per second.
|-
|public define float MPH_TO_MPS = 0.447||Miles per hour -> Metres per second.
|-
|public define float MPH_TO_KPH = 1.609||Miles per hour -> Kilometres per hour.
|}
 
==Members==
 
{{TableHeader|width=95%|margin=15px}}
|width=375|public Browser timeTableInfo||A publicly accessible Browser object for timetable information.
|}
 
==Methods==
 

===AddVelocity===
{{MethodHeader|public native void AddVelocity(float velocity)}}
;Parameters
*'''velocity''' = Velocity to add to the current speed of the train.
;Returned Value
*None
;Syntax
train.AddVelocity(5.0);
;Notes
*Velocity parameter must be in metres per second and may be negative.
*Use the [[#Measurement Conversion Multipliers|Measurement Conversion Multipliers]] to convert from other units.
 

===ClearTrainTimetable===
{{MethodHeader|public void ClearTrainTimetable(ScenarioBehavior rule)}}
;Parameters
*'''rule''' = rule that called [[#SetTrainTimetable|SetTrainTimetable()]] on this train.
;Returned Value
*None
;Syntax
train.ClearTimeTable(timetableRule);
;Notes
*Clears the train timetable of this train.
*Having cleared the TrainTimetable, it is now safe again to set another TrainTimetable for this train through [[#SetTrainTimetable|SetTrainTimetable()]].
*This method must only be called by the rule which called SetTrainTimetable() in the first place.
*It is the responsibility of the caller to post a (TrainTimetable, Touch) message after calling this function.
 

===DecTrainBusy===
{{MethodHeader|public void DecTrainBusy(void)}}
;Parameters
*None
;Returned Value
*None
;Syntax
train.DecTrainBusy();
;Notes
*Decrements this train's busy count.
*See [[#IsTrainBusy|IsTrainBusy()]] for further details.
 

===Derail===
{{MethodHeader|public native void Derail(void)}}
;Parameters
*None
;Returned Value
*None
;Syntax
train.Derail();
;Notes
*Deliberately derails the train.
 

===EnablePhysics===
{{MethodHeader|public native void EnablePhysics(bool enable)}}
;Parameters
*'''enable''' = True to enable physics calculations for this train, false to disable
;Returned Value
*None
;Syntax
train.EnablePhysics(false);
;Notes
*Turning physics off for scenic rolling stock that the player cannot interact with can boost performance.
*There is no point in doing physic calculations for idle rollingstock.
 

===GetActiveDriver===
{{MethodHeader|public native DriverCharacter GetActiveDriver(void)}}
;Parameters
*None
;Returned Value
*The active driver of this train, null if there is no driver assigned.
;Syntax
DriverCharacter driver = train.GetActiveDriver();
;Notes
*There may be more than one driver on a train but there is only one active driver and an individual Locomotive may only have one driver assigned.
 

===GetAdvisoryLimit===
{{MethodHeader|public native float GetAdvisoryLimit(void)}}
;Parameters
*None
;Returned Value
*The current advisory speed limit set by script.
;Syntax
float speed = train.GetAdvisoryLimit();
;Notes
 

===GetAllowsUserContol===
{{MethodHeader|public native bool GetAllowsUserControl(void)}}
;Parameters
*None
;Returned Value
*True if this train allows the user to control it directly through DCC or Cabin interfaces, false otherwise.
;Syntax
bool canDrive =train.getAllowsUserControl();
;Notes
 

===GetAutopilotMode===
{{MethodHeader|public native int GetAutopilot Mode(void)}}
;Parameters
*None
;Returned Value
*One of the [[#Train Control Modes|Train Control Mode]] constants defining the method by which the train is currently controlled.
;Syntax
int controlMode = train.GetAutopilotMode();
;Notes
 

===GetAutopilotStopJunctionBase===
{{MethodHeader|public native JunctionBase GetAutopilotStopJunctionBase(void)}}
;Parameters
*None
;Returned Value
*The junction object that is preventing the autopilot from taking this train any further, null if the train is not stopped by a junction.
;Syntax
JunctionBase junction = train GetAutopilotStopJunctionBase();
;Notes
 

===GetAutopilotStopTrain===
{{MethodHeader|public native Train GetAutopilotStopTrain(void)}}
;Parameters
*None
;Returned Value
*The train that is preventing the autopilot from taking this train any further, null if the train is not being held up by another train.
;Syntax
Train otherTrain = train.GetAutopilotStopTrain();
;Notes
 

===GetAutopilotTargetSlowing===
{{MethodHeader|public native bool GetAutopilotTargetSlowing(void)}}
;Parameters
*None
;Returned Value
*True if the autopilot is slowing down for its target destination, false otherwise.
;Syntax
bool isSlowing = train.GetAutopilotTargetSlowing();
;Notes
 

===GetDCCThrottle===
{{MethodHeader|public native float GetDCCThrottle(void)}}
;Parameters
*None
;Returned Value
*The DCC throttle setting for this train when using DCC physics.
;Syntax
float throttle = GetDCCThrottle();
;Notes
*The returned value will be in the range [-1.0 .. 1.0] where -1.0 is full throttle in reverse, 0.0 is stationary and 1.0 is full throttle forward.
 

===GetFrontmostLocomotive===
{{MethodHeader|public native Locomotive GetFrontmostLocomotive(void)}}
;Parameters
*None
;Returned Value
*Returns a reference to the frontmost locomotive in the train.
;Syntax
Loco = Train.GetFrontmostLocomotive();
;Notes
*The ''front'' of the train is defined relative to the train's current heading.??
*The train's heading may not correspond to its physical appearance and can change during game play.
 

===GetHeadlightState===
{{MethodHeader|public native bool GetHeadlightState(void)}}
;Parameters
*None
;Returned Value
*True if headlights are turned on, false otherwise.
;Syntax
bool lights = train.GetHeadlightState();
;Notes
*Only the frontmost locomotive will display headlighs.
 

===GetLastVisitedBuildable===
{{MethodHeader|public Buildable GetLastVisitedBuildable(void)}}
;Parameters
*None
;Returned Value
*The last [[Class Buildable|Buildable]] object visited by this train, null if there have been no such visits.
;Syntax
Buildable buildable = train.GetLastVisitedBuildable();
;Notes
 

===GetLastVisitedIndustry===
{{MethodHeader|public Industry GetLastVisitedIndustry(void)}}
;Parameters
*None
;Returned Value
*The last Industry object visited by this train, null if there have been no such visits.
;Syntax
Industry industry = train.GetLastVisitedIndustry();
;Notes
 

===GetLastVisitedTrack===
{{MethodHeader|public Track GetLastVisitedTrack(void)}}
;Parameters
*None
;Returned Value
*The last track segment visited by this train.
;Syntax
Track track = train.GetLastVisitedTrack();
;Notes
*Note that the returned value may be null. How is that possible?
 

===GetHighBeams===
{{MethodHeader|public bool GetHighBeams(void)}}
;Parameters
*None
;Returned Value
*True if the frontmost locomotive's high beams are on, false otherwise.
;Syntax
bool High_Lights = train.GetHighBeams();
;Notes
*See also [[Class Vehicle#GetHighBeams|Vehicle.GetHighBeams()]]
 

===GetMaximumCouplingStressVehicle===
{{MethodHeader|public native Vehicle GetMaximumCouplingStressVehicle(void)}}
;Parameters
*None
;Returned Value
*The Vehicle in this consist that is experiencing the greatest level of coupling stress.
;Syntax
Vehicle vehicle = GetMaximumCouplingStressVehicle();
;Notes
 

===GetPantographState===
{{MethodHeader|public native int GetPantographState(void)}}
;Parameters
*None
;Returned Value
*The state of the pantographs of the electric locomotives in this train.
;Syntax
int pantoState = train.GetPantographState();
;Notes
*The returned value will be in the range [0..3] where:
**0 = Both pantographs down.
**1 = Front pantograph up.
**2 = Rear pantograph up.
**3 = Both pantographs up.
 

===GetSmoothedVelocity===
{{MethodHeader|public native float GetSmoothedVelocity(void)}}
;Parameters
*None
;Returned Value
*Returns a smoothed velocity, intended for human consumption.
;Syntax
float speed = train.GetSmoothedVelocity();
;Notes
*If you require an accurate velocity readout for physics operations, use [[#GetVelocity|GetVelocity()]].
 

===GetSpeedLimit===
{{MethodHeader|public native float GetSpeedLimit(void)}}
;Parameters
*None
;Returned Value
*The current sign posted speed limit.
;Syntax
float permittedSpeed = train.GetSpeedLimit();
;Notes
*The speed limit is dependent on trackside signs placed in Surveyor as well as the direction of the train.
*A default value applies to track that isn't sign posted.
 

===GetTrackmarkDirection===
{{MethodHeader|public native int GetTrackmarkDirection(TrackMark mark)}}
;Parameters
*'''mark''' = A reference to the Trackmark to search for.
;Returned Value
* One of the [[#Found Results|Found Result]] values representing the location of the given track mark relative to this train.
;Syntax
int location = train.GetTrackmarkDirection(trackmark);
;Notes
 

===GetTrainBrakes===
{{MethodHeader|public native float GetTrainBrakes(void)}}
;Parameters
*None
;Returned Value
*One of the [[#Train Brake Modes|Train Brake mode]] constants indicating the current state of this train's brakes.
;Syntax
float brakeState = train.GetTrainBrakes();
;Notes
 

===GetTrainDisplayName===
{{MethodHeader|public native string GetTrainDisplayName(void)}}
;Parameters
*None
;Returned Value
*A localised display name for this train.
;Syntax
string trainName = train.GetTrainDisplayName();
;Notes
*This will be a name Trainz has created for the consist such as "Consist 0" and will match the description shown in the Minimap view.
 

===GetTrainPriorityNumber===
{{MethodHeader|public native int GetTrainPriorityNumber(void)}}
;Parameters
*None
;Returned Value
*Train priority value in the range [1 .. 3]
;Syntax
int priority = train.GetTrainPriorityNumber();
;Notes
*See [[#SetTrainPriority|SetTrainPriority()]] for further details.
 

===GetTrainTimetable===
{{MethodHeader|public TrainTimetable GetTrainTimetable(void)}}
;Parameters
*None
;Returned Value
*The TrainTimetable that the train is currently using, null if there is none.
;Syntax
TrainTimetable timetable = train.GetTrainTimetable();
;Notes
 

===GetVehicles===
{{MethodHeader|public native Vehicle[ ] GetVehicles(void)}}
;Parameters
*None
;Returned Value
*Returns an array consisting of all the vehicles making up this train.
;Syntax
Vehicle[] vehicles = train.GetVehicles();
;Notes
*GetVehicles[0] is always the front vehicle of the train relative to the train's current heading.
*The train's heading may not correspond to its physical appearance and can change during game play.
 

===GetVelocity===
{{MethodHeader|public native float GetVelocity(void)}}
;Parameters
*None
;Returned Value
*The train's current velocity.
;Syntax
float speed = train.GetVelocity();
;Notes
*This function provides the instantaneous velocity for vehicles in this train, which is good for physics calculations but not good for human-readable display.
*See also [[#GetSmoothedVelocity|GetSmoothedVelocity()]].
 

===HasReachedInnerJunctionRadius===
{{MethodHeader|public bool HasReachedJunctionInnerJunctionRadius(JunctionBase junction)}}
;Parameters
*'''junction''' = JunctionBase object to query.
;Returned Value
*True if this train is within the inner radius of the given junction, false otherwise.
;Syntax
bool arrived = train.HasReachedInnerJunctionRadius(junction10);
;Notes
 

===HasTrainTimetable===
{{MethodHeader|public bool HasTrainTimetable(void)}}
;Parameters
*None
;Returned Value
*True if this train has an attached TrainTimetable, false otherwise.
;Syntax
bool timed = train.HasTrainTimetable();
;Notes
 

===IsScheduleRunning===
{{MethodHeader|public bool IsScheduleRunning(void)}}
;Parameters
*None
;Returned Value
*True if this train is currently running to a Schedule, false otherwise.
;Syntax
bool scheduled = train.IsScheduleRunning();
;Notes
 

===IsScheduleWindowVisible===
{{MethodHeader|public bool IsScheduleWindowVisible(void)}}
;Parameters
*None
;Returned Value
*True if the schedule window for this train is currently open, false otherwise.
;Syntax
bool windowOpen = IsScheduleWindowVisible();
;Notes
 

===IsStillInJunction===
{{MethodHeader|public bool IsStillInJunction(JunctionBase junction)}}
;Parameters
*'''junction''' = JunctionBase object to query.
;Returned Value
*True if the train holds a Permit for the given junction, flse otherwise.
;Syntax
bool inJunction = train.IsStillInJunction(junction10);
;Notes
 

===IsStopped===
{{MethodHeader|public native bool IsStopped(void)}}
;Parameters
*None
;Returned Value
*True if the train is currently stationary, false if it is in motion.
;Syntax
bool moving=train.IsMoving();
;Notes
 

===IsTrainBusy===
{{MethodHeader|public bool IsTrainBusy(void)}}
;Parameters
*None
;Returned Value
*True if the train's 'busy' count is greater than zero, false otherwise.
;Syntax
bool busy = train.IsTrainBusy();
;Notes
*Using the [[#IncTrainBusy|IncTrainBusy()]] method, any piece of script code can tag a train being busy.
*The train can be untagged later by calling DecTrainBusy().
*This mechanism is mainly used by industries that are doing something with the train.
*A train can be tagged as being busy more than once by calling IncTrainBusy() multiple times so different industries can tag the train.
*Each time IncTrainBusy() is called, an internal busy count is incremented and if that busy count is greater than zero, the train is considered busy.
 

===IsViewDetailsVisible===
{{MethodHeader|public bool IsViewDetailsVisible(void)}}
;Parameters
*None
;Returned Value
*true if the ViewDetails window for this train is visible, false otherwise.
;Syntax
bool visible = train.IsViewDetailsVisible();
;Notes
 

===MapObjectIsInFront===
{{MethodHeader|public bool MapObjectIsInFront(MapObject obj, float range)}}
;Parameters
*'''obj''' = MapObject to search for.
*'''range''' = Maximum search distance.
;Returned Value
*True if the object is found within the specified distance and in front of the train, false otherwise.
;Syntax
bool isClose = train.MapObjectIsInFront(terminus,100.0);
;Notes
 

===ReleaseTrackPermits===
{{MethodHeader|public void ReleaseTrackPermits(Permit[ ] permitList)}}
;Parameters
*'''permitList''' = Permit array containing a list of permits to release.
;Returned Value
*None
;Syntax
train.ReleaseTrackPermits(permitList);
;Notes
*This method will release any permits from the ''permitList'' array that are currently held by this train.
*Any other permits in the array that are not held by this train will be ignored.
 

===RunSchedule===
{{MethodHeader|public thread void RunSchedule(Schedule schedule, bool loop, float delay)}}
;Parameters
*'''schedule''' = The Schedule that the train is to follow.
*'''loop''' = False to run the schedule once, True to repeat it continuously.
*'''delay''' = Time in seconds to wait before starting the schedule.
;Returned Value
*None
;Syntax
train.RunSchedule(schedule,false,10.0);
;Notes
*See [[Class Schedule|Schedule]] for information on how to build a schedule.
*Only one schedule may run on a train at a time and the user cannot control the train when it is running a schedule.
*This method is a thread, so the calling code does not need to wait for it to finish and return before executing other code.
 

===SetAdvisoryLimit===
{{MethodHeader|public native void SetAdvisoryLimit(float speed)}}
;Parameters
*'''speed''' = Speed limit to set in KPH
;Returned Value
*None
;Syntax
train.SetAdvisoryLimit(60.0);
;Notes
*Sets an advisory speed limit for a script controlled train.
*Use zero in the speed parameter to clear any previously imposed limit.
*Does this really use KPH, most similar methods use MPS
 

===SetAutopilotMode===
{{MethodHeader|public native void SetAutopilotMode(int mode)}}
;Parameters
*'''mode''' = One of the [[#Train Control Modes|Train Control Mode]] constants specifying the method by which this train is controlled.
;Returned Value
*None
;Syntax
train.SetAutopilotMode(Train.CONTROL_AUTOMANUAL);
;Notes
 

===SetAutopilotTarget===
{{MethodHeader|public native void SetAutopilotTarget(Buildable buildable, string trigger) public native void SetAutopilotTarget(Trackside trackside) public native void SetAutopilotTarget(Track track) public native void SetAutopilotTarget(JunctionBase junction)}}
;Parameters
*'''buildable''' = Buildable object to use as a destination.
*'''trigger''' = Attached trigger within the buildable, specified by name.
*'''trackside''' = Trackside object to use as a destination.
*'''track''' = Track segment to use as a destination.
*'''junction''' = JunctionBase object to use as a destination.
;Returned Value
*None
;Syntax
train.SetAutopilotTarget("Kings Cross Station","trigger1");
;Notes
*This method sets a destination for the autopilot to take this train to.
*Objects from respective child classes such as industries, signals and trackmarks may be specified.
 

===SetAutopilotTargetMinimumDistance===
{{MethodHeader|public native void SetAutopilotTargetMinimumDistance(float distance)}}
;Parameters
*'''distance''' = The minimum distance in metres, between the train and the autopilot target, to be reached before the train will start to slow down.
;Returned Value
*None
;Syntax
train SetAutopilotTargetMinimumDistance(100.0);
;Notes
 

===SetAutoPilotTargetMinimumSpeed===
{{MethodHeader|public native void SetAutopilotTargetMinimumSpeed(float speed)}}
;Parameters
*'''speed''' = Minimum speed, in metres per second, that the train should be travelling at when it reaches the Autopilot target.
;Returned Value
*None
;Syntax
train.SetAutoPilotTargetMinimumSpeed(20.0);
;Notes
*The documentation seems to mean that the train should be going at 20.0 OR MORE. Shouldn't it be MaximumSpeed???
 

===SetBail===
{{MethodHeader|public native void SetBail(void)}}
;Parameters
*None
;Returned Value
*None
;Syntax
train.SetBail();
;Notes
*Depresses the bail control for a short period.
 

===SetCouplingMask===
{{MethodHeader|public void SetCouplingMask(int mask)}}
;Parameters
*'''mask''' = A mask specifying which of the trains exposed couplers are allowed to couple.
;Returned Value
*None
;Syntax
train.SetCouplingMask(Vehicle.COUPLE_NONE); // prevents this train from coupling to another in Driver mode.
;Notes
*The mask can be built using the [[Class Vehicle#Coupler Flags|Coupler Flag]] constants defined in [[Class Vehicle]].
*This method will not prevent vehicles or trains from coupling in Surveyor, but takes effect in Driver mode.
 

===SetDCCThrottle===
{{MethodHeader|public native void SetDCCThrottle(float throttle)}}
;Parameters
*'''throttle''' = Float value in the range -1.0 .. 1.0 defining the throttle setting for the train when using DCC physics.
;Returned Value
*None
;Syntax
train.SetDCCThrottle(0.0); //sets the throttle to neutral.
;Notes
*Full speed ahead is 1.0
*Maximum in reverse is -1.0
*Neutral is 0.0
 

===SetDecouplingMask===
{{MethodHeader|public void SetDecouplingMask(int mask)}}
;Parameters
*'''mask''' = A mask specifying which of the couplers are allowed to couple, applies to all of the vehicles in the train.
;Returned Value
*None
;Syntax
train.SetDecouplingMask(Vehicle.COUPLE_FRONT|Vehicle.COUPLE_BACK); // prevents vehicles being uncoupled from the train in Driver mode.
;Notes
*The mask can be built using the [[Class Vehicle#Coupler Flags|Coupler Flag]] constants defined in [[Class Vehicle]].
*This method will not prevent vehicles or trains from being uncoupled in Surveyor, but takes effect in Driver mode.
 

===SetDynamicBrakeMode===
{{MethodHeader|public native void SetDynamicBrakeMode(int mode)}}
;Parameters
*One of the [[#Dynamic Brake States|Dynamic Brake State]] constants indicating the current state of this train's brakes.
;Returned Value
*None
;Syntax
train.SetDynamicBrakeMode(Train.DYNAMIC_BRAKE_TRACTION);
;Notes
 

===SetFloatingLimit===
{{MethodHeader|public native void SetFloatingLimit(float delta, bool enable)}}
;Parameters
*'''delta''' = Tolerance allowed from the posted limit in metres per second.
*'''enable''' = Use true to enable messages related to floating limits, false to disable.
;Returned Value
*None
;Syntax
train.SetFloatingLimit(5.0,true);
;Notes
*Sets the floating speed limit level above the sign posted limit.
*The floating limit is an amount of tolerance above the current speed limit.
*Messages for floating speed violations are not to be confused with regular speed limit messages.
*The floating limit is monitored by the Scenario.Monitor() thread, and may be used for point deduction when speeding. It should therefore be reserved for player trains.
 

===SetHandBrake===
{{MethodHeader|public void SetHandBrake(bool state)}}
;Parameters
*'''state''' = Use true to apply the handbrake to all vehicles in this train which are not Locomotives, false to release the handbrake.
;Returned Value
*None
;Syntax
train.SetHandBrake(true)'
;Notes
 

===SetHeadlightState===
{{MethodHeader|public native void SetHeadlightState(bool lightsOn)}}
;Parameters
*'''lightsOn''' = True to turn the headlights on, false to turn them off.
;Returned Value
*None
;Syntax
train.SetHeadlightState(true);
;Notes
*This method affects only the headlights on the frontmost locomotive.
 

===SetHighBeams===
{{MethodHeader|public void SetHighBeams(bool value)}}
;Parameters
*'''value''' = True to turn on high beams, false to turn them off.
;Returned Value
*None
;Syntax
train.SetHighBeams(true);
;Notes
*See also [[Class Vehicle#SetHighBeams|Vehicle.SetHighBeams()]]
 

===SetLastVisitedBuildable===
{{MethodHeader|public void SetLastVisitedBuildable(Buildable buildable)}}
;Parameters
*'''buildable''' = Sets the last visited buildable to the given object.
;Returned Value
*None
;Syntax
train.SetLastVisitedBuildable(KingsCrossStation);
;Notes
 

===SetManualThrottle===
{{MethodHeader|public native void SetManualThrottle(int notch)}}
;Parameters
*'''notch''' = Value in the range 0 .. 8 to set the throttle.
;Returned Value
*None
;Syntax
train.SetManualThrottle(5);
;Notes
 

===SetPantogaphState===
{{MethodHeader|public native void SetPantographState(int state)}}
;Parameters
*'''state''' = Value in the range 0 .. 3 to set the pantographs if this train has them.
;Returned Value
*None
;Syntax
train.SetPantographState(3);
;Notes
*Use one of these values for ''state'':
**0 = Both pantographs down.
**1 = Front pantograph up.
**2 = Rear pantograph up.
**3 = Both pantographs up.
 

===SetReverser===
{{MethodHeader|public native void SetReverser(int mode)}}
;Parameters
*'''mode''' = One of the [[#Reverser Traction Modes|Reverser Traction Mode]] constants defining the required state of the train's reverser lever.
;Returned Value
*None
;Syntax
train.SetReverser(Train.TRACTION_REVERSE);
;Notes
 

===SetTrainBrakes===
{{MethodHeader|public native void SetTrainBrakes(float mode)}}
;Parameters
*'''mode''' = One of the [[#Train Brake States|Train Brake State]] constants defining the required state of the train's brakes.
;Returned Value
*None
;Syntax
train.SetTrainBrakes(Train.TRAIN_BRAKE_EMERGENCY);
;Notes
 

===SetTrainPriorityNumber===
{{MethodHeader|public native void SetTrainPriority Number(int priority)}}
;Parameters
*'''priority''' = Priority value in the range 1 .. 3.
;Returned Value
*None
;Syntax
train.SetTrainPriorityNumber(2);
;Notes
*All trains and track sections can be assigned a priority value in the range of [1 - 3] with the default value being 2.
*The priority value is not a numerical scale of precedence, but a value for the AI driver to attempt to match.
*This means the driver will ''prefer'' track sections that have a priority equal to that of the train.
*Changing the priority of the train only takes affect when the driver restarts a new schedule.
 

===SetTrainTimetable===
{{MethodHeader|public void SetTrainTimetable(TrainTimetable timetable)}}
;Parameters
*'''timetable''' = Assigns the specified timetable to this train.
;Returned Value
*None
;Syntax
train.SetTrainTimetable(timetable);
;Notes
*This train must not already have a TrainTimetable assigned.
*To ensure that this proviso is met, use [[#ClearTrainTimetabel|ClearTrainTimetable()]] prior to calling this method.
*It is the responsibility of the caller to post a "TrainTimetable","Touch" message after calling this function.
 

===SetVelocity===
{{MethodHeader|public native void SetVelocity(float velocity)}}
;Parameters
*'''velocity''' = Velocity to apply to the train, in metres per second.
;Returned Value
*None
;Syntax
train.SetVelocity(0.0); // stops the train, subject to braking performance.
;Notes
 

===ShowInConsistMenu===
{{MethodHeader|public native void ShowInConsistMenu(bool show)}}
;Parameters
*'''show''' = True to make this train visible to the in-game consist menu, false to hide it.
;Returned Value
*None
;Syntax
train.ShowInConsistMenu(false);
;Notes
 

===SoundHorn===
{{MethodHeader|public native void SoundHorn(void)}}
;Parameters
*None
;Returned Value
*None
;Syntax
train.SoundHorn();
;Notes
*Sounds the horn or whictle for all locomotives in this train.
 

===StopSchedule===
{{MethodHeader|public void StopSchedule(void)}}
;Parameters
*None
;Returned Value
*None
;Syntax
train.StopSchedule();
;Notes
*This method stops the Schedule this train is currently running (if any).
 

===StopScheduleAndWait===
{{MethodHeader|public void StopSchedule(void)}}
;Parameters
*None
;Returned Value
*None
;Syntax
train.StopSchedule();
;Notes
*This method stops the Schedule this train is currently running (if any) and waits until the train's schedule actually stops before returning.
*If the train is not running a schedule, the method returns after broadcasting a "Schedule","Touch" message, in case someone is listening for schedule messages.
 

===StopTrainGently===
{{MethodHeader|public native void StopTrainGently(void)}}
;Parameters
*None
;Returned Value
*None
;Syntax
train.StopTrainGently();
;Notes
*Brings the train to a halt over a short time period.
 

===TakePermitOnTrack===
{{MethodHeader|public Permit[ ] TakePermitOnTrack(bool direction)}}
;Parameters
*'''direction''' = Direction relative to the train in which to take out permits.
;Returned Value
*An array including any permits taken which have not yet been granted to this train. Some of these permits may not yet have been granted.
;Syntax
Permit[] permits = train.TakePermitOnTrack(true);
;Notes
*Gets permits on the current track in the given direction.
 

===TestTrackPermit===
{{MethodHeader|public native bool TestTrackPermit(Permit permit, bool innerOnly)}}
;Parameters
*'''permit''' = An existing Permit object.
*'''innerOnly''' = If true the method will test only the inner radius, if false the default radius of 150 metres will be used.
;Returned Value
*True if this train is within the track controlled by ''permit'', false otherwise.
;Syntax
bool ownPermit = train.TestTrackPermit(permit1,false);
;Notes
*The method generates an exception if the ''permit'' parameter does not refer to a track.
 

===ToggleScheduleWindow===
{{MethodHeader|public void ToggleScheduleWindow(void)}}
;Parameters
*None
;Returned Value
*None
;Syntax
train.ToggleScheduleWindow();
;Notes
*If the schedule window is already open/visible, this method will destroy it.
*Otherwise if the view details window is not visible, UpdateScheduleWindow() is called to create it for display.
 

===ToggleViewDetailsWindow===
{{MethodHeader|public void ToggleViewDetailsWindow(void)}}
;Parameters
*None
;Returned Value
*None
;Syntax
train.ToggleViewDetailsWindow();
;Notes
*If the ViewDetails window is already open/visible, this method will destroy it.
*Otherwise if the view details window is not visible, ViewDetails() is called to create it for display.
 

===TrackSearch===
{{MethodHeader|public native MapObject[ ] TrackSearch(bool direction, float distance)}}
;Parameters
*'''direction''' = Direction to search relative to the train's heading, true for forwards, false for backwards.
*'''distance''' = Maximum search distance in metres.
;Returned Value
*An array of objects found along the track in the defined search direction, the array might be empty.
;Syntax
MapObject[] objects = train.TrackSearch(true,5000.0) // searches 5km forwards along the track.
;Notes
*Gets all of the Trackside and SceneryWithTrack objects on a length of track that is either in front of or behind this train.
*Descendants of these classes are also returned.
 

===TracksideIsInFront===
{{MethodHeader|public bool TracksideIsInFront(Trackside obj, float range)}}
;Parameters
*'''obj''' = Trackside object to search for.
*'''range''' = Mximum search distance.
;Returned Value
*True if the object is logically forward of this train, false otherwise.
;Syntax
bool found = train.TracksideIsInFront(signal1,500.0);
;Notes
 

===Turnaround===
{{MethodHeader|public native void Turnaround(void)}}
;Parameters
*None
;Returned Value
*None
;Syntax
train.Turnaround();
;Notes
*Reverses the logical direction of the train, ie changes its heading.
*The physical direction of the vehicles is not altered but the throttle direction is reversed.
*If the camera is focused on the train in tracking view when this method is called the camera's direction of view (relative to the map) will alter through 180 degrees.
 

===UpdateScheduleWindow===
{{MethodHeader|public void UpdateScheduleWindow(string vehicleName)}}
;Parameters
*'''vehicleName''' = Name of vehicle within the train.
;Returned Value
*None
;Syntax
train.UpdateScheduleWindow("brake2");
;Notes
*Updates the schedule window from the given vehicle.
 

===UpdateViewDetails===
{{MethodHeader|public void UpdateViewDetails(Vehicle vehicle)}}
;Parameters
*'''vehicle''' = Reference to a vehicle within the train.
;Returned Value
*None
;Syntax
train.UpdateViewDetails(vehicle);
;Notes
*Called by Vehicle.UpdateViewDetails() when a vehicle's load has changed so that the train's detail window can be amended.
 

===UpdateViewDetailsLocomotive===
{{MethodHeader|public void UpdateViewDetailsLocomotive(void)}}
;Parameters
*None
;Returned Value
*None
;Syntax
train.UpdateViewDetailsLocomotive(vehicle);
;Notes
*Called by Locomotive.UpdateViewDetails() when any of the Locomotive's operating parameters have changed so that the train's detail window can be amended.
 

===ViewDetails===
{{MethodHeader|public void ViewDetails(Vehicle vehicle)}}
;Parameters
*'''vehicle''' = Reference to a vehicle within the train.
;Returned Value
*None
;Syntax
train.ViewDetails(vehicle);
;Notes
*This method is called by Vehicle.ViewDetails() when the user has requested to view the details of the consist.
*It will create a Browser window listing information about the train including who the driver character is and the loads of all vehicles.
 

===WasRunScheduleSuccessful===
{{MethodHeader|public bool WasRunScheduleSuccessful(void)}}
;Parameters
*None
;Returned Value
*True if the most recently run schedule was successfully, false otherwise.
;Syntax
train.WasRunScheduleSuccessful();
;Notes
 

==Code Examples==
 

==Related Methods==
[[Class TrainUtil#AreInTrain|TrainUtil.AreInTrain()]] 
[[Class TrainUtil#CreateTrainFromSoup|TrainUtil.CreateTrainFromSoup()]] 
[[Class TrainUtil#IsInTrain|TrainUtil.IsInTrain()]] 
[[Class World#CreateTrain|World.CreateTrain()]] 
[[Class World#DeleteTrain|World.DeleteTrain()]] 
[[Class World#GetTrainList|World.GetTrainList()]] 
 

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

TrainzOnline - User contributions [en]

Class Train