Class Vehicle

From TrainzOnline
(Difference between revisions)
Jump to: navigation, search
(SetHeadlightColor)
(added GetFacingRelativeToTrain(void) (obsolete) for repair information)
 
(24 intermediate revisions by 10 users not shown)
Line 1: Line 1:
*[[TrainzScript Language Reference|API Hierarchy]]
+
*[[TrainzScript Library Reference|API Hierarchy]]
 
**[[Class GSObject|GSObject]] *
 
**[[Class GSObject|GSObject]] *
 
***[[Class GameObject|GameObject]]
 
***[[Class GameObject|GameObject]]
Line 11: Line 11:
  
 
*A vehicle is a single piece of rolling stock including locomotives and tenders.
 
*A vehicle is a single piece of rolling stock including locomotives and tenders.
*A vehicle is always part of a train, if a vehicle is decoupled and left alone TRS will create a new consist to include it.
+
*A vehicle is always part of a train, if a vehicle is decoupled and left alone Trainz will create a new consist to include it.
 
<br>
 
<br>
  
Line 21: Line 21:
 
|bgcolor="#EEEEEE"|'''Major'''||bgcolor="#EEEEEE"|'''Minor'''||bgcolor="#EEEEEE"|'''Source'''||bgcolor="#EEEEEE" |'''Destination'''||bgcolor="#EEEEEE" |
 
|bgcolor="#EEEEEE"|'''Major'''||bgcolor="#EEEEEE"|'''Minor'''||bgcolor="#EEEEEE"|'''Source'''||bgcolor="#EEEEEE" |'''Destination'''||bgcolor="#EEEEEE" |
 
|-
 
|-
|[[Vehicle Messages|Vehicle]]||Derailed||Vehicle||Broadcast||Vehicle has derailed and can no longer be used.  
+
|Vehicle||Derailed||Vehicle||Vehicle||Vehicle has derailed and can no longer be driven.  
 
|-
 
|-
|[[Vehicle Messages|Vehicle]]||Coupled||Vehicle||Broadcast||Vehicle has coupled up with another vehicle.  
+
|Vehicle||Coupled||Vehicle||Vehicle (other)||Vehicle has coupled to another Vehicle.
 
|-
 
|-
|[[Vehicle Messages|Vehicle]]||Decoupled||Vehicle||Broadcast||Vehicle has decoupled from another vehicle.  
+
|Vehicle||Decoupled||Vehicle||Vehicle (other)||Vehicle has decoupled from another vehicle.
 
|-
 
|-
|[[Vehicle Messages|Vehicle]]||Bad Couple||Vehicle||Broadcast||Vehicle has coupled with another vehicle at too high a velocity.  
+
|Vehicle||Coupler breakage||Vehicle||Vehicle||Vehicle coupler has broken (likely due to being coupled too fast).
 
|-
 
|-
|[[Vehicle Messages|Vehicle]]||Collided||Vehicle||Broadcast||Vehicle has collided with another vehicle.
+
|Vehicle||BadCouple||Vehicle||Vehicle (other)||Vehicle has coupled with another vehicle at too high a velocity.
 +
|-
 +
|Vehicle||Collided||Vehicle||Vehicle (other)||Vehicle has collided with another vehicle (either a couple was attempted too fast and broke the coupler, or the coupler was already broken).
 
|}
 
|}
 
<br>
 
<br>
 +
*Note: Many of these messages are broadcast prior to TRS19 (and in certain TRS19 compatibility modes). Broadcast messages are being phased out due to poor performance, and should not be used.
  
 
==Constants==
 
==Constants==
Line 79: Line 82:
 
|public define int TYPE_HAS_INTERIOR = 4||Vehicle has an interior. This does not necessarily mean that it is a lcomotive.
 
|public define int TYPE_HAS_INTERIOR = 4||Vehicle has an interior. This does not necessarily mean that it is a lcomotive.
 
|}
 
|}
<br>
+
<br><pre style="color: red">
 +
Having tested these values with the associated function 'GetVehicleTypeFlags', it seems that the 'Vehicle Type Flag' for a loco is '5' and not '1'
 +
vincentrh
 +
 
 +
Perhaps they are bit flags?  Therefore a value of 1 (loco) and 4 (has interior) would result in 5 being returned for a loco with an interior.  i.e. 1 and 4 "OR"ed together.
 +
PCAS1986
 +
</pre>''
  
 
==Members==
 
==Members==
Line 157: Line 166:
 
{{MethodHeader|public native bool Couple(Vehicle other)}}
 
{{MethodHeader|public native bool Couple(Vehicle other)}}
 
;Parameters
 
;Parameters
*''other''' = Adjacent vehicle to couple to.
+
*''other'' = Adjacent vehicle to couple to.
 
;Returned Value
 
;Returned Value
*True if the operation was successfully completed, fale otherwise.
+
*True if the operation was successful, fale otherwise.
 
;Syntax
 
;Syntax
 
  if (Couple(vehicle2)) Interface.Print("Success!");
 
  if (Couple(vehicle2)) Interface.Print("Success!");
 
;Notes
 
;Notes
*Couples this vehicle to the given vehicle which must already be adjacent.
 
*When a vehicle is decoupled from another, the couplers are left in an unlocked state, even though the vehicles are flush against each other.
 
*This state will remain until the vehicles move a small distance apart.
 
*Sometimes you may wish to cause them to couple again and that is the intended use of this method.
 
 
*If the two vehicles involved are not adjacent then this method will have no effect.
 
*If the two vehicles involved are not adjacent then this method will have no effect.
 +
*When a vehicle is decoupled from another, the couplers are left in an unlocked state, even though the vehicles are flush against each other. This state will remain until the vehicles move some distance apart, or the coupler is relocked using this function.
 +
*Coupling two vehicles will merge their Train objects, resulting in one of the trains being deleted. (ie, GetMyTrain() may return a different result after calling this function.) It is not safe for script to predict which Train will be kept, so any cached Train references should be released.
 
<br>
 
<br>
  
Line 279: Line 286:
 
{{MethodHeader|public native int GetCouplingDirection(Vehicle other)}}
 
{{MethodHeader|public native int GetCouplingDirection(Vehicle other)}}
 
;Parameters
 
;Parameters
*''other''' = Adjacent vehicle to couple to.
+
*''other'' = A vehicle to query the coupling direction for. Coupler does not need to be locked.
 
;Returned Value
 
;Returned Value
*One of the [[#Direction Relationships|Direction Relationship]] constants indicating the direction of a neighbouring vehicle, relative to the direction of the caller.
+
*A [[#Coupler Flags|Coupler Flags]] constant indicating which end (if any) the passed vehicle is within coupling range of.
 
;Syntax
 
;Syntax
  bool direction = GetCouplingDirection(vehicle2);
+
  int couplerEnd = vehicle1.GetCouplingDirection(vehicle2);
 +
if (couplerEnd == Vehicle.COUPLE_BACK)
 +
  ; // vehicle2 is coupled to the rear coupler of vehicle1
 
;Notes
 
;Notes
*If the result is DIRECTION_FORWARD then both vehicles have the same orientation.
+
*The return value is not affected by either vehicles train-relative or track-relative facing
*If the result is DIRECTION_BACKWARD then the two vehicles face in opposite directions.
+
*The function may return COUPLE_FRONT/COUPLE_BACK even if the coupler is not 'locked'. I.e. The vehicles may be in different Trains, and the return value may change if one train drives away.
*The fact that this method returns a value does not mean that it is possible for the two vehicles to couple.
+
 
<br>
 
<br>
  
Line 293: Line 301:
 
{{MethodHeader|public native float GetCouplingStress(Vehicle other)}}
 
{{MethodHeader|public native float GetCouplingStress(Vehicle other)}}
 
;Parameters
 
;Parameters
*''other''' = Other vehicle in the same consist to query.
+
*''other'' = The coupled vehicled to check the coupler stress against.
 
;Returned Value
 
;Returned Value
*The calculated coupling stress between the two vehicles in kilonewtons (kN);
+
*The current coupler stress between the two vehicles in newtons (N);
 
;Syntax
 
;Syntax
  float kn = GetCouplingStress(vehicle2);
+
  float stressInNewtons = GetCouplingStress(vehicle2);
 
;Notes
 
;Notes
*<float color=red>Must the two vehicles be adjacent?</font>
+
*This function will throw an exception if the passed vehicle is not coupled at either end.
 +
*The scripter may use Vehicle.GetCouplingDirection() to test if two vehicles are coupled.
 
<br>
 
<br>
  
Line 320: Line 329:
 
*None
 
*None
 
;Returned Value
 
;Returned Value
*The default maximum coupler expansion stress value for this vehicle in kilonewtons (kN), as defined in ''config.txt''.  
+
*The default maximum coupler compression stress value for this vehicle in newtons (N), as defined in ''config.txt''.  
 
;Syntax
 
;Syntax
 
  float DMCS = GetDefaultMaximumCouplerCompressionStress();
 
  float DMCS = GetDefaultMaximumCouplerCompressionStress();
Line 332: Line 341:
 
*None
 
*None
 
;Returned Value
 
;Returned Value
*The default maximum coupler compression stress value for this vehicle in kilonewtons (kN), as defined in ''config.txt''.  
+
*The default maximum coupler expansion stress value for this vehicle in newtons (N), as defined in ''config.txt''.  
 
;Syntax
 
;Syntax
 
  float DMCE = GetDefaultMaximumCouplerExpansionStress();
 
  float DMCE = GetDefaultMaximumCouplerExpansionStress();
Line 356: Line 365:
 
*None
 
*None
 
;Returned Value
 
;Returned Value
*The default maximum tractive effort of this vehicle from its configuration in kilonewtons (kN), as defined in ''config.txt''.  
+
*The default maximum tractive effort of this vehicle from its configuration in newtons (N), as defined in ''config.txt''.  
 
;Syntax
 
;Syntax
 
  float DMTE = GetDefaultMaximumTractiveEffort();
 
  float DMTE = GetDefaultMaximumTractiveEffort();
Line 372: Line 381:
 
  bool vehicleToTrain = GetDirectionRelativeToTrain();
 
  bool vehicleToTrain = GetDirectionRelativeToTrain();
 
;Notes
 
;Notes
 +
Replaces obsolete function GetFacingRelativeToTrain()
 
<br>
 
<br>
  
Line 384: Line 394:
 
;Notes
 
;Notes
 
*Engine parameter strings you can use with this method are:
 
*Engine parameter strings you can use with this method are:
 +
**"applied-force"
 
**"brake-cylinder-pressure"
 
**"brake-cylinder-pressure"
 
**"brake-pipe-pressure"
 
**"brake-pipe-pressure"
**"coal-mass"
 
 
**"current-drawn"
 
**"current-drawn"
 
**"equaliser-pressure"
 
**"equaliser-pressure"
**"fire-temperature"
 
 
**"flow"
 
**"flow"
 
**"horn"
 
**"horn"
 
**"main-reservoir-pressure"
 
**"main-reservoir-pressure"
 +
**"max-te"
 +
**"no3-pipe-pressure"
 +
**"wheelslip"
 +
*values refer only to steam engines:
 +
**"coal-mass"
 +
**"engine-force"
 +
**"fire-temperature"
 
**"max-coal-mass"
 
**"max-coal-mass"
 
**"max-fire-temperature"
 
**"max-fire-temperature"
**"no3-pipe-pressure"
 
 
**"steam-boiler-liquid-percent"
 
**"steam-boiler-liquid-percent"
 
**"steam-boiler-pressure"
 
**"steam-boiler-pressure"
 
**"steam-piston-cycle"
 
**"steam-piston-cycle"
**"wheelslip"
 
**"engine-force"
 
**"applied-force"
 
**"max-te"
 
*Some of the values refer only to steam engines.
 
 
<br>
 
<br>
  
Line 415: Line 425:
 
  int eType = GetEngineType();
 
  int eType = GetEngineType();
 
;Notes
 
;Notes
 +
<br>
 +
 +
===GetFacingRelativeToTrain===
 +
{{MethodHeader|public obsolete native bool GetFacingRelativeToTrain(void) (obsolete)}}
 +
;Parameters
 +
*None
 +
;Returned Value
 +
*True or False relative to which way the train is facing.
 +
;Syntax
 +
bool vehicleToTrain = GetFacingRelativeToTrain();
 +
;Notes
 +
Obsolete function call, use GetDirectionRelativeToTrain() instead.
 +
After replacement, you may or may not get inverse or opposite results, so now true is false, depends on direction, so additional coding may be required to overcome this.
 
<br>
 
<br>
  
Line 463: Line 486:
 
*None
 
*None
 
;Returned Value
 
;Returned Value
*The maximum coupler expansion stress value for this vehicle in kilonewtons (kN).
+
*The maximum coupler compression stress value for this vehicle in newtons (N).
 
;Syntax
 
;Syntax
 
  float MCS = GetMaximumCouplerCompressionStress();
 
  float MCS = GetMaximumCouplerCompressionStress();
Line 475: Line 498:
 
*None
 
*None
 
;Returned Value
 
;Returned Value
*The maximum coupler expansion stress value for this vehicle in kilonewtons (kN).
+
*The maximum coupler expansion stress value for this vehicle in newtons (N).
 
;Syntax
 
;Syntax
 
  float DMCE = GetMaximumCouplerExpansionStress();
 
  float DMCE = GetMaximumCouplerExpansionStress();
Line 511: Line 534:
 
*None
 
*None
 
;Returned Value
 
;Returned Value
*A reference to the train of which this vehicle is part.
+
*A reference to the train which this vehicle is a member of.
 
;Syntax
 
;Syntax
 
  Train train = GetMyTrain();
 
  Train train = GetMyTrain();
 
;Notes
 
;Notes
 
*All vehicles belong to a Train consist, even if a vehicle is not coupled to any other vehicle.
 
*All vehicles belong to a Train consist, even if a vehicle is not coupled to any other vehicle.
 +
*A vehicles Train may change following any coupling operation, and is generally not worth caching. (Ie, don't bother tracking your own Train member variable in custom scripts, just call GetMyTrain() when it's required.)
 +
<br>
 +
 +
===GetOdometerDistance===
 +
{{MethodHeader|public native Train GetOdometerDistance(void)}}
 +
;Parameters
 +
*None
 +
;Returned Value
 +
*The number of meters that this Vehicle has moved.
 +
;Syntax
 +
float distance = GetOdometerDistance();
 +
;Notes
 +
*Returns the total distance that this Vehicle has moved. No assumptions should be made regarding the starting value of the odometer as this may change between vehicles, sessions, or Trainz versions. This value is continuous under normal operation, however calls to SetOdometerDistance() may arbitrarily adjust the current value.
 
<br>
 
<br>
  
Line 550: Line 586:
 
  string fleetId = GetRunningNumber();
 
  string fleetId = GetRunningNumber();
 
;Notes
 
;Notes
*This value is set using [[#SetRunningNumber|SetRunningNumber()]] and should be restricted to alphanumeric characters and paces.
+
*This value can be set using [[#SetRunningNumber|SetRunningNumber()]] and should be restricted to alphanumeric characters and spaces.
 
<br>
 
<br>
  
Line 605: Line 641:
 
*None
 
*None
 
;Returned Value
 
;Returned Value
*One of the [[#Vehicle Type Flags|Vehicle Type Flags]] representing what kind of vehicle the current object is.  
+
*A bitfield of [[#Vehicle Type Flags|Vehicle Type Flags]] representing the characteristics of the vehicle.
 
;Syntax
 
;Syntax
 
  int flags = GetVehicleTypeFlags();
 
  int flags = GetVehicleTypeFlags();
 +
if ((Flags.TestAny(flags, Vehicle.TYPE_HAS_INTERIOR)))
 +
  ; // This vehicle has an interior
 
;Notes
 
;Notes
 +
*The returned flags are a bitfield, and must be treated as such. I.e, do '''not''' test if (GetVehicleTypeFlags() == Vehicle.TYPE_LOCOMOTIVE).
 
<br>
 
<br>
  
Line 777: Line 816:
 
{{MethodHeader|public native void SetDecouplingMask(int mask)}}
 
{{MethodHeader|public native void SetDecouplingMask(int mask)}}
 
;Parameters
 
;Parameters
*'''mask''' = A mask specifying which of the vehilce's couplers are allowed to couple.  
+
*'''mask''' = A mask specifying which of the vehilce's couplers are allowed to decouple.  
 
;Returned Value
 
;Returned Value
 
*None
 
*None
Line 801: Line 840:
 
{{MethodHeader|SetHeadlightColor(float red, float blue, float green)}}
 
{{MethodHeader|SetHeadlightColor(float red, float blue, float green)}}
 
;Parameters
 
;Parameters
*'''red, blue, green''' = RGB components of selected colour, expressed as normalised values.
+
*'''red, blue, green''' = RGB components of selected color, expressed as normalised values.
 
;Returned Value
 
;Returned Value
 
*None
 
*None
 
;Syntax
 
;Syntax
  SetHeadlightColour(0.5,1.0,0.5); // sets colour to RGB:128,255,128
+
  SetHeadlightColor(0.5,1.0,0.5); // sets color to RGB:128,255,128
 
;Notes
 
;Notes
 
*This method controls the color of the illumination produced by the headlights.
 
*This method controls the color of the illumination produced by the headlights.
Line 816: Line 855:
 
{{MethodHeader|public native void SetMaximumCouplerCompressionStress(float stress)}}
 
{{MethodHeader|public native void SetMaximumCouplerCompressionStress(float stress)}}
 
;Parameters
 
;Parameters
*'''stress''' = Maximum ''tensile'' stress in kilonewtons (kN), Use 0.0 to turn off this simulation. ''// please, check this''
+
*'''stress''' = Maximum compression stress in newtons (N). Use 0.0 for no breakage.
 
;Returned Value
 
;Returned Value
 
*None
 
*None
 
;Syntax
 
;Syntax
  SetMaximumCouplerCompressionStress(1500.0);
+
  SetMaximumCouplerCompressionStress(1500000.0);
 
;Notes
 
;Notes
*Sets the maximum coupler expansion stress value for this vehicle.  
+
*Sets the maximum coupler compression stress value for this vehicle.  
*This value refers to the maximum expansion stress which this vehicle's couplers need to experience before they break.
+
*This value refers to the maximum compression stress which this vehicle's couplers need to experience before they break.
 
*This is effectively the stress that a coupler can withstand before it breaks.
 
*This is effectively the stress that a coupler can withstand before it breaks.
 
*As a point of reference, a typical modern knuckle-type coupler can handle approximately 2500 kN of force before breaking.
 
*As a point of reference, a typical modern knuckle-type coupler can handle approximately 2500 kN of force before breaking.
Line 832: Line 871:
 
{{MethodHeader|public native void SetMaximumCouplerExpansionStress(float stress)}}
 
{{MethodHeader|public native void SetMaximumCouplerExpansionStress(float stress)}}
 
;Parameters
 
;Parameters
*'''stress''' = Maximum compression stress in kilonewtons (kN), Use 0.0 to turn off this simulation.
+
*'''stress''' = Maximum expansion stress in newtons (N), Use 0.0 for no breakage.
 
;Returned Value
 
;Returned Value
 
*None
 
*None
 
;Syntax
 
;Syntax
  SetMaximumCouplerExpansionStress(1000.0);
+
  SetMaximumCouplerExpansionStress(1000000.0);
 
;Notes
 
;Notes
*Sets the maximum coupler compression stress value for this vehicle.  
+
*Sets the maximum coupler expansion stress value for this vehicle.  
*This value refers to the maximum compression stress which this vehicle's couplers need to experience before they break.
+
*This value refers to the maximum expansion stress which this vehicle's couplers need to experience before they break.
 
*This is effectively the stress that a coupler can withstand before it breaks.
 
*This is effectively the stress that a coupler can withstand before it breaks.
 
*As a point of reference, a typical modern knuckle-type coupler can handle approximately 2500 kN of force before breaking.
 
*As a point of reference, a typical modern knuckle-type coupler can handle approximately 2500 kN of force before breaking.
Line 848: Line 887:
 
{{MethodHeader|public native void SetMaximumCoupleVelocity(float velocity)}}
 
{{MethodHeader|public native void SetMaximumCoupleVelocity(float velocity)}}
 
;Parameters
 
;Parameters
*'''velocity''' = The maximum speed in metres per second at which this vehicle can be coupled to without breaking a coupler.  
+
*'''velocity''' = The maximum speed in metres per second at which this vehicle can be coupled to another, or 0 for no maximum.
 
;Returned Value
 
;Returned Value
 
*None
 
*None
Line 854: Line 893:
 
  SetMaximumCoupleVelocity(10);
 
  SetMaximumCoupleVelocity(10);
 
;Notes
 
;Notes
*"Vehicle","BadCouple" are broadcast if this speed is exceeded.
+
*Despite the name, the passed value is a speed (ie. unsigned, ie. must be greater than or equal to 0).
*If a value of zero is used "Vehicle","BadCouple" messages will not be issued.
+
*If coupler breakage is enabled, then a coupling attempt above this speed will break the coupler, and post a "Coupler breakage" message, followed by a "Collided" message.
 +
*If coupler breakage is not enabled, hen a coupling attempt above this speed will fail, and post a "BadCouple" message.
 +
*Passing a value of 0.0/zero can be used allow coupling to happen any speed.
 
<br>
 
<br>
  
Line 873: Line 914:
  
 
===SetPitchBasedOnSpeed===
 
===SetPitchBasedOnSpeed===
{{MethodHeader|public native void SetPitchBasedOnSpeed(float factor)}}
+
{{MethodHeader|public native void SetPitchBasedOnSpeed(float multiplier)}}
 
;Parameters
 
;Parameters
*'''factor''' = An arbitrary value used to vary the pitch of the train with its velocity.
+
*'''multiplier''' = The value to multiply the velocity by to get the train pitch angle.
 
;Returned Value
 
;Returned Value
 
*None
 
*None
Line 881: Line 922:
 
  SetPitchBasedOnSpeed(2.5);
 
  SetPitchBasedOnSpeed(2.5);
 
;Notes
 
;Notes
*Pitch is rotation about an axis at right angles to the track direction.
+
*This feature is often used by "non-train" vehicles like helicopters.
 +
*Pitch is the forward/backward rotation of the vehicle mesh (ie, roation about an axis perpendicular to the track direction).
 
<br>
 
<br>
  
Line 911: Line 953:
 
{{MethodHeader|public native bool SetProductRestriction(Asset product)}}
 
{{MethodHeader|public native bool SetProductRestriction(Asset product)}}
 
;Parameters
 
;Parameters
*'''product''' = Asset to to which this vehicle's load is to be restricted.
+
*'''product''' = Asset to which this vehicle's load is to be restricted.
 
;Returned Value
 
;Returned Value
 
*True if successful, false otherwise.
 
*True if successful, false otherwise.
Line 943: Line 985:
  
 
===SetRollBasedOnTrack===
 
===SetRollBasedOnTrack===
{{MethodHeader|public native void SetRollBasedOnTrack(float factor)}}
+
{{MethodHeader|public native void SetRollBasedOnTrack(float multiplier)}}
 
;Parameters
 
;Parameters
*'''factor''' = Arbitrary value used to control the amount of roll.
+
*'''multiplier''' = The value to multiply the curve by to get the train roll angle.
 
;Returned Value
 
;Returned Value
 
*None
 
*None
Line 951: Line 993:
 
  SetRollBasedOnTrack(2.0);
 
  SetRollBasedOnTrack(2.0);
 
;Notes
 
;Notes
*Roll is a rotation about an axis parallel to the track direction.
+
*This feature is often used by "non-train" vehicles like aeroplanes or boats.
 +
*Pitch is the left/right rotation of the vehicle mesh (ie, roation about an axis parallel to the track direction).
 
*Use a positive value to lean 'into' the curve, a negative value to lean out.
 
*Use a positive value to lean 'into' the curve, a negative value to lean out.
 
<br>
 
<br>
Line 992: Line 1,035:
  
 
===Uncouple===
 
===Uncouple===
{{MethodHeader|public native void Uncouple(int end)<br>public native void Uncouple(Vehicle other)}}
+
{{MethodHeader|public native void Uncouple(int direction)<br>public native void Uncouple(Vehicle other)}}
 
;Parameters
 
;Parameters
*'''end''' = One of the [[#Direction Relationships|Direction Relationship]] constants indicating at which end of the current vehicle the uncoupling is to occur.
+
*'''direction''' = A [[#Coupler Flags|Coupler Flags]] constant indicating which coupler to detach.
 
*'''other''' = A reference to the other vehicle form which the caller is to be uncoupled.
 
*'''other''' = A reference to the other vehicle form which the caller is to be uncoupled.
 
;Returned Value
 
;Returned Value
 
*None
 
*None
 
;Syntax
 
;Syntax
  Uncouple(DIRECTION_FORWARD); // uncouple at the current vehicle's front end
+
  Uncouple(COUPLE_FRONT);       // uncouple anything that's attached to the vehicle's front coupler
 
  Uncouple(vehicle1);          // uncouple from the specified vehicle
 
  Uncouple(vehicle1);          // uncouple from the specified vehicle
 
;Notes
 
;Notes
*This method will always cause another Train object to be created.
+
*Uncoupling will cause another Train object to be created for one half of the train.
*The current Train reference will remain on the section of the previous train with the most drivers declared.
+
*Caling Uncouple(COUPLE_BOTH) is not valid, you must specify a single coupler.
 +
*See also Vehicle.GetCouplingDirection().
 
<br>
 
<br>
  
Line 1,073: Line 1,117:
 
*None
 
*None
 
;Notes
 
;Notes
*In ts12 only.
+
*In TS12 and greater only.
 
*Override this function as required, but don't forget to call the inherited version in case it does something in the future.
 
*Override this function as required, but don't forget to call the inherited version in case it does something in the future.
 
*Attempting to manipulate the makeup or positioning of any Train from within this function is illegal behavior. If you need to do that, trigger a delayed action using a message or a thread.
 
*Attempting to manipulate the makeup or positioning of any Train from within this function is illegal behavior. If you need to do that, trigger a delayed action using a message or a thread.

Latest revision as of 00:16, 15 September 2022


  • A vehicle is a single piece of rolling stock including locomotives and tenders.
  • A vehicle is always part of a train, if a vehicle is decoupled and left alone Trainz will create a new consist to include it.


Contents

[edit] Related Messages

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


Major Minor Source Destination
Vehicle Derailed Vehicle Vehicle Vehicle has derailed and can no longer be driven.
Vehicle Coupled Vehicle Vehicle (other) Vehicle has coupled to another Vehicle.
Vehicle Decoupled Vehicle Vehicle (other) Vehicle has decoupled from another vehicle.
Vehicle Coupler breakage Vehicle Vehicle Vehicle coupler has broken (likely due to being coupled too fast).
Vehicle BadCouple Vehicle Vehicle (other) Vehicle has coupled with another vehicle at too high a velocity.
Vehicle Collided Vehicle Vehicle (other) Vehicle has collided with another vehicle (either a couple was attempted too fast and broke the coupler, or the coupler was already broken).


  • Note: Many of these messages are broadcast prior to TRS19 (and in certain TRS19 compatibility modes). Broadcast messages are being phased out due to poor performance, and should not be used.

[edit] Constants


[edit] Coupler Flags


public define int COUPLE_NONE = 0 Neither coupler.
public define int COUPLE_FRONT = 1 Front coupler.
public define int COUPLE_BACK = 2 Back coupler.
public define int COUPLE_BOTH = COUPLE_FRONT ¦ COUPLE_BACK Both couplers.


[edit] Direction Relationships


public define int DIRECTION_NONE = 0 No known relationship.
public define int DIRECTION_FORWARD = 1 Forward, facing in the same direction.
public define int DIRECTION_BACKWARD = -1 Backward, facing in opposite directions.


[edit] Engine Types


public define int ENGINE_NONE = 0 Not a powered vehicle.
public define int ENGINE_STANDARD = 1 Diesel, Diesel-Electric, Electric.
public define int ENGINE_STEAM = 2 Steam powered.


[edit] Vehicle Type Flags


public define int TYPE_LOCOMOTIVE = 1 Vehicle is a powered locomotive.
public define int TYPE_TENDER = 2 Vehicle carries fuel for a locomotive.
public define int TYPE_HAS_INTERIOR = 4 Vehicle has an interior. This does not necessarily mean that it is a lcomotive.

Having tested these values with the associated function 'GetVehicleTypeFlags', it seems that the 'Vehicle Type Flag' for a loco is '5' and not '1'
vincentrh

Perhaps they are bit flags?  Therefore a value of 1 (loco) and 4 (has interior) would result in 5 being returned for a loco with an interior.  i.e. 1 and 4 "OR"ed together.
PCAS1986

[edit] Members


public IndustryProductInfoCollection vehicleProductInfoCollection A data object that allows tracking of products and associated assets & queues.


[edit] Methods


[edit] BeginLoad

float BeginLoad(LoadingReport report)
Parameters
  • report = Report on the current state of the loading operation.
Returned Value
  • The time required, in seconds, for the activity to complete.
Syntax
float BeginLoad(LoadingReport report) {
   DoStuff(report);
   return 10.0;
}
Notes
  • This is a callback method which should be overridden by the script writer to perform customised activities before loading at an industry.
  • These include such operations as particle effects and animations.
  • The report parameter provides details of the industries and vehicles involved and of their spatial relationship.
  • It is the responsibility of the script writer to determine the time required for these activities and to return this in the method result.


[edit] BeginUnload

float BeginUnload(LoadingReport report)
Parameters
  • report = Report on the current state of the loading operation.
Returned Value
  • The time required, in seconds, for the activity to complete.
Syntax
float BeginLoad(LoadingReport report) {
   DoStuff(report);
   return 10.0;
}
Notes
  • This is a callback method which should be overridden by the script writer to perform customised activities before loading at an industry.
  • These include such operations as particle effects and animations.
  • The report parameter provides details of the industries and vehicles involved and of their spatial relationship.
  • It is the responsibility of the script writer to determine the time required for these activities and to return this in the method result.


[edit] CanLoadProductFromQueue

public bool CanLoadProductFromQueue(ProductQueue queue)
Parameters
  • queue = The queue to be queried.
Returned Value
  • True if the vehicle and queue are compatible and the queue can be used to load the vehicle, false otherwise.
  • None
Syntax
if (CanLoadProductFromQueue(industryOutQueue)) {
   DoTheProcess();
}
Notes


[edit] CanUnloadProductToQueue

public bool CanUnloadProductToQueue(ProductQueue queue)
Parameters
  • queue = The queue to be queried.
Returned Value
  • True if the vehicle and queue are compatible and the queue can be used to unload the vehicle, false otherwise.
Syntax
if (CanUnloadProductToQueue(industryOutQueue)) {
   DoTheProcess();
}
Notes


[edit] Couple

public native bool Couple(Vehicle other)
Parameters
  • other = Adjacent vehicle to couple to.
Returned Value
  • True if the operation was successful, fale otherwise.
Syntax
if (Couple(vehicle2)) Interface.Print("Success!");
Notes
  • If the two vehicles involved are not adjacent then this method will have no effect.
  • When a vehicle is decoupled from another, the couplers are left in an unlocked state, even though the vehicles are flush against each other. This state will remain until the vehicles move some distance apart, or the coupler is relocked using this function.
  • Coupling two vehicles will merge their Train objects, resulting in one of the trains being deleted. (ie, GetMyTrain() may return a different result after calling this function.) It is not safe for script to predict which Train will be kept, so any cached Train references should be released.


[edit] EndLoad

float EndLoad(LoadingReport report)
Parameters
  • report = Report on the current state of the loading operation.
Returned Value
  • The time required, in seconds, for the activity to complete.
Syntax
float EndLoad(LoadingReport report) {
   DoStuff(report);
   return 10.0;
}
Notes
  • This is a callback method which should be overridden by the script writer to perform customised activities after loading at an industry.
  • These include such operations as particle effects and animations.
  • The report parameter provides details of the industries and vehicles involved and of their spatial relationship.
  • It is the responsibility of the script writer to determine the time required for these activities and to return this in the method result.


[edit] EndUnload

float EndUnload(LoadingReport report)
Parameters
  • report = Report on the current state of the loading operation.
Returned Value
  • The time required, in seconds, for the activity to complete.
Syntax
float EndUnload(LoadingReport report) {
   DoStuff(report);
   return 10.0;
}
Notes
  • This is a callback method which should be overridden by the script writer to perform customised activities after unloading at an industry.
  • These include such operations as particle effects and animations.
  • The report parameter provides details of the industries and vehicles involved and of their spatial relationship.
  • It is the responsibility of the script writer to determine the time required for these activities and to return this in the method result.


[edit] GetAuxReservoirPressure

public native float GetAuxReservoirPressure(void)
Parameters
  • None
Returned Value
  • The current auxiliary reservoir pressure of this vehicle.
Syntax
float ARP = GetAuxReservoirPressure();
Notes


[edit] GetBogeyList

public native Bogey[ ] GetBogeyList(void)
Parameters
  • None
Returned Value
  • An array containing references to all the Bogey objects attached to this vehicle.
Syntax
Bogey[] bogies = GetBogeyList();
Notes
  • Bogies are indexed in the same numerical order as they are listed in config.txt.
  • Invisible bogies etc. are included.


[edit] GetBrakeCylinderPressure

public native float GetBrakeCylinderPressure(void)
Parameters
  • None
Returned Value
  • The current brake cylinder pressure of this vehicle.
Syntax
float BCP = GetBrakeCylinderPressure();
Notes


[edit] GetBrakePipePressure

public native float GetBrakePipePressure(void)
Parameters
  • None
Returned Value
  • The current brake pipe pressure of this vehicle.
Syntax
float BPP = GetBrakePipePressure();
Notes


[edit] GetCabinSwayAmount

public native float GetCabinSwayAmount(void)
Parameters
  • None
Returned Value
  • The cabin sway amount for this vehicle.
Syntax
float CSA = GetCabinSwayAmount();
Notes
  • Higher positive values indicate higher levels of cabin sway while a 0.0 indicates no cabin sway.
  • See also SetCabinSwayAmount().


[edit] GetCouplerBreakageEnabled

public native bool GetCouplerBreakageEnabled(void)
Parameters
  • None
Returned Value
  • True if coupler breakages are enabled on this vehicle, false otherwise.
Syntax
if (GetCouplerBreakageEnabled()) Interface.Print("Drive carefully to avoid breaking the couplers");
Notes


[edit] GetCouplingDirection

public native int GetCouplingDirection(Vehicle other)
Parameters
  • other = A vehicle to query the coupling direction for. Coupler does not need to be locked.
Returned Value
  • A Coupler Flags constant indicating which end (if any) the passed vehicle is within coupling range of.
Syntax
int couplerEnd = vehicle1.GetCouplingDirection(vehicle2);
if (couplerEnd == Vehicle.COUPLE_BACK)
  ; // vehicle2 is coupled to the rear coupler of vehicle1
Notes
  • The return value is not affected by either vehicles train-relative or track-relative facing
  • The function may return COUPLE_FRONT/COUPLE_BACK even if the coupler is not 'locked'. I.e. The vehicles may be in different Trains, and the return value may change if one train drives away.


[edit] GetCouplingStress

public native float GetCouplingStress(Vehicle other)
Parameters
  • other = The coupled vehicled to check the coupler stress against.
Returned Value
  • The current coupler stress between the two vehicles in newtons (N);
Syntax
float stressInNewtons = GetCouplingStress(vehicle2);
Notes
  • This function will throw an exception if the passed vehicle is not coupled at either end.
  • The scripter may use Vehicle.GetCouplingDirection() to test if two vehicles are coupled.


[edit] GetDefaultCabinSwayAmount

public native float GetDefaultCabinSwayAmount(void)
Parameters
  • None
Returned Value
  • The default cabin sway amount for this vehicle as defined in config.txt.
Syntax
float CSA = GetCabinSwayAmount();
Notes
  • Higher positive values indicate higher levels of cabin sway while a 0.0 indicates no cabin sway.
  • See also SetCabinSwayAmount().


[edit] GetDefaultMaximumCouplerCompressionStress

publc native float GetDefaultMaximumCouplerCompressionStress(void)
Parameters
  • None
Returned Value
  • The default maximum coupler compression stress value for this vehicle in newtons (N), as defined in config.txt.
Syntax
float DMCS = GetDefaultMaximumCouplerCompressionStress();
Notes


[edit] GetDefaultMaximumCouplerExpansionStress

public native float GetDefaultMaximumCouplerExpansionStress(void)
Parameters
  • None
Returned Value
  • The default maximum coupler expansion stress value for this vehicle in newtons (N), as defined in config.txt.
Syntax
float DMCE = GetDefaultMaximumCouplerExpansionStress();
Notes


[edit] GetDefaultMaximumCoupleVelocity

public native float GetDefaultMaximumCoupleVelocity(void)
Parameters
  • None
Returned Value
  • The default maximum speed at which this vehicle can be coupled to without breaking the coupler, as defined in config.txt.
Syntax
float DMCV = GetDefaultMaximumCoupleVelocity();
Notes


[edit] GetDefaultMaximumTractiveEffort

GetDefaultMaximumTractiveEffort()
Parameters
  • None
Returned Value
  • The default maximum tractive effort of this vehicle from its configuration in newtons (N), as defined in config.txt.
Syntax
float DMTE = GetDefaultMaximumTractiveEffort();
Notes


[edit] GetDirectionRelativeToTrain

public native bool GetDirectionRelativeToTrain(void)
Parameters
  • None
Returned Value
  • True if this vehicle faces in the same direction as the train's current heading, false otherwise.
Syntax
bool vehicleToTrain = GetDirectionRelativeToTrain();
Notes

Replaces obsolete function GetFacingRelativeToTrain()

[edit] GetEngineParam

public native float GetEngineParam(string param)
Parameters
  • param = One of the engine parameter strings listed below.
Returned Value
  • The current value of the given engine parameter.
Syntax
float pressure = GetEngineParam("steam-boiler-pressure");
Notes
  • Engine parameter strings you can use with this method are:
    • "applied-force"
    • "brake-cylinder-pressure"
    • "brake-pipe-pressure"
    • "current-drawn"
    • "equaliser-pressure"
    • "flow"
    • "horn"
    • "main-reservoir-pressure"
    • "max-te"
    • "no3-pipe-pressure"
    • "wheelslip"
  • values refer only to steam engines:
    • "coal-mass"
    • "engine-force"
    • "fire-temperature"
    • "max-coal-mass"
    • "max-fire-temperature"
    • "steam-boiler-liquid-percent"
    • "steam-boiler-pressure"
    • "steam-piston-cycle"


[edit] GetEngineType

public native int GetEngineType(void)
Parameters
  • None
Returned Value
  • One of the Engine Type constants describing the engine type of this vehicle.
Syntax
int eType = GetEngineType();
Notes


[edit] GetFacingRelativeToTrain

public obsolete native bool GetFacingRelativeToTrain(void) (obsolete)
Parameters
  • None
Returned Value
  • True or False relative to which way the train is facing.
Syntax
bool vehicleToTrain = GetFacingRelativeToTrain();
Notes

Obsolete function call, use GetDirectionRelativeToTrain() instead. After replacement, you may or may not get inverse or opposite results, so now true is false, depends on direction, so additional coding may be required to overcome this.

[edit] GetLength

public native float GetLength(void)
Parameters
  • None
Returned Value
  • The length of this vehicle in metres.
Syntax
float length = GetLength();
Notes


[edit] GetLoadTime

float GetLoadTime(LoadingReport report)
Parameters
  • report = Report on the current state of the loading operation.
Returned Value
  • The time required, in seconds, for the activity to complete.
Syntax
float GetLoadTime(LoadingReport report) {
   DoStuff(report);
   return 10.0;
}
Notes
  • This is a callback method which informs the game engine of the time needed to load this vehicle.
  • The method may be use to perform customised activities during the loading operation.
  • These include such operations as particle effects and animations.
  • The report parameter provides details of the industries and vehicles involved and of their spatial relationship.
  • It is the responsibility of the script writer to determine the time required for these activities and to return this in the method result.


[edit] GetMass

public native float GetMass(void)
Parameters
  • None
Returned Value
  • The mass of the vehicle in kilograms.
Syntax
float mass = GetMass();
Notes


[edit] GetMaximumCouplerCompressionStress

publc native float GetMaximumCouplerCompressionStress(void)
Parameters
  • None
Returned Value
  • The maximum coupler compression stress value for this vehicle in newtons (N).
Syntax
float MCS = GetMaximumCouplerCompressionStress();
Notes


[edit] GetMaximumCouplerExpansionStress

public native float GetMaximumCouplerExpansionStress(void)
Parameters
  • None
Returned Value
  • The maximum coupler expansion stress value for this vehicle in newtons (N).
Syntax
float DMCE = GetMaximumCouplerExpansionStress();
Notes


[edit] GetMaximumCoupleVelocity

public native float GetMaximumCoupleVelocity(void)
Parameters
  • None
Returned Value
  • The maximum speed at which this vehicle can be coupled to without breaking the coupler.
Syntax
float MCV = GetMaximumCoupleVelocity();
Notes


[edit] GetMaximumTractiveEffort

GetMaximumTractiveEffort()
Parameters
  • None
Returned Value
  • The maximum tractive effort of this vehicle from its configuration in newtons (N).
Syntax
float MTE = GetMaximumTractiveEffort();
Notes


[edit] GetMyTrain

public native Train GetMyTrain(void)
Parameters
  • None
Returned Value
  • A reference to the train which this vehicle is a member of.
Syntax
Train train = GetMyTrain();
Notes
  • All vehicles belong to a Train consist, even if a vehicle is not coupled to any other vehicle.
  • A vehicles Train may change following any coupling operation, and is generally not worth caching. (Ie, don't bother tracking your own Train member variable in custom scripts, just call GetMyTrain() when it's required.)


[edit] GetOdometerDistance

public native Train GetOdometerDistance(void)
Parameters
  • None
Returned Value
  • The number of meters that this Vehicle has moved.
Syntax
float distance = GetOdometerDistance();
Notes
  • Returns the total distance that this Vehicle has moved. No assumptions should be made regarding the starting value of the odometer as this may change between vehicles, sessions, or Trainz versions. This value is continuous under normal operation, however calls to SetOdometerDistance() may arbitrarily adjust the current value.


[edit] GetProductRestriction

public ProductFilter GetProductRestriction(void)
Parameters
  • None
Returned Value
  • The current product restriction filter if any, null otherwise.
Syntax
ProductFilter filter = GetProductRestriction();
Notes


[edit] GetRelationToTrack

public native int GetRelationToTrack(Buildable obj, string trackName)
Parameters
  • obj = Reference to a Buildable object.
  • trackName = String representing the name of a track as defined in the Buildable's config.txt.
Returned Value
  • One of the Direction Relationship constants indicating the direction of the vehicle, relative to the Buildable's attached track.
Syntax
  • This method will return either DIRECTION_FORWARD or DIRECTION_BACKWARD if the vehicle is on the track as specified by the arguments or on a directly neighboring track, otherwise DIRECTION_NONE will be returned.
Notes


[edit] GetRunningNumber

public native string GetRunningNumber(void)
Parameters
  • None
Returned Value
  • The running (fleet identification) number of the vehicle.
Syntax
string fleetId = GetRunningNumber();
Notes
  • This value can be set using SetRunningNumber() and should be restricted to alphanumeric characters and spaces.


[edit] GetSandingTractionMultiplier

public native float GetSandingTractionMultiplier(void)
Parameters
  • None
Returned Value
  • A wheelslip traction multiplier to apply when sand is in use.
Syntax
float slipFactor = GetSandingTractionMultiplier();
Notes


[edit] GetTrackGradient

public native float GetTrackGradient(void)
Parameters
  • None
Returned Value
  • The current track gradient as a percentage.
Syntax
float gradient = GetTrackGradient();
Notes
  • The sign of the gradient is determined by the direction of this vehicle relative to the gradient.
  • A negative sign indicates that the vehicle is facing down a gradient while a positive sign indicates the vehicle is facing up a gradient.
  • The vehicle's direction may not match that of the train so the value returned here may not be what you expect.
  • Use GetDirectionRelativeToTrain() to check this.


[edit] GetUnloadTime

float GetUnloadTime(LoadingReport report)
Parameters
  • report = Report on the current state of the loading operation.
Returned Value
  • The time required, in seconds, for the activity to complete.
Syntax
float GetUnloadTime(LoadingReport report) {
   DoStuff(report);
   return 10.0;
}
Notes
  • This is a callback method which informs the game engine of the time needed to unload this vehicle.
  • The method may be use to perform customised activities during the unloading operation.
  • These include such operations as particle effects and animations.
  • The report parameter provides details of the industries and vehicles involved and of their spatial relationship.
  • It is the responsibility of the script writer to determine the time required for these activities and to return this in the method result.


[edit] GetVehicleTypeFlags

public native int GetVehicleTypeFlags(void)
Parameters
  • None
Returned Value
Syntax
int flags = GetVehicleTypeFlags();
if ((Flags.TestAny(flags, Vehicle.TYPE_HAS_INTERIOR)))
  ; // This vehicle has an interior
Notes
  • The returned flags are a bitfield, and must be treated as such. I.e, do not test if (GetVehicleTypeFlags() == Vehicle.TYPE_LOCOMOTIVE).


[edit] GetVelocity

public native float GetVelocity(void)
Parameters
  • None
Returned Value
  • The current instantaneous velocity of the train in metres per second.
Syntax
float speed = GetVelocity();
Notes


[edit] GetWheelslipTractionMultiplier

public native float GetWheelslipTractionMultiplier(void)
Parameters
  • None
Returned Value
  • The current wheelslip traction multiplier value.
Syntax
float slip = GetWheelslipTractionMultiplier();
Notes


[edit] IsInTunnel

public native bool IsInTunnel(void)
Parameters
  • None
Returned Value
  • True if this vehicle is in a tunnel, false otherwise.
Syntax
bool underground = IsInTunnel();
Notes


[edit] IsOnBridge

public native void IsOnBridge(void)
Parameters
  • None
Returned Value
  • True if this vehicle is on a bridge, false otherwise.
Syntax
bool onBridge = IsOnBridge();
Notes


[edit] LoadProduct

public bool LoadProduct(LoadingReport report)
Parameters
  • report = Report on the current state of the loading operation.
Returned Value
  • True if the loading operation was successful, false otherwise.
Syntax
LoadProduct(report);
Notes
  • Loads products into this vehicle as defined by the given report.
  • This method works by attempting to transfer products to this vehicle's queues if possible from the industry queue specified in report.
  • The sequence of events for a loading operation as performed by this method is:
    • Verify that an loading operation is possible with this vehicle by calling CanLoadProductFromQueue().
    • BeginLoad() on this vehicle and Industry.BeginLoad() on the industry specified in the report are called to perform any pre-loading events like animation or particle effects on the vehicle and industry respectively.
    • Both of these methods return the amount of time required for a load operation and the LoadProduct() method sleeps for which ever of these times is the longer.
    • The actual product transfer from the industry to the vehicle is performed by calling ProductQueue.TransferProductFrom() on this vehicle's queue(s).
    • GetLoadTime() on this vehicle and Industry.GetLoadTime() are called. Again, LoadProduct() sleeps for which ever is the longer of the times returned.
    • EndLoad() and Industry.EndLoad() are called to perform any post-loading events. As before LoadProduct() sleeps for the longer time.


[edit] Reposition

public native bool Reposition(Train train, int myCoupleDir, int otherCoupleDir)
public native bool Reposition(Vehicle vehicle, int myCoupleDir, int otherCoupleDir)
public native bool Reposition(TrackMark mark, bool direction)
Parameters
  • train = Train to attach the vehicle to.
  • vehicle = Vehicle to attach the vehicle to.
  • myCoupleDir = The end of the current vehicle that will be coupled, use either COUPLE_FRONT or COUPLE_BACK.
  • otherCoupleDir = The end of the target vehicle that will be coupled to, use either COUPLE_FRONT or COUPLE_BACK.
  • mark = Trackmark to move this vehicle to.
  • direction = Direction for the vehicle, relative to the TrackMark.
  • None
Returned Value
  • True if the operation was successfully completed, false otherwise.
Syntax
Reposition(Train3,COUPLE_FRONT,COUPLE_BACK);
Reposition(Vehicle5,COUPLE_FRONT,COUPLE_BACK);
Reposition(Mark9,true);
Notes
  • Variant 1 moves the current vehicle and couples it to the specified train using the specified vehicle ends.
  • Variant 2 moves the current vehicle and couples it to the specified vehicle using the specified vehicle ends.
  • Variant 3 moves the current vehicle from its train to the specified trackmark, normally creating a new consist.


[edit] Reverse

public native bool Reverse(void)
Parameters
  • None
Returned Value
  • True if the operation was successfully completed, false otherwise.
Syntax
if (Reverse()) Interface.Print("Direction of " + GetName() + " reversed");
Notes
  • This method reverses the direction of the current vehicle in relation to its consist.


[edit] SetBrakePipeEfficiency

public native void SetBrakePipeEfficiency(float efficiency)
Parameters
  • efficiency = A Normalised value in the range 0.0 .. 1.0 representing the efficiency of the brake pipe.
Returned Value
  • None
Syntax
SetBrakePipeEfficiency(0.5);
Notes


[edit] SetBrokenBrakes

public native void SetBrokenBrakes(bool broken)
Parameters
  • broken = True to render the brakes non operational, false to repair them.
Returned Value
  • None
Syntax
SetBrokenBrakes(true);
Notes


[edit] SetCabinSwayAmount

public native void SetCabinSwayAmount(float amount)
Parameters
  • amount = Cabin sway value greater than or equal to zero.
Returned Value
  • None
Syntax
SetCabinSwayAmount(2.5);
Notes
  • A value of zero removes all sway.
  • Higher positive values increase the effect.
  • The method is only of relevance to vehicles with interior views.


[edit] SetCouplerBreakageEnabled

public native void SetCouplerBreakageEnabled(bool enabled)
Parameters
  • enabled = True enables simulation of coupler breakage.
  • None
Returned Value
  • None
Syntax
SetCouplerBreakageEnabled(true);
Notes


[edit] SetCouplingMask

public native void SetCouplingMask(int mask)
Parameters
  • mask = A mask specifying which of the vehilce's couplers are allowed to couple.
Returned Value
  • None
Syntax
SetCouplingMask(COUPLE_NONE); // prevents this vehicle from coupling to another in Driver mode.
Notes
  • The mask can be built using the Coupler Flag constants.
  • This method will not prevent vehicles from coupling in Surveyor, but takes effect in Driver mode.


[edit] SetDecouplingMask

public native void SetDecouplingMask(int mask)
Parameters
  • mask = A mask specifying which of the vehilce's couplers are allowed to decouple.
Returned Value
  • None
Syntax
SetDecouplingMask(COUPLE_NONE); // prevents this vehicle from uncoupling in Driver mode.
Notes
  • The mask can be built using the Coupler Flag constants.
  • This method will not prevent vehicles from uncoupling in Surveyor, but takes effect in Driver mode.


[edit] SetHandbrake

public native void SetHandBrake(bool applied)
Parameters
  • applied = If true the handbrake is applied, if false the handbrake is released.
Returned Value
  • None
Syntax
SetHandBrake(true);
Notes


[edit] SetHeadlightColor

SetHeadlightColor(float red, float blue, float green)
Parameters
  • red, blue, green = RGB components of selected color, expressed as normalised values.
Returned Value
  • None
Syntax
SetHeadlightColor(0.5,1.0,0.5); // sets color to RGB:128,255,128
Notes
  • This method controls the color of the illumination produced by the headlights.
  • It does not affect the "diffuse" component of illumination (this component remains white). Works correctly with ground and bump-mapped meshes only.
  • It does not affect the color of the headlight coronas.
  • This should method not be used to "turn off" the headlights, as even a black light will consume CPU time with lighting calculations.


[edit] SetMaximumCouplerCompressionStress

public native void SetMaximumCouplerCompressionStress(float stress)
Parameters
  • stress = Maximum compression stress in newtons (N). Use 0.0 for no breakage.
Returned Value
  • None
Syntax
SetMaximumCouplerCompressionStress(1500000.0);
Notes
  • Sets the maximum coupler compression stress value for this vehicle.
  • This value refers to the maximum compression stress which this vehicle's couplers need to experience before they break.
  • This is effectively the stress that a coupler can withstand before it breaks.
  • As a point of reference, a typical modern knuckle-type coupler can handle approximately 2500 kN of force before breaking.
  • This is roughly equivalent to the weight of 2.5 million apples.


[edit] SetMaximumCouplerExpansionStress

public native void SetMaximumCouplerExpansionStress(float stress)
Parameters
  • stress = Maximum expansion stress in newtons (N), Use 0.0 for no breakage.
Returned Value
  • None
Syntax
SetMaximumCouplerExpansionStress(1000000.0);
Notes
  • Sets the maximum coupler expansion stress value for this vehicle.
  • This value refers to the maximum expansion stress which this vehicle's couplers need to experience before they break.
  • This is effectively the stress that a coupler can withstand before it breaks.
  • As a point of reference, a typical modern knuckle-type coupler can handle approximately 2500 kN of force before breaking.
  • This is roughly equivalent to the weight of 2.5 million apples.


[edit] SetMaximumCoupleVelocity

public native void SetMaximumCoupleVelocity(float velocity)
Parameters
  • velocity = The maximum speed in metres per second at which this vehicle can be coupled to another, or 0 for no maximum.
Returned Value
  • None
Syntax
SetMaximumCoupleVelocity(10);
Notes
  • Despite the name, the passed value is a speed (ie. unsigned, ie. must be greater than or equal to 0).
  • If coupler breakage is enabled, then a coupling attempt above this speed will break the coupler, and post a "Coupler breakage" message, followed by a "Collided" message.
  • If coupler breakage is not enabled, hen a coupling attempt above this speed will fail, and post a "BadCouple" message.
  • Passing a value of 0.0/zero can be used allow coupling to happen any speed.


[edit] SetMaximumTractiveEffort

public native void SetMaximumTractiveEffort(float maxTE)
Parameters
  • maxTE = The maximum tractive effort of this vehicle in newtons (N).
Returned Value
  • None
Syntax
SetMaximumTractiveEffort(185000.0);
Notes
  • The maximum tractive effort of a vehicle refers to its maximum traction or pulling power measured in newtons.
  • This value is initially defined in the configuration of a vehicle asset but can be altered with this method.
  • Generally, only locomotives will have tractive effort.


[edit] SetPitchBasedOnSpeed

public native void SetPitchBasedOnSpeed(float multiplier)
Parameters
  • multiplier = The value to multiply the velocity by to get the train pitch angle.
Returned Value
  • None
Syntax
SetPitchBasedOnSpeed(2.5);
Notes
  • This feature is often used by "non-train" vehicles like helicopters.
  • Pitch is the forward/backward rotation of the vehicle mesh (ie, roation about an axis perpendicular to the track direction).


[edit] SetPitchBasedOnTrack

public native void SetPitchBasedOnTrack(bool pitch)
Parameters
  • pitch = True to enable the effect, false to disable.
Returned Value
  • None
Syntax
SetPitchBasedOnTrack(true);
Notes
  • Pitch is rotation about an axis at right angles to the track direction.


[edit] SetProductDisabled

public native void SetProductDisabled(void)
Parameters
  • None
Returned Value
  • None
Syntax
SetProductDisabled();
Notes
  • Disables the loading or unloading of any product, overriding any previous calls to SetProductRestriction().


[edit] SetProductRestriction

public native bool SetProductRestriction(Asset product)
Parameters
  • product = Asset to which this vehicle's load is to be restricted.
Returned Value
  • True if successful, false otherwise.
Syntax
SetProductRestriction(coal);
Notes
  • Restricts this vehicle to only allow the given product.
  • When a product restriction is in effect, only that product may be either loaded or unloaded.
  • This method overrides any previous call to SetProductDisabled().
  • If the product parameter is null, any product compatible with this vehicle can be loaded/unloaded.
  • If it is a product that is not compatible with this vehicle, no restriction is set and false will be returned.


[edit] SetQueueInitialCount

public void SetQueueInitialCount(ProductQueue queue, Asset product, int amount)
Parameters
  • queue = Queue to use, any existing products in this queue will be destroyed.
  • product = Asset of product to use.
  • amount = Amount of product to use.
Returned Value
  • None
Syntax
SetQueueInitialCount(passengerQueue,passengers,20);
Notes
  • Fills the given queue with the specified quantity of product.
  • This method sets the amount of products in the given queue.
  • It is a utility method that works on the given queue which need not be a queue from this vehicle.
  • The product filter provided with queue will be used to check if the queue can take products of type asset.
  • If it can't, the filter will be modified to suit as this method is forceful in that regard.


[edit] SetRollBasedOnTrack

public native void SetRollBasedOnTrack(float multiplier)
Parameters
  • multiplier = The value to multiply the curve by to get the train roll angle.
Returned Value
  • None
Syntax
SetRollBasedOnTrack(2.0);
Notes
  • This feature is often used by "non-train" vehicles like aeroplanes or boats.
  • Pitch is the left/right rotation of the vehicle mesh (ie, roation about an axis parallel to the track direction).
  • Use a positive value to lean 'into' the curve, a negative value to lean out.


[edit] SetRunningNumber

public native void SetRunningNumber(string number)
Parameters
  • number = The running (fleet identification) number of the vehicle.
Returned Value
  • None
Syntax
SetRunningNumber("21C1");
SetRunningNumber("4472");
Notes
  • This value is retrieved using GetRunningNumber() and should be restricted to alphanumeric characters and spaces.


[edit] SetSandingTractionMultiplier

public native void SetSandingTractionMultiplier(float factor)
Parameters
  • factor = A multiplier value of 1.0 or more defining the increase in this vehicle's tractive effort when sand is in use.
Returned Value
  • None
Syntax
SetSandingTractionMultiplier(1.5); // allow sanding to increase tractive effort by 50%
Notes


[edit] SetWheelslipTractionMultiplier

public native void SetWheelslipTractionMultiplier(float factor)
Parameters
  • factor = A multiplier value of 1.0 or less to apply to decrease this vehicle's traction when wheelslip occurs.
Returned Value
  • None
Syntax
SetWheelslipTractionMultiplier(0.25); // wheelslip reduces tractive effort to 25% of normal.
Notes
  • A multiplier value of 1.0 disables the wheelspin sound.


[edit] Uncouple

public native void Uncouple(int direction)
public native void Uncouple(Vehicle other)
Parameters
  • direction = A Coupler Flags constant indicating which coupler to detach.
  • other = A reference to the other vehicle form which the caller is to be uncoupled.
Returned Value
  • None
Syntax
Uncouple(COUPLE_FRONT);       // uncouple anything that's attached to the vehicle's front coupler
Uncouple(vehicle1);           // uncouple from the specified vehicle
Notes
  • Uncoupling will cause another Train object to be created for one half of the train.
  • Caling Uncouple(COUPLE_BOTH) is not valid, you must specify a single coupler.
  • See also Vehicle.GetCouplingDirection().


[edit] UnloadProduct

public bool UnloadProduct(LoadingReport report)
Parameters
  • report = Report on the current state of the loading operation.
Returned Value
  • True if the unloading operation was successful, false otherwise.
Syntax
UnloadProduct(report);
Notes
  • Unloads products into this vehicle as defined by the given report.
  • This method works by attempting to transfer products from this vehicle's queues to the industry queue specified in report.
  • The sequence of events for an unloading operation as performed by this method is:
    • Verify that an unloading operation is possible with this vehicle by calling CanUnloadProductToQueue().
    • BeginUnload() on this vehicle and Industry.BeginUnload() on the industry specified in the report are called to perform any pre-unloading events like animation or particle effects on the vehicle and industry respectively.
    • Both of these methods return the amount of time required for an unloading operation and the UnloadProduct() method sleeps for which ever of these times is the longer.
    • The actual product transfer to the industry from the vehicle is performed by calling ProductQueue.TransferProductFrom() on the industry queue(s).
    • GetUnloadTime() on this vehicle and Industry.GetUnloadTime() are called. Again, UnloadProduct() sleeps for which ever is the longer of the times returned.
    • EndUnload() and Industry.EndUnload() are called to perform any post-loading events. As before UnloadProduct() sleeps for the longer time.


[edit] UpdateViewDetails

void UpdateViewDetails(Message msg)
Parameters
  • msg = Message object which triggers this handler.
Returned Value
  • None
Notes
  • Update the view details window for this vehicle (from the train).
  • This method is setup by Init() as a handler method for a message of type "Vehicle","LoadComplete".
  • Such a message indicates that the load or queue of the vehicle have changed and the view details window of the train will need to be updated.


[edit] ViewDetails

void ViewDetails(Message msg)
Parameters
  • msg = Message object which triggers this handler.
Returned Value
  • None
Notes
  • View details window for this vehicle using the Train's output.
  • This method is setup by Init() as a handler method for a message of type "MapObject","ViewDetails".object.
  • Such a message indicates that the user has opened the right-click menu of the vehicle and selected the "View Details" menu item.
  • This method will call the ViewDetails() method of this vehicle's train so that a Browser window describing the entire train can be displayed to the user.


[edit] ViewSchedule

void ViewSchedule(Message msg)
Parameters
  • msg = Message object which triggers this handler.
Returned Value
  • None
Notes
  • View the schedule window for this vehicle from the train.
  • This method is setup by Init() as a handler method for a message of type "MapObject","View-Schedule".
  • Such a message indicates that the schedule of the vehicle or train is to be displayed for the user.
  • This method calls through to Train.UpdateScheduleWindow().



[edit] NotifyTrainChanged

public void NotifyTrainChanged(Train prevTrain, Train nextTrain)
Parameters
  • prevTrain = The train to which this Vehicle was previously attached.
  • nextTrain = The train to which this Vehicle is now attached.
Returned Value
  • None
Notes
  • In TS12 and greater only.
  • Override this function as required, but don't forget to call the inherited version in case it does something in the future.
  • Attempting to manipulate the makeup or positioning of any Train from within this function is illegal behavior. If you need to do that, trigger a delayed action using a message or a thread.


[edit] Code Examples


[edit] Related Methods

Train.GetVehicles()
World.GetVehicleList()

[edit] Categories

Personal tools