*[[TrainzScript Language Reference|API Hierarchy]]
**World
 
*World is a static class used to access various aspects of the Trainz environment.
 

==Constants==
*These constants are used to define various values and can be used as mnenomics.
*If accessed from scripts the values must be prefixed ''World.'', for example:
World.SetWeather(World.WEATHER_TYPE_LIGHT_SNOW,World.WEATHER_CHANGEABILITY_PERIODIC);
 

===Camera View Modes===
----
*These values can be used either to choose the current camera viewing mode through World.SetCameraMode(), or to restrict certain camera modes from being accessed through methods such as World.SetCamera().

{{TableHeader|width=95%|margin=15px}}
|width=375|public define int CAMERA_INTERNAL = 1||Internal cabin camera view.
|-
|public define int CAMERA_EXTERNAL = 2||External train camera view
|-
|public define int CAMERA_TRACKING = 4||External tracking camera view.
|-
|public define int CAMERA_ROAMING = 128||Roaming camera view.
|}
 

===Camera Flags===
----
*These flags are used in addition to the Camera Mode Flags to allow or disallow specific camera actions.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int CAMERA_SWITCH_VIEWS = 8||User permitted to swap between the camera views.
|-
|public define int CAMERA_SWITCH_VEHICLES = 16||User permitted to swap vehicles within the current train.
|-
|public define int CAMERA_SWITCH_TRAINS = 32||User permitted to swap to other trains which are in the consist menu.
|-
|public define int CAMERA_LOCKED = 64||User is NOT permitted to adjust camera (i.e. zoom, pan etc.).
|-
|public define int CAMERA_NORMAL = * ||Normal camera mode where everything is permitted.
|-
|colspan=2|* NOTE: CAMERA_NORMAL = CAMERA_INTERNAL | CAMERA_EXTERNAL | CAMERA_TRACKING | CAMERA_SWITCH_VIEWS | CAMERA_SWITCH_VEHICLES | CAMERA_SWITCH_TRAINS
|}
 

===Weather Type Constants===
----
*Define the current state of the weather in Trainz.
*A variety of weather conditions are supported and can be changed by using one of these values with the World.SetWeather() method.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int WEATHER_TYPE_CLEAR = 0||Clear weather, no clouds, rain or snow.
|-
|public define int WEATHER_TYPE_CLOUDY = 1||Cloudy weather, no rain.
|-
|public define int WEATHER_TYPE_DRIZZLE = 2||Drizzle, light rain.
|-
|public define int WEATHER_TYPE_RAIN = 3||Rainy weather.
|-
|public define int WEATHER_TYPE_STORMY = 4||Stormy weather that includes lightning and thunder.
|-
|public define int WEATHER_TYPE_LIGHT_SNOW = 5||Snowing lightly.
|-
|public define int WEATHER_TYPE_MEDIUM_SNOW = 6||Medium level snow fall.
|-
|public define int WEATHER_TYPE_HEAVY_SNOW = 7||Heavy snow fall.
|}
 

===Weather Changeability Constants===
----
*Define the changeability settings for the weather.
*Weather changeability refers to variability of weather conditions rather than to a specific weather type.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int WEATHER_CHANGEABILITY_NONE = 0||Weather remains static.
|-
|public define int WEATHER_CHANGEABILITY_PERIODIC = 1||Periodic changes in weather.
|-
|public define int WEATHER_CHANGEABILITY_EXTREME = 2||Extreme and frequent changes in weather.
|}
 

===Time Values===
----
*Time constants defined in seconds.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define float TIME_SECOND = 1.0f||One second.
|-
|public define float TIME_MINUTE = TIME_SECOND * 60.0f||One minute, 60.0 seconds.
|-
|public define float TIME_HOUR = TIME_MINUTE * 60.0f||One hour, 60.0 minutes, 3600.0 seconds.
|-
|public define float TIME_DAY = TIME_HOUR * 24.0f||One day, 24 hours, 1440.0 minutes, 86400.0 seconds.
|}
 

===Time Rate Constants===
----
*Values that define the time rates relative to normal time.
*These constants can be used to set the time rate that Trainz runs out through the World.SetGameTimeRate() method.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int TIME_RATE_1X = 0||Real time (i.e. time in Trainz passes at the same rate as in the real world)
|-
|public define int TIME_RATE_2X = 1||Time passes at twice normal speed.
|-
|public define int TIME_RATE_4X = 2||
|-
|public define int TIME_RATE_8X = 3||
|-
|public define int TIME_RATE_16X = 4||
|-
|public define int TIME_RATE_32X = 5||
|-
|public define int TIME_RATE_60X = 6||
|-
| public define int TIME_RATE_120X = 7||
|-
| public define int TIME_RATE_240X = 8||
|-
|public define int TIME_RATE_360X = 9||
|-
|public define int TIME_RATE_480X = 10||
|-
|public define int TIME_RATE_720X = 11||
|-
|public define int TIME_RATE_960X = 12||
|-
|public define int TIME_RATE_1200X = 13||
|-
|public define int TIME_RATE_1440X = 14||
|}
 

===Trainz Modules===
----
*Trainz module mode constants.
*These values define the various module environments that Trainz can be in.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int NO_MODULE = 0||Trainz not running in a module.
|-
|public define int SURVEYOR_MODULE = 1||Trainz is currently running in Surveyor.
|-
|public define int DRIVER_MODULE = 2||Trainz is currently running in Driver.
|}
 

==Related Messages==
* [[TrainzScript Message Reference]] 
* [[Camera Messages]] 
* [[Interface Messages]] 
* [[ModuleInit Message]] 
 

==AddDriverCharacter==
{{MethodHeader|public native DriverCharacter AddDriverCharacter(Asset driverCharacterAsset)}}
;Parameters
*'''driverCharacterAsset''' = Asset containing character to be added.
;Returned Value
*Reference to the DriverCharacter if successful, null otherwise.
;Syntax
DriverCharacter Casey = World.AddDriverCharacter(CaseyJones);
;Notes
 

==AddDriverCommand==
{{MethodHeader|public native DriverCommand AddDriverCommand(Asset driverCommandAsset)}}
;Parameters
*'''driverCommandAsset''' = Asset containing command to be added.
;Returned Value
*Reference to the DriverCommand if successful, null otherwise.
;Syntax
DriverCommand GoFaster = World.AddDriverCommand(accelerate);
;Notes
 

==CreateBehavior==
{{MethodHeader|public native ScenarioBehavior CreateBehavior(KUID kuid, Soup initialProperties)}}
;Parameters
*'''kuid''' = KUID of scenario.
'''initialProperties''' = Soup object containing initial properties for scenario.
;Returned Value
*Reference to the ScenarioBehavior created if successful, null otherwise.
;Syntax
ScenarioBehavior scenario = World.CreateBehavior(scenarioAsset, scenarioSoup);
;Notes
*The returned ScenarioBehavior object may be ended by releasing all references to it (resetting all references to null).
 

==CreateTrain==
{{MethodHeader|public native Train CreateTrain(KUID[ ] consist, string trackmarkName, bool direction) public native Train CreateTrain(KUID[ ] consist, TrackMark trackmark, bool direction) public native Train CreateTrain(KUID[ ] consist, Buildable buildable, string trackName, float position, bool direction)}}
;Parameters
*'''consist''' = An array of vehicle KUIDs used to describe the required Train object.
*'''trackmarkName''' = Name of Trackmark at which the consist is to be formed.
*'''buildable''' = Buildable on which the consist is to be formed.
*'''trackName''' = Name of track within Buildable object.
*'''position''' = Distance at which the Train is to be placed relative to the start of the track.
*'''trackmark''' = Reference to Trackmark at which the consist is to be formed.
*'''direction''' = Orientation of Train relative to direction of track or trackmark.
;Returned Value
*Reference to the Train created if successful, null otherwise.
;Syntax
Train train = World.CreateTrain(consist, buildable, "Track 1", 10.0, true);
;Notes
*These methods create a train from a list of vehicles in a consist array.
*Depending on the variant of the method used, the train can be created at a Trackmark, specified by name or reference, or at a Buildable or Industry object.
*It is the responsibility of the script programmer to ensure that sufficient track exists at the given location to allow the train to be created.
 

==DeleteTrain==
{{MethodHeader|public native void DeleteTrain(Train train)}}
;Parameters
*'''train''' = train to be deleted from map.
;Returned Value
*None
;Syntax
World.DeleteTrain(flyingScotsman);
;Notes
*Once a train has been deleted, care should be taken to avoid using its reference.
 

==DeleteVehicle==
{{MethodHeader|public native void DeleteVehicle(Vehicle vehicle)}}
;Parameters
*'''vehicle''' = vehicle to be deleted from its train.
;Returned Value
*None
;Syntax
World.DeleteVehicle(vehicles[vehicles.size()-1]);
;Notes
*Use Train.GetVehicles() to obtain an array of vehicles for a given train.
*Use Vehicle.GetMyTrain() to obtain a train reference for a given vehicle.
 

==FindAsset==
{{MethodHeader|public native Asset FindAsset(KUID kuid)}}
;Parameters
*'''kuid''' = KUID of Asset to return.
;Returned Value
*Given a valid KUID parameter, this method return an Asset reference if successful, null otherwise.
;Syntax
Asset asset = World.FindAsset(kuid);
;Notes
*See also Asset.FindAsset()
 

==FindDriverCommand==
{{MethodHeader|public native DriverCommand FindDriverCommand(Asset driverCommandAsset)}}
;Parameters
*'''driverCommandAsset''' = Asset containing command to be added.
;Returned Value
*Reference to the DriverCommand if successful, null otherwise.
;Syntax
DriverCommand GoFaster = World.FindDriverCommand(accelerate);
;Notes
 

==GetAssetList==
{{MethodHeader|public native Asset[ ] GetAssetList(string kind)}}
;Parameters
*'''kind''' = String representing the Kind of asset to return.
;Returned Value
*A list of all assets of the given ''kind''
;Syntax
Asset[] Libraries = World.GetAssetList("Library");
;Notes
*All installed assets of the given ''kind'' are returned, irrespective of whether or not they are in use on the current map.
 

==GetBadWeatherFog==
{{MethodHeader|public native float GetBadWeatherFog(void)}}
;Parameters
*None
;Returned Value
*Bad weather fog distance as a float in the range 0.0..1.0.
;Syntax
float dist = World.GetBadWeatherFog();
;Notes
 

==GetBehaviors==
{{MethodHeader|public native ScenarioBehavior[ ] GetBehaviors(void)}}
;Parameters
*None
;Returned Value
*A list of top-level behaviors or rules on the currently loaded route.
;Syntax
ScenarioBehavior[] rules = World.GetBehaviors();
;Notes
 

==GetCameraPositionX==
{{MethodHeader|public native float GetCameraPositionX(void)}}
;Parameters
*None
;Returned Value
*X Coordinate of the current camera position.
;Syntax
float X = World.GetCameraPositionX();
*Notes
 

==GetCameraPositionY==
{{MethodHeader|public native float GetCameraPositionY(void)}}
;Parameters
*None
;Returned Value
*Y Coordinate of the current camera position.
;Syntax
float Y = World.GetCameraPositionY();
*Notes
 

==GetCameraPositionZ==
{{MethodHeader|public native float GetCameraPositionZ(void)}}
;Parameters
*None
;Returned Value
*Z Coordinate of the current camera position.
;Syntax
float Z = World.GetCameraPositionZ();
*Notes
 

==GetCurrentModule==
{{MethodHeader|public native int GetCurrentModule(void)}}
;Parameters
*None
;Returned Value
*An integer representing the current Trainz module.
;Syntax
int module = World,GetCurrentModule();
;Notes
* See [[#Trainz Modules|Trainz Modules]] for details of the constants associated with this method.
* See [[ModuleInit Message]] for further details.
 

==GetDriverCharacterList==
{{MethodHeader|public native DriverCharacter[ ] GetDriverCharacterList(void)}}
;Parameters
*None
;Returned Value
*An array of DriverCharacter objects installed in the current world.
;Syntax
DriverCharacter[] drivers = World.GetDriverCharacterList();
;Notes
 

==GetDriverCommandList==
{{MethodHeader|public native DriverCommand[ ] GetDriverCommandList(void)}}
;Parameters
*None
;Returned Value
*An array of DriverCommand objects installed in the current world.
;Syntax
DriverCommand[] commands = World.GetDriverCommandList();
;Notes
 

==GetGameTime==
{{MethodHeader|public native float GetGameTime(void)}}
;Parameters
*None
;Returned value
*Current game time.
;Syntax
float Now = World.GetGameTime();
;Notes
*The returned time is normalised to a value between 0.0 and 1.0
*0.0 = midday.
*0.5 = midnight
*Use the [[#Time_Values|Time Value]] constants to convert the normalised values to human readable times.
 

==GetGoodWeatherFog==
{{MethodHeader|public native float GetGoodWeatherFog(void)}}
;Parameters
*None
;Returned Value
*Good weather fog distance as a float in the range 0.0..1.0.
;Syntax
float dist = World.GetGoodWeatherFog();
;Notes
 

==GetGroundDrawDistance==
{{MethodHeader|public native float GetGroundDrawDistance(void)}}
;Parameters
*None
;Returned Value
*Ground draw distance in metres.
;Syntax
float dist = World.GetGroundDrawDistance();
;Notes
 

==GetIndustryList==
{{MethodHeader|public native GameObject[ ] GetIndustryList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the Industry objects for the current route.
;Syntax
GameObject[] Industries = World.GetIndustryList();
;Notes
 

==GetJunctionList==
{{MethodHeader|public native Junction[ ] GetJunctionList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the trackside junction objects for the current route.
;Syntax
Junction[] junctions = World.GetJunctionList();
;Notes
*Junction objects attached to fixed track junctions are not currently returned by this method.
 

==GetLibrary==
{{MethodHeader|public native Library GetLibrary(KUID kuid)}}
;Parameters
*'''kuid''' = KUID of script library asset to load.
;Returned Value
*A reference to the script library asset if successful, null otherwise.
;Syntax
Library codelib = World.GetLibrary(LibraryKUID);
;Notes
*The [[Class Library|Library]] asset is initialised when this method is first called in a session.
*Since only one instance can exist, subsequent calls return a reference to the existing Library object.
*See [[Class Library|Library]] for notes on how to use this method.
 

==GetSceneryDrawDistance==
{{MethodHeader|public native float GetSceneryDrawDistance(void)}}
;Parameters
*None
;Returned Value
*Scenery draw distance in metres.
;Syntax
float dist = World.GetSceneryDrawDistance();
;Notes
 

==GetSeconds==
{{MethodHeader|public native float GetSeconds(void)}}
;Parameters
*None
;Returned Value
*The current value of a floating point number incrementing once per second in real time.
;Syntax
float start = World.GetSeconds();
// do stuff
float finish = World.GetSeconds();
float period = finish - start;
;Notes
*Each call will return a float value containing the current value of an internal counter.
*Subtracting a later value from a value saved at an earlier call will enable the delay between the two calls to be established.
 

==GetSignalList==
{{MethodHeader|public native Signal[ ] GetSignalList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the signal objects for the current route.
;Syntax
Signal[] signals = World.GetSignalList();
;Notes
 

==GetStringTable==
{{MethodHeader|public native StringTable GetStringTable(void)}}
;Parameters
*None
;Returned Value
*The StringTable for the current session.
;Syntax
StringTable data = World.GetStringTable();
;Notes
 

==GetSurveyorSavedConsist==
{{MethodHeader|public native Soup GetSurveyorSavedConsistList(string name)}}
;Parameters
*'''name''' = Name of the consist to retireiev.
;Returned Value
*Returns a Soup definition of the named consist if it exists, null otherwise.
;Syntax
Soup consist = World.GetSurveyorSavedConsist("Brighton Belle");
;Notes
*Remember that the returned data is in a Soup format, which is not the same thing as a Train.
*TrainUtil.CreateTrainFormSoup() can be used to create a train from the returned Soup.
*This method only works in Surveyor.
 

==GetSurveyorSavedConsistList==
{{MethodHeader|public native string[ ] GetSurveyorSavedConsistList()}}
;Parameters
*None
;Returned Value
*An array of names of all the saved consist objects in Surveyor.
;Syntax
string[] consists = World.GetSurveyorSavedConsistList();
;Notes
*This method only works in Surveyor.
 

==GetTrackmarkList==
{{MethodHeader|public native TrackMark[ ] GetTrackmarkList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the trackmark objects for the current route.
;Syntax
Trackmark[] trackmarks = World.GetTrackmarkList();
;Notes
 

==GetTrainList==
{{MethodHeader|public native Train[ ] GetTrainList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the trains for the current route.
;Syntax
Train[] trains = World.GetTrainList();
;Notes
 

==GetTrainzBuild==
{{MethodHeader|public native int GetTrainzBuild(void)}}
;Parameters;
*None
;Returned Value
*Gets the current build number of Trainz.
;Syntax
int build = World.GetTrainzBuild();
;Notes
*The value returned corresponds to the build number you can see in the bottom-right side of the main Trainz menu screen.
 

==GetTrainzVersion==
{{MethodHeader|public native float GetTrainzVersion(void)}}
;Parameters
*None
;Returned Value
*The TRS version number.
;Syntax
float version = World.GetTrainzVersion();
;Notes
*The value returned corresponds to the version number you can see in the bottom-right side of the main Trainz menu screen.
 

==GetTriggerList==
{{MethodHeader|public native Trigger[ ] GetTriggerList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the trigger objects for the current route.
;Syntax
Trigger[] triggers = World.GetTriggerList();
;Notes
*This method does not return scenery triggers, ie those attached to SceneryWithTrack objects and their descendants.
 

==GetVehicleList==
{{MethodHeader|public native Vehicle[ ] GetVehicleList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the vehicles in the current route.
;Syntax
Vehicle[] vehicles = World.GetVehicleList();
;Notes
 

==GetWeatherChangeability==
{{MethodHeader|public native int GetWeatherChangeability(void)}}
;Parameter
*None
;Returned Value
*One of the [[#Weather_Changeability_Constants|Weather Changeability Constants]] denoting the variability of weather conditions.
;Syntax
int variability = World.GetWeatherChangeability();
;Notes
 

==GetWeatherType==
{{MethodHeader|public native int GetWeatherType(void)}}
;Parameter
*None
;Returned Value
*One of the [[#Weather_Type_Constants|Weather Type Constants]] denoting the current weather conditions.
;Syntax
int weather = World.GetWeatherType();
;Notes
 

==LoadMap==
{{MethodHeader|public native bool LoadMap(KUID kuid)}}
;Parameters
*'''kuid''' = KUID of map to load.
;Returned Value
*True if successful, false otherwise.
;Syntax
if (World.LoadMap(mapKUID) Interface.Print("Map loaded OK");
else Interface.Print("Map load failed");
;Notes
 

==Play2DSound==
{{MethodHeader|public float Play2DSound(Asset asset, string wave)}}
;Parameters
*'''asset''' = Asset where the sound file is located.
*'''wave''' = Name of the ''*.wav'' file to be played, a relative path can be included.
;Returned Value
*The length of the sound file in seconds.
;Syntax
// Play the sound and continues script execution.
World.Play2DSound(soundAsset,"sounds/allaboard.wav");
// Wait until sound has completed before continuing.
Sleep(World.Play2DSound(soundAsset,"sounds/allaboard.wav"));
;Notes
*Plays a ''.wav" sound file from the given asset's folder.
*The sound is non directional and can be mono or stereo.
*This method does not return after the sound has finished playing, it returns with the length of the sound as soon as it is called.
*This means your code will keep on executing while Trainz is playing the sound.
*If you want to wait for the sound to complete playing before moving on, wrap the Play2DSound() call up in a Sleep() call.
*Remember that Sleep() can't always be used.
 

==PlaySound==
{{MethodHeader|public native float PlaySound     (Asset asset, string wave, float vol, float near, float far, GameObject target, string pt)     (Asset asset, string wave, float vol, float near, float far, GameObject target, string pt, bool loop)}}
;Parameters
*'''asset''' = Asset where the sound file is located.
*'''wave''' = Name of the ''*.wav'' file to be played, a relative path can be included.
*'''vol''' = Volume level to play the sound at
*'''near''' = Distance from the target asset at which the sound will be played at maximum volume.
*'''far''' = Distance from the target asset at which the sound will become inaudible.
*'''target''' = GameObject to which the sound will be attached if a 3d sound is required, null for 2D.
*'''pt''' = Name of attachment point in the target object if a 3d sound is required, null for 2D.
*'''loop''' = (Optional) If true the sound will loop continuously.
;Returned Value
*<strike>The length of the sound file in seconds.</strike>
*NOTE: In TS12, the returned value is now undefined, and currently always returns '10'. This is to remove the performance cost of having to read the file from disk immediately to determine the sound length before the function can complete.
;Syntax
// Play the sound and continues script execution.
World.PlaySound(soundAsset,"sounds/allaboard.wav",1000.0,10.0,100.0,Station,"a.loudspeaker");
<strike>// Wait until sound has completed before continuing.</strike>
<strike> Sleep(World.PlaySound(soundAsset,"sounds/allaboard.wav",1000.0,10.0,100.0,Station,"a.loudspeaker"));</strike>
;Notes
*Plays a ''.wav'' sound file from the given asset's folder.
*If the sound is to be directional a mono sound file is required.
*This method does not return after the sound has finished playing, it returns with the length of the sound as soon as it is called.
*This means your code will keep on executing while Trainz is playing the sound.
*If you want to wait for the sound to complete playing before moving on, wrap the PlaySound() call up in a Sleep() call.
*Remember that Sleep() can't always be used.
*The sound volume will be at a maximum for a camera position at or less than the value of the ''near'' parameter and will reduce with distance until the hearing position reaches ''far'', when the sound will be inaudible.
 

==RemoveDriverCharacter==
{{MethodHeader|public native void RemoveDriverCharacter(DriverCharacter driver)}}
;Parameters
*'''driver''' = DriverCharacter to remove.
;Returned Value
*None
;Syntax
World.RemoveDriverCharacter(dave);
;Notes
 

==RemoveDriverCommand==
{{MethodHeader|public native void RemoveDriverCommand(DriverCommand command)}}
;Parameters
*'''command''' = DriverCommand to remove.
;Returned Value
*None
;Syntax
World.RemoveDriverCommand(driverCommand);
;Notes
 

==SetBadWeatherFog==
{{MethodHeader|public native void SetBadWeatherFog(float distance)}}
;Parameters
*'''distance''' = Bad weather fog distance to set.
;Returned Value
*None
;Syntax
World.SetBadWeatherFog(0.5);
;Notes
 

==SetCamera==
{{MethodHeader|public native bool SetCamera(MapObject focus) public native void SetCamera(Junction focus) public native void SetCamera(Vehicle focus, int cameraMode) public native void SetCamera(Train focus, int cameraMode)}}
;Parameters
*'''focus''' = Object on which the camera is to be focused.
*''cameraMode''' = One of the [[#Camera_View_Modes|Camera View Mode]] constants defining the view which should be assigned to the camera.
;Returned Value
*The first variant returns a boolean to indicate success or failure.
*Remaining variants do not return a value
'Syntax
World.SetCamera(train.GetVehicles[0],World.CAMERA_TRACKING); // sets the camera to track the first vehicle in the train.
 

==SetCameraAngle==
{{MethodHeader|public void SetCameraAngle(int yaw, int pitch, float radius)}}
;Parameters
*'''yaw''' = Camera rotation in degrees, 90 is a direct front view.
*'''pitch''' = Camera angle relative to the horizon, 0 is horizontal, 90 points vertically upwards.
*'''radius''' = Distance in metres to the object in focus.
;Returned Value
*None
;Syntax
World.SetCameraAngle(90,0,25); // Sets the camera to a direct frontal view at 25 metres from the currently focused object.
;Notes
*''Radius'' is measured from the object origin point (0,0,0).
 

==SetCameraFlags==
{{MethodHeader|public native void SetCameraFlags(int flags)}}
;Parameter
*'''flags''' integer value defining what the user is permitted to do with the game camera.
;Returned Value
*None
;Syntax
// User is permitted to select External or Tracking views only.
World.SetCameraFlags(World.CAMERA_EXTERNAL | World.CAMERA_TRACKING);
;Notes
*Use any combination of [[#Camera_Flags|Camera Flags]] and [[#Camera_View_Modes|Camera View Modes]] to set the parameter.
 

==SetCameraMode==
{{MethodHeader|public void SetCameraMode(int mode)}}
;Parameter
*'''mode''' = Camera mode to select.
;Returned Value
*None
;Syntax
World.SetCameraMode(World.CAMERA_TRACKING);
;Notes
*Use one of the [[#Camera_View_Modes|Camera View Modes]] to set the parameter.
 

==SetGameTime==
{{MethodHeader|public void SetGameTime(float time)}}
;Parameters
*'''time''' = new gane time to set.
;Returned Value
*None
;Syntax
World.SetGameTime(0.5); // sets time to midnight
;Notes
*Game time is normalised to a value between 0.0 and 1.0
*0.0 = midday.
*0.5 = midnight
*Use the [[#Time_Values|Time Value]] constants to convert human readable times to normalised values.
 

==SetGameTimeRate==
{{MethodHeader|public native void SetGameTimeRate(float rate)}}
;Parameters
*'''rate''' = New time rate to set.
;Returned Value
*None
;Syntax
World.SetGameTimeRate(World.TIME_RATE_8X); // sets game time to advance by 8 minutes per minute of real world time.
;Notes
*Use one of the [[#Time_Rate_Constants|Time Rate Constants]] to define the parameter.
 

==SetGoodWeatherFog==
{{MethodHeader|public native void SetGoodWeatherFog(float distance)}}
;Parameters
*'''distance''' = Good weather fog distance to set.
;Returned Value
*None
;Syntax
World.SetGoodWeatherFog(0.5);
;Notes
 

==SetGroundDrawDistance==
{{MethodHeader|public native void SetGroundDrawDistance(float distance)}}
;Parameters
*'''distance''' = Ground draw distance in metres.
;Returned Value
*None
;Syntax
World.SetGroundDrawDistance(1000.0);
;Notes
*Compatibility warning: Use of this function is not recommended, it may become non-functional in future Trainz versions.
 

==SetSceneryDrawDistance==
{{MethodHeader|public native void SetSceneryDrawDistance(float distance)}}
;Parameters
*'''distance''' = Scenery draw distance in metres.
;Returned Value
*None
;Syntax
World.SetSceneryDrawDistance(1000.0);
;Notes
*Compatibility warning: Use of this function is not recommended, it may become non-functional in future Trainz versions.
 

==SetTargetObserver==
{{MethodHeader|public void SetTargetObserver(GameObject observer)}}
;Parameters
*'''observer''' = ?
;Returned Value
*None
;Syntax
?
;Notes
*One of the great unsolved mysteries of Trainz
 

==SetWeather==
{{MethodHeader|public native void SetWeather(int type, int changeability)}}
;Parameters
*'''type''' = Weather conditions as defined by one of the [[#Weather_Type_Constants|Weather Type Constants]].
*'''change''' = Weather variation as defined by one of the [[#Weather_Changeability_Constants|Weather Changeability Constants]].
;Returned Value
*None
;Syntax
World.SetWeather(World.WEATHER_TYPE_HEAVY_SNOW,World.WEATHER_CHANGEABILITY_EXTREME); // April in Paris.
;Notes
 

==UserSetCamera==
{{MethodHeader|public native bool UserSetCamera(GameObject target)}}
;Parameters
*'''target''' = GameObject to set focus to.
;Returned Value
*True if successful, false otherwise.
;Syntax
World.UserSetCamera(Router,GetGameObject("Junction 5"));
;Notes
 

==UserSetCameraMode==
{{MethodHeader|public native void UserSetCameraMode(int mode)}}
;Parameters
*'''mode''' = One of the [[#Camera_View_Modes|Camera View Modes]]
;Returned Value
*None
;Syntax
World.UserSetCameraMode(World.CAMERA_ROAMING); // switches to roaming view if permitted.
;Notes
*This method respects the current [[#Camera_Flags|Camera Flag]] settings, disallowing any change which the flags do not permit.
 

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

Class World

2011-04-25T14:09:49Z

Tram (legacy 26267): /* PlaySound */

*[[TrainzScript Language Reference|API Hierarchy]]
**World
 
*World is a static class used to access various aspects of the Trainz environment.
 

==Constants==
*These constants are used to define various values and can be used as mnenomics.
*If accessed from scripts the values must be prefixed ''World.'', for example:
World.SetWeather(World.WEATHER_TYPE_LIGHT_SNOW,World.WEATHER_CHANGEABILITY_PERIODIC);
 

===Camera View Modes===
----
*These values can be used either to choose the current camera viewing mode through World.SetCameraMode(), or to restrict certain camera modes from being accessed through methods such as World.SetCamera().

{{TableHeader|width=95%|margin=15px}}
|width=375|public define int CAMERA_INTERNAL = 1||Internal cabin camera view.
|-
|public define int CAMERA_EXTERNAL = 2||External train camera view
|-
|public define int CAMERA_TRACKING = 4||External tracking camera view.
|-
|public define int CAMERA_ROAMING = 128||Roaming camera view.
|}
 

===Camera Flags===
----
*These flags are used in addition to the Camera Mode Flags to allow or disallow specific camera actions.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int CAMERA_SWITCH_VIEWS = 8||User permitted to swap between the camera views.
|-
|public define int CAMERA_SWITCH_VEHICLES = 16||User permitted to swap vehicles within the current train.
|-
|public define int CAMERA_SWITCH_TRAINS = 32||User permitted to swap to other trains which are in the consist menu.
|-
|public define int CAMERA_LOCKED = 64||User is NOT permitted to adjust camera (i.e. zoom, pan etc.).
|-
|public define int CAMERA_NORMAL = * ||Normal camera mode where everything is permitted.
|-
|colspan=2|* NOTE: CAMERA_NORMAL = CAMERA_INTERNAL | CAMERA_EXTERNAL | CAMERA_TRACKING | CAMERA_SWITCH_VIEWS | CAMERA_SWITCH_VEHICLES | CAMERA_SWITCH_TRAINS
|}
 

===Weather Type Constants===
----
*Define the current state of the weather in Trainz.
*A variety of weather conditions are supported and can be changed by using one of these values with the World.SetWeather() method.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int WEATHER_TYPE_CLEAR = 0||Clear weather, no clouds, rain or snow.
|-
|public define int WEATHER_TYPE_CLOUDY = 1||Cloudy weather, no rain.
|-
|public define int WEATHER_TYPE_DRIZZLE = 2||Drizzle, light rain.
|-
|public define int WEATHER_TYPE_RAIN = 3||Rainy weather.
|-
|public define int WEATHER_TYPE_STORMY = 4||Stormy weather that includes lightning and thunder.
|-
|public define int WEATHER_TYPE_LIGHT_SNOW = 5||Snowing lightly.
|-
|public define int WEATHER_TYPE_MEDIUM_SNOW = 6||Medium level snow fall.
|-
|public define int WEATHER_TYPE_HEAVY_SNOW = 7||Heavy snow fall.
|}
 

===Weather Changeability Constants===
----
*Define the changeability settings for the weather.
*Weather changeability refers to variability of weather conditions rather than to a specific weather type.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int WEATHER_CHANGEABILITY_NONE = 0||Weather remains static.
|-
|public define int WEATHER_CHANGEABILITY_PERIODIC = 1||Periodic changes in weather.
|-
|public define int WEATHER_CHANGEABILITY_EXTREME = 2||Extreme and frequent changes in weather.
|}
 

===Time Values===
----
*Time constants defined in seconds.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define float TIME_SECOND = 1.0f||One second.
|-
|public define float TIME_MINUTE = TIME_SECOND * 60.0f||One minute, 60.0 seconds.
|-
|public define float TIME_HOUR = TIME_MINUTE * 60.0f||One hour, 60.0 minutes, 3600.0 seconds.
|-
|public define float TIME_DAY = TIME_HOUR * 24.0f||One day, 24 hours, 1440.0 minutes, 86400.0 seconds.
|}
 

===Time Rate Constants===
----
*Values that define the time rates relative to normal time.
*These constants can be used to set the time rate that Trainz runs out through the World.SetGameTimeRate() method.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int TIME_RATE_1X = 0||Real time (i.e. time in Trainz passes at the same rate as in the real world)
|-
|public define int TIME_RATE_2X = 1||Time passes at twice normal speed.
|-
|public define int TIME_RATE_4X = 2||
|-
|public define int TIME_RATE_8X = 3||
|-
|public define int TIME_RATE_16X = 4||
|-
|public define int TIME_RATE_32X = 5||
|-
|public define int TIME_RATE_60X = 6||
|-
| public define int TIME_RATE_120X = 7||
|-
| public define int TIME_RATE_240X = 8||
|-
|public define int TIME_RATE_360X = 9||
|-
|public define int TIME_RATE_480X = 10||
|-
|public define int TIME_RATE_720X = 11||
|-
|public define int TIME_RATE_960X = 12||
|-
|public define int TIME_RATE_1200X = 13||
|-
|public define int TIME_RATE_1440X = 14||
|}
 

===Trainz Modules===
----
*Trainz module mode constants.
*These values define the various module environments that Trainz can be in.
{{TableHeader|width=95%|margin=15px}}
|width=375|public define int NO_MODULE = 0||Trainz not running in a module.
|-
|public define int SURVEYOR_MODULE = 1||Trainz is currently running in Surveyor.
|-
|public define int DRIVER_MODULE = 2||Trainz is currently running in Driver.
|}
 

==Related Messages==
* [[TrainzScript Message Reference]] 
* [[Camera Messages]] 
* [[Interface Messages]] 
* [[ModuleInit Message]] 
 

==AddDriverCharacter==
{{MethodHeader|public native DriverCharacter AddDriverCharacter(Asset driverCharacterAsset)}}
;Parameters
*'''driverCharacterAsset''' = Asset containing character to be added.
;Returned Value
*Reference to the DriverCharacter if successful, null otherwise.
;Syntax
DriverCharacter Casey = World.AddDriverCharacter(CaseyJones);
;Notes
 

==AddDriverCommand==
{{MethodHeader|public native DriverCommand AddDriverCommand(Asset driverCommandAsset)}}
;Parameters
*'''driverCommandAsset''' = Asset containing command to be added.
;Returned Value
*Reference to the DriverCommand if successful, null otherwise.
;Syntax
DriverCommand GoFaster = World.AddDriverCommand(accelerate);
;Notes
 

==CreateBehavior==
{{MethodHeader|public native ScenarioBehavior CreateBehavior(KUID kuid, Soup initialProperties)}}
;Parameters
*'''kuid''' = KUID of scenario.
'''initialProperties''' = Soup object containing initial properties for scenario.
;Returned Value
*Reference to the ScenarioBehavior created if successful, null otherwise.
;Syntax
ScenarioBehavior scenario = World.CreateBehavior(scenarioAsset, scenarioSoup);
;Notes
*The returned ScenarioBehavior object may be ended by releasing all references to it (resetting all references to null).
 

==CreateTrain==
{{MethodHeader|public native Train CreateTrain(KUID[ ] consist, string trackmarkName, bool direction) public native Train CreateTrain(KUID[ ] consist, TrackMark trackmark, bool direction) public native Train CreateTrain(KUID[ ] consist, Buildable buildable, string trackName, float position, bool direction)}}
;Parameters
*'''consist''' = An array of vehicle KUIDs used to describe the required Train object.
*'''trackmarkName''' = Name of Trackmark at which the consist is to be formed.
*'''buildable''' = Buildable on which the consist is to be formed.
*'''trackName''' = Name of track within Buildable object.
*'''position''' = Distance at which the Train is to be placed relative to the start of the track.
*'''trackmark''' = Reference to Trackmark at which the consist is to be formed.
*'''direction''' = Orientation of Train relative to direction of track or trackmark.
;Returned Value
*Reference to the Train created if successful, null otherwise.
;Syntax
Train train = World.CreateTrain(consist, buildable, "Track 1", 10.0, true);
;Notes
*These methods create a train from a list of vehicles in a consist array.
*Depending on the variant of the method used, the train can be created at a Trackmark, specified by name or reference, or at a Buildable or Industry object.
*It is the responsibility of the script programmer to ensure that sufficient track exists at the given location to allow the train to be created.
 

==DeleteTrain==
{{MethodHeader|public native void DeleteTrain(Train train)}}
;Parameters
*'''train''' = train to be deleted from map.
;Returned Value
*None
;Syntax
World.DeleteTrain(flyingScotsman);
;Notes
*Once a train has been deleted, care should be taken to avoid using its reference.
 

==DeleteVehicle==
{{MethodHeader|public native void DeleteVehicle(Vehicle vehicle)}}
;Parameters
*'''vehicle''' = vehicle to be deleted from its train.
;Returned Value
*None
;Syntax
World.DeleteVehicle(vehicles[vehicles.size()-1]);
;Notes
*Use Train.GetVehicles() to obtain an array of vehicles for a given train.
*Use Vehicle.GetMyTrain() to obtain a train reference for a given vehicle.
 

==FindAsset==
{{MethodHeader|public native Asset FindAsset(KUID kuid)}}
;Parameters
*'''kuid''' = KUID of Asset to return.
;Returned Value
*Given a valid KUID parameter, this method return an Asset reference if successful, null otherwise.
;Syntax
Asset asset = World.FindAsset(kuid);
;Notes
*See also Asset.FindAsset()
 

==FindDriverCommand==
{{MethodHeader|public native DriverCommand FindDriverCommand(Asset driverCommandAsset)}}
;Parameters
*'''driverCommandAsset''' = Asset containing command to be added.
;Returned Value
*Reference to the DriverCommand if successful, null otherwise.
;Syntax
DriverCommand GoFaster = World.FindDriverCommand(accelerate);
;Notes
 

==GetAssetList==
{{MethodHeader|public native Asset[ ] GetAssetList(string kind)}}
;Parameters
*'''kind''' = String representing the Kind of asset to return.
;Returned Value
*A list of all assets of the given ''kind''
;Syntax
Asset[] Libraries = World.GetAssetList("Library");
;Notes
*All installed assets of the given ''kind'' are returned, irrespective of whether or not they are in use on the current map.
 

==GetBadWeatherFog==
{{MethodHeader|public native float GetBadWeatherFog(void)}}
;Parameters
*None
;Returned Value
*Bad weather fog distance as a float in the range 0.0..1.0.
;Syntax
float dist = World.GetBadWeatherFog();
;Notes
 

==GetBehaviors==
{{MethodHeader|public native ScenarioBehavior[ ] GetBehaviors(void)}}
;Parameters
*None
;Returned Value
*A list of top-level behaviors or rules on the currently loaded route.
;Syntax
ScenarioBehavior[] rules = World.GetBehaviors();
;Notes
 

==GetCameraPositionX==
{{MethodHeader|public native float GetCameraPositionX(void)}}
;Parameters
*None
;Returned Value
*X Coordinate of the current camera position.
;Syntax
float X = World.GetCameraPositionX();
*Notes
 

==GetCameraPositionY==
{{MethodHeader|public native float GetCameraPositionY(void)}}
;Parameters
*None
;Returned Value
*Y Coordinate of the current camera position.
;Syntax
float Y = World.GetCameraPositionY();
*Notes
 

==GetCameraPositionZ==
{{MethodHeader|public native float GetCameraPositionZ(void)}}
;Parameters
*None
;Returned Value
*Z Coordinate of the current camera position.
;Syntax
float Z = World.GetCameraPositionZ();
*Notes
 

==GetCurrentModule==
{{MethodHeader|public native int GetCurrentModule(void)}}
;Parameters
*None
;Returned Value
*An integer representing the current Trainz module.
;Syntax
int module = World,GetCurrentModule();
;Notes
* See [[#Trainz Modules|Trainz Modules]] for details of the constants associated with this method.
* See [[ModuleInit Message]] for further details.
 

==GetDriverCharacterList==
{{MethodHeader|public native DriverCharacter[ ] GetDriverCharacterList(void)}}
;Parameters
*None
;Returned Value
*An array of DriverCharacter objects installed in the current world.
;Syntax
DriverCharacter[] drivers = World.GetDriverCharacterList();
;Notes
 

==GetDriverCommandList==
{{MethodHeader|public native DriverCommand[ ] GetDriverCommandList(void)}}
;Parameters
*None
;Returned Value
*An array of DriverCommand objects installed in the current world.
;Syntax
DriverCommand[] commands = World.GetDriverCommandList();
;Notes
 

==GetGameTime==
{{MethodHeader|public native float GetGameTime(void)}}
;Parameters
*None
;Returned value
*Current game time.
;Syntax
float Now = World.GetGameTime();
;Notes
*The returned time is normalised to a value between 0.0 and 1.0
*0.0 = midday.
*0.5 = midnight
*Use the [[#Time_Values|Time Value]] constants to convert the normalised values to human readable times.
 

==GetGoodWeatherFog==
{{MethodHeader|public native float GetGoodWeatherFog(void)}}
;Parameters
*None
;Returned Value
*Good weather fog distance as a float in the range 0.0..1.0.
;Syntax
float dist = World.GetGoodWeatherFog();
;Notes
 

==GetGroundDrawDistance==
{{MethodHeader|public native float GetGroundDrawDistance(void)}}
;Parameters
*None
;Returned Value
*Ground draw distance in metres.
;Syntax
float dist = World.GetGroundDrawDistance();
;Notes
 

==GetIndustryList==
{{MethodHeader|public native GameObject[ ] GetIndustryList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the Industry objects for the current route.
;Syntax
GameObject[] Industries = World.GetIndustryList();
;Notes
 

==GetJunctionList==
{{MethodHeader|public native Junction[ ] GetJunctionList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the trackside junction objects for the current route.
;Syntax
Junction[] junctions = World.GetJunctionList();
;Notes
*Junction objects attached to fixed track junctions are not currently returned by this method.
 

==GetLibrary==
{{MethodHeader|public native Library GetLibrary(KUID kuid)}}
;Parameters
*'''kuid''' = KUID of script library asset to load.
;Returned Value
*A reference to the script library asset if successful, null otherwise.
;Syntax
Library codelib = World.GetLibrary(LibraryKUID);
;Notes
*The [[Class Library|Library]] asset is initialised when this method is first called in a session.
*Since only one instance can exist, subsequent calls return a reference to the existing Library object.
*See [[Class Library|Library]] for notes on how to use this method.
 

==GetSceneryDrawDistance==
{{MethodHeader|public native float GetSceneryDrawDistance(void)}}
;Parameters
*None
;Returned Value
*Scenery draw distance in metres.
;Syntax
float dist = World.GetSceneryDrawDistance();
;Notes
 

==GetSeconds==
{{MethodHeader|public native float GetSeconds(void)}}
;Parameters
*None
;Returned Value
*The current value of a floating point number incrementing once per second in real time.
;Syntax
float start = World.GetSeconds();
// do stuff
float finish = World.GetSeconds();
float period = finish - start;
;Notes
*Each call will return a float value containing the current value of an internal counter.
*Subtracting a later value from a value saved at an earlier call will enable the delay between the two calls to be established.
 

==GetSignalList==
{{MethodHeader|public native Signal[ ] GetSignalList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the signal objects for the current route.
;Syntax
Signal[] signals = World.GetSignalList();
;Notes
 

==GetStringTable==
{{MethodHeader|public native StringTable GetStringTable(void)}}
;Parameters
*None
;Returned Value
*The StringTable for the current session.
;Syntax
StringTable data = World.GetStringTable();
;Notes
 

==GetSurveyorSavedConsist==
{{MethodHeader|public native Soup GetSurveyorSavedConsistList(string name)}}
;Parameters
*'''name''' = Name of the consist to retireiev.
;Returned Value
*Returns a Soup definition of the named consist if it exists, null otherwise.
;Syntax
Soup consist = World.GetSurveyorSavedConsist("Brighton Belle");
;Notes
*Remember that the returned data is in a Soup format, which is not the same thing as a Train.
*TrainUtil.CreateTrainFormSoup() can be used to create a train from the returned Soup.
*This method only works in Surveyor.
 

==GetSurveyorSavedConsistList==
{{MethodHeader|public native string[ ] GetSurveyorSavedConsistList()}}
;Parameters
*None
;Returned Value
*An array of names of all the saved consist objects in Surveyor.
;Syntax
string[] consists = World.GetSurveyorSavedConsistList();
;Notes
*This method only works in Surveyor.
 

==GetTrackmarkList==
{{MethodHeader|public native TrackMark[ ] GetTrackmarkList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the trackmark objects for the current route.
;Syntax
Trackmark[] trackmarks = World.GetTrackmarkList();
;Notes
 

==GetTrainList==
{{MethodHeader|public native Train[ ] GetTrainList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the trains for the current route.
;Syntax
Train[] trains = World.GetTrainList();
;Notes
 

==GetTrainzBuild==
{{MethodHeader|public native int GetTrainzBuild(void)}}
;Parameters;
*None
;Returned Value
*Gets the current build number of Trainz.
;Syntax
int build = World.GetTrainzBuild();
;Notes
*The value returned corresponds to the build number you can see in the bottom-right side of the main Trainz menu screen.
 

==GetTrainzVersion==
{{MethodHeader|public native float GetTrainzVersion(void)}}
;Parameters
*None
;Returned Value
*The TRS version number.
;Syntax
float version = World.GetTrainzVersion();
;Notes
*The value returned corresponds to the version number you can see in the bottom-right side of the main Trainz menu screen.
 

==GetTriggerList==
{{MethodHeader|public native Trigger[ ] GetTriggerList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the trigger objects for the current route.
;Syntax
Trigger[] triggers = World.GetTriggerList();
;Notes
*This method does not return scenery triggers, ie those attached to SceneryWithTrack objects and their descendants.
 

==GetVehicleList==
{{MethodHeader|public native Vehicle[ ] GetVehicleList(void)}}
;Parameters
*None
;Returned Value
*An array of references to all of the vehicles in the current route.
;Syntax
Vehicle[] vehicles = World.GetVehicleList();
;Notes
 

==GetWeatherChangeability==
{{MethodHeader|public native int GetWeatherChangeability(void)}}
;Parameter
*None
;Returned Value
*One of the [[#Weather_Changeability_Constants|Weather Changeability Constants]] denoting the variability of weather conditions.
;Syntax
int variability = World.GetWeatherChangeability();
;Notes
 

==GetWeatherType==
{{MethodHeader|public native int GetWeatherType(void)}}
;Parameter
*None
;Returned Value
*One of the [[#Weather_Type_Constants|Weather Type Constants]] denoting the current weather conditions.
;Syntax
int weather = World.GetWeatherType();
;Notes
 

==LoadMap==
{{MethodHeader|public native bool LoadMap(KUID kuid)}}
;Parameters
*'''kuid''' = KUID of map to load.
;Returned Value
*True if successful, false otherwise.
;Syntax
if (World.LoadMap(mapKUID) Interface.Print("Map loaded OK");
else Interface.Print("Map load failed");
;Notes
 

==Play2DSound==
{{MethodHeader|public float Play2DSound(Asset asset, string wave)}}
;Parameters
*'''asset''' = Asset where the sound file is located.
*'''wave''' = Name of the ''*.wav'' file to be played, a relative path can be included.
;Returned Value
*The length of the sound file in seconds.
;Syntax
// Play the sound and continues script execution.
World.Play2DSound(soundAsset,"sounds/allaboard.wav");
// Wait until sound has completed before continuing.
Sleep(World.Play2DSound(soundAsset,"sounds/allaboard.wav"));
;Notes
*Plays a ''.wav" sound file from the given asset's folder.
*The sound is non directional and can be mono or stereo.
*This method does not return after the sound has finished playing, it returns with the length of the sound as soon as it is called.
*This means your code will keep on executing while Trainz is playing the sound.
*If you want to wait for the sound to complete playing before moving on, wrap the Play2DSound() call up in a Sleep() call.
*Remember that Sleep() can't always be used.
 

==PlaySound==
{{MethodHeader|public native float PlaySound     (Asset asset, string wave, float vol, float near, float far, GameObject target, string pt)     (Asset asset, string wave, float vol, float near, float far, GameObject target, string pt, bool loop)}}
;Parameters
*'''asset''' = Asset where the sound file is located.
*'''wave''' = Name of the ''*.wav'' file to be played, a relative path can be included.
*'''vol''' = Volume level to play the sound at
*'''near''' = Distance from the target asset at which the sound will be played at maximum volume.
*'''far''' = Distance from the target asset at which the sound will become inaudible.
*'''target''' = GameObject to which the sound will be attached if a 3d sound is required, null for 2D.
*'''pt''' = Name of attachment point in the target object if a 3d sound is required, null for 2D.
*'''loop''' = (Optional) If true the sound will loop continuously.
;Returned Value
*<strike>The length of the sound file in seconds.</strike>
*NOTE: In TS12, the returned value is now undefined, and currently always returns '10'. This is to remove the performance cost of having to read the file from disk immediately to determine the sound length before the function can complete.
;Syntax
// Play the sound and continues script execution.
World.PlaySound(soundAsset,"sounds/allaboard.wav",1000.0,10.0,100.0,Station,"a.loudspeaker");
<strike> // Wait until sound has completed before continuing.</strike>
<strike> Sleep(World.PlaySound(soundAsset,"sounds/allaboard.wav",1000.0,10.0,100.0,Station,"a.loudspeaker"));</strike>
;Notes
*Plays a ''.wav'' sound file from the given asset's folder.
*If the sound is to be directional a mono sound file is required.
*This method does not return after the sound has finished playing, it returns with the length of the sound as soon as it is called.
*This means your code will keep on executing while Trainz is playing the sound.
*If you want to wait for the sound to complete playing before moving on, wrap the PlaySound() call up in a Sleep() call.
*Remember that Sleep() can't always be used.
*The sound volume will be at a maximum for a camera position at or less than the value of the ''near'' parameter and will reduce with distance until the hearing position reaches ''far'', when the sound will be inaudible.
 

==RemoveDriverCharacter==
{{MethodHeader|public native void RemoveDriverCharacter(DriverCharacter driver)}}
;Parameters
*'''driver''' = DriverCharacter to remove.
;Returned Value
*None
;Syntax
World.RemoveDriverCharacter(dave);
;Notes
 

==RemoveDriverCommand==
{{MethodHeader|public native void RemoveDriverCommand(DriverCommand command)}}
;Parameters
*'''command''' = DriverCommand to remove.
;Returned Value
*None
;Syntax
World.RemoveDriverCommand(driverCommand);
;Notes
 

==SetBadWeatherFog==
{{MethodHeader|public native void SetBadWeatherFog(float distance)}}
;Parameters
*'''distance''' = Bad weather fog distance to set.
;Returned Value
*None
;Syntax
World.SetBadWeatherFog(0.5);
;Notes
 

==SetCamera==
{{MethodHeader|public native bool SetCamera(MapObject focus) public native void SetCamera(Junction focus) public native void SetCamera(Vehicle focus, int cameraMode) public native void SetCamera(Train focus, int cameraMode)}}
;Parameters
*'''focus''' = Object on which the camera is to be focused.
*''cameraMode''' = One of the [[#Camera_View_Modes|Camera View Mode]] constants defining the view which should be assigned to the camera.
;Returned Value
*The first variant returns a boolean to indicate success or failure.
*Remaining variants do not return a value
'Syntax
World.SetCamera(train.GetVehicles[0],World.CAMERA_TRACKING); // sets the camera to track the first vehicle in the train.
 

==SetCameraAngle==
{{MethodHeader|public void SetCameraAngle(int yaw, int pitch, float radius)}}
;Parameters
*'''yaw''' = Camera rotation in degrees, 90 is a direct front view.
*'''pitch''' = Camera angle relative to the horizon, 0 is horizontal, 90 points vertically upwards.
*'''radius''' = Distance in metres to the object in focus.
;Returned Value
*None
;Syntax
World.SetCameraAngle(90,0,25); // Sets the camera to a direct frontal view at 25 metres from the currently focused object.
;Notes
*''Radius'' is measured from the object origin point (0,0,0).
 

==SetCameraFlags==
{{MethodHeader|public native void SetCameraFlags(int flags)}}
;Parameter
*'''flags''' integer value defining what the user is permitted to do with the game camera.
;Returned Value
*None
;Syntax
// User is permitted to select External or Tracking views only.
World.SetCameraFlags(World.CAMERA_EXTERNAL | World.CAMERA_TRACKING);
;Notes
*Use any combination of [[#Camera_Flags|Camera Flags]] and [[#Camera_View_Modes|Camera View Modes]] to set the parameter.
 

==SetCameraMode==
{{MethodHeader|public void SetCameraMode(int mode)}}
;Parameter
*'''mode''' = Camera mode to select.
;Returned Value
*None
;Syntax
World.SetCameraMode(World.CAMERA_TRACKING);
;Notes
*Use one of the [[#Camera_View_Modes|Camera View Modes]] to set the parameter.
 

==SetGameTime==
{{MethodHeader|public void SetGameTime(float time)}}
;Parameters
*'''time''' = new gane time to set.
;Returned Value
*None
;Syntax
World.SetGameTime(0.5); // sets time to midnight
;Notes
*Game time is normalised to a value between 0.0 and 1.0
*0.0 = midday.
*0.5 = midnight
*Use the [[#Time_Values|Time Value]] constants to convert human readable times to normalised values.
 

==SetGameTimeRate==
{{MethodHeader|public native void SetGameTimeRate(float rate)}}
;Parameters
*'''rate''' = New time rate to set.
;Returned Value
*None
;Syntax
World.SetGameTimeRate(World.TIME_RATE_8X); // sets game time to advance by 8 minutes per minute of real world time.
;Notes
*Use one of the [[#Time_Rate_Constants|Time Rate Constants]] to define the parameter.
 

==SetGoodWeatherFog==
{{MethodHeader|public native void SetGoodWeatherFog(float distance)}}
;Parameters
*'''distance''' = Good weather fog distance to set.
;Returned Value
*None
;Syntax
World.SetGoodWeatherFog(0.5);
;Notes
 

==SetGroundDrawDistance==
{{MethodHeader|public native void SetGroundDrawDistance(float distance)}}
;Parameters
*'''distance''' = Ground draw distance in metres.
;Returned Value
*None
;Syntax
World.SetGroundDrawDistance(1000.0);
;Notes
*Compatibility warning: Use of this function is not recommended, it may become non-functional in future Trainz versions.
 

==SetSceneryDrawDistance==
{{MethodHeader|public native void SetSceneryDrawDistance(float distance)}}
;Parameters
*'''distance''' = Scenery draw distance in metres.
;Returned Value
*None
;Syntax
World.SetSceneryDrawDistance(1000.0);
;Notes
*Compatibility warning: Use of this function is not recommended, it may become non-functional in future Trainz versions.
 

==SetTargetObserver==
{{MethodHeader|public void SetTargetObserver(GameObject observer)}}
;Parameters
*'''observer''' = ?
;Returned Value
*None
;Syntax
?
;Notes
*One of the great unsolved mysteries of Trainz
 

==SetWeather==
{{MethodHeader|public native void SetWeather(int type, int changeability)}}
;Parameters
*'''type''' = Weather conditions as defined by one of the [[#Weather_Type_Constants|Weather Type Constants]].
*'''change''' = Weather variation as defined by one of the [[#Weather_Changeability_Constants|Weather Changeability Constants]].
;Returned Value
*None
;Syntax
World.SetWeather(World.WEATHER_TYPE_HEAVY_SNOW,World.WEATHER_CHANGEABILITY_EXTREME); // April in Paris.
;Notes
 

==UserSetCamera==
{{MethodHeader|public native bool UserSetCamera(GameObject target)}}
;Parameters
*'''target''' = GameObject to set focus to.
;Returned Value
*True if successful, false otherwise.
;Syntax
World.UserSetCamera(Router,GetGameObject("Junction 5"));
;Notes
 

==UserSetCameraMode==
{{MethodHeader|public native void UserSetCameraMode(int mode)}}
;Parameters
*'''mode''' = One of the [[#Camera_View_Modes|Camera View Modes]]
;Returned Value
*None
;Syntax
World.UserSetCameraMode(World.CAMERA_ROAMING); // switches to roaming view if permitted.
;Notes
*This method respects the current [[#Camera_Flags|Camera Flag]] settings, disallowing any change which the flags do not permit.
 

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

Class MeshObject

2011-04-03T00:45:23Z

Tram (legacy 26267): /* SetFXAttachment */

*[[TrainzScript Language Reference|API Hierarchy]]
**[[Class GSObject|GSObject]]
***[[Class GameObject|GameObject]]
****[[Class PropertyObject|PropertyObject]]
****[[Class TrainzGameObject|TrainzGameObject]]
*****MeshObject
 

This is a base class for [[class Asset|Asset]] based game objects that have meshes, effects, animations and particles. Interface methods to deal with these are provided so things like showing or hiding a mesh, attaching a mesh to an attachment point or controlling an animation can be done from a script.

For animation Trainz interpolates between key frames. This means an intermediate animation frame is calculated dynamically to be-in-synch with the game's framerate.

Trainzscript is an interpreted scripting language intended to be used to monitor and react to events in the Trainz world, not to perform sophisticated real-time animation tasks. Using a script to start an animation in response to an event in a thread is reasonable. However trying to control animation tightly down to short intervals is likely to provide unsatisfactory results and to adversely affect overall performance of the game.

==MeshObject Messages==
Messages related to MeshObject assets:
*[[Animation-Event Message]]
*[[pfx Message]]
 

==GetFXAttachment==
{{MethodHeader|public native MeshObject GetFXAttachment(string effect)}}
;Parameters
*'''effect''' = name of the mesh effect to query.
;Returned Value
*Returns a reference to the MeshObject currently attached to the named effect.
;Syntax
MeshObject attachment = GetFXAttachment("coupler");
;Notes
*The method returns null if the effect is unoccupied.
 

==GetMeshAnimationFrame==
{{MethodHeader|public native float GetMeshAnimationFrame(string mesh)'''}}
;Parameters
*'''mesh''' = the name of the mesh or submesh container which includes the animation file to be queried.
;Returned Value
*Current fame of the animation file within the specified mesh container.
;Syntax
float height = GetMeshAnimationFrame("zPosition")
;Notes
*Note that the returned value is likely to be an interpreted floating point value.
 

==GetMeshAnimationFrameCount==
{{MethodHeader|public native float GetMeshAnimationFrameCount(string mesh)}}
;Parameters
*'''mesh''' = the name of the mesh or submesh container which includes the animation file to be queried.
;Returned Value
*The number of frames in the specified animation.
;Syntax
float positions = GetMeshAnimationFrameCount("lever");
;Notes
*Note that the returned value is a float rather than an integer.
 

==GetTextureSelfIlluminationState==
{{MethodHeader|public native bool GetTextureSelfIlluminationState(string texture)'''}}
;Parameters
*'''texture''' = root name of ''*.texture.text'' file to query.
;Returned Value
*Returns true if the specified texture has self illumination set.
;Syntax
bool isEmissive = GetTextureSelfIlluminationState("texture");
;Notes
*Compatibility warning: Use of this function is not recommended, it may become non-functional in future Trainz versions.
 

==HasMesh==
{{MethodHeader|public native bool HasMesh(string mesh)}}
;Parameters
*'''mesh''' = the name of the mesh or submesh to be queried.
;Returned Value
*None
;Syntax
if (HasMesh("ventilation")) StartMeshAnimationLoop("fans");
;Notes
*
 

==SetFXAnimationState==
{{MethodHeader|public native void SetFXAnimationState(string effect, bool state)}}
;Parameters
*'''effect''' = name of attached-animation effect containing the animation to play.
*'''state''' = true to start the animation loop, false to stop.
;Returned Value
*None
;Syntax
if (gateClosed) SetFXAnimationState("gate",false);
;Notes
 

==SetFXAttachment==
{{MethodHeader|public native MeshObject SetFXAttachment(string effect, Asset asset)'''}}
;Parameters
*'''effect''' = effect containing the attachment to be manipulated.
*'''asset''' = mesh asset to attach to the effect. If asset is null any existing asset will be removed and nothing will be added.
;Returned Value
*Returns a reference to the MeshObject which has been attached to the named effect. If the mesh asset isn't "kind mesh", returns null.
;Syntax
MeshObject lamp = SetFXAttachment("lamp0",redlamp);
;Notes
*Returns null if the effect is unoccupied when the method returns.
 

==SetFXCoronaTexture==
{{MethodHeader|public native void SetFXCoronaTexture(string effect, Asset texture)}}
;Parameters
*'''effect''' = effect containg the corona to be manipulated.
*'''asset''' = corona texture asset to attach to the effect. If asset is null the corona will be turned off.
;Returned Value
*None
;Syntax
SetFXCoronaTexture("stopLight",redCorona);
;Notes
*Other corona parameters such as frequency and size are defined in ''config.txt'' and cannot be altered by script code.
 

==SetFXNameText==
{{MethodHeader|public native void SetFXNameText(string effect, string text)}}
;Parameters
*'''effect''' = effect containg the name effect to be changed.
*'''text''' = new string value.
;Returned Value
*None
;Syntax
SetFXNameText("home","Shangri-La");
;Notes
*Method will not accept an empty string in the ''text'' parameter.
 

==SetFXTextureReplacement==
{{MethodHeader|public native void SetFXTextureReplacement(string effect, Asset textureGroup, int index)}}
;Parameters
*'''effect''' = texture-replacement effect to be changed.
*'''textureGroup''' = reference to texture group asset which is the source of the texture to be applied.
*'''index''' = index into ''textures'' table of texture-group indicating which texture to apply.
;Returned Value
*None
;Syntax
SetFXTextureReplacement("load","loadTextures",5); // applies texture 5 from texture-group
SetFXTextureReplacement("load",null,0); // clears the effect, reinstating the texture defined in the asset.
;Notes
*Use null in the textureGroup parameter to turn texture replacement off.
 

==SetMesh==
{{MethodHeader|public native void SetMesh(string mesh, float fadeDuration)}}
;Parameters
*'''mesh''' = the name of the mesh or submesh to be displayed.
*'''fadeDuration''' = period in seconds during which mesh visibility will be faded in or out.
;Returned Value
*None
;Syntax
SetMesh("default",0.5);
;Notes
*Shows the specified mesh and hides all other meshes.
*If fadeDuration is 0.0 the mesh transition will be instantaneous.
 

==SetMeshAnimationFrame==
{{MethodHeader|public native void SetMeshAnimationFrame(string mesh, float frame) 
public native void SetMeshAnimationFrame(string mesh, float frame, float period)}}
;Parameters
*'''mesh''' = the name of the mesh or submesh container which includes the animation file to be manipulated.
*'''frame''' = the frame position to which the animation is to be moved, this may be an interpolated value.
*'''period''' = the period over which the animation will be moved from its current position to the newly specified point.
;Returned Value
*None
;Syntax
SetMeshAnimationFrame("default",5.0); // move the animation to frame 5 instantaneously
SetMeshAnimationFrame("default",5.0,2.0); // move the animation to frame 5 over 2 seconds
;Notes
*Moves the specified animation to the specified frame.
*For the first variant the transition is instant.
*For the second variant the transition will complete during the specified period.
 

==SetMeshAnimationSpeed==
{{MethodHeader|public native void SetMeshAnimationSpeed(string mesh, float speed)}}
;Parameters
*'''mesh''' = the name of the mesh or submesh container which includes the animation file to be manipulated.
*'''speed''' = multiplication factor to apply to the original animation speed.
;Returned Value
*None
;Syntax
SetMeshAnimationSpeed("fans",2.0); // run fans at double speed
SetMeshAnimationSpeed("fans",-1.0); // run fans backwards at original speed
;Notes
*Modifies the speed at which the animation is played.
*The original speed is multiplied by the new speed factor.
*Use negative values to make the animation run in reverse.
 

==SetMeshAnimationState==
{{MethodHeader|public native void SetMeshAnimationState(string mesh, bool state)}}
;Parameters
*'''mesh''' = the name of the mesh or submesh container which includes the animation file to be played.
*'''state''' = the direction in which the file is to be played, true for forwards, false for backwards.
;Returned Value
*None
;Syntax
SetMeshAnimationState("door",true); // opens the door
SetMeshAnimationState("door",false); // closes the door
;Notes
*This method plays animations and is best suited to those which have defined start and end points such as the opening and closing of a gate or door.
*If ''state'' is true the animation plays forwards from its current position to the last frame. If the current position is already at the last frame the call has no effect.
*If ''state'' is false the animation plays backwards from its current position to the first frame. If the current position is already at the first frame the call has no effect.
 

==SetMeshVisible==
{{MethodHeader|public native void SetMeshVisible(string mesh, bool visible, float fadeDuration)}}
;Parameters
*'''mesh''' = the name of the mesh or submesh to be displayed.
*'''visible''' = true to show the mesh, false to hide it.
*'''fadeDuration''' = period in seconds during which mesh visibility will be faded in or out.
;Returned Value
*None
;Syntax
SetMeshVisible("driver", false, 1.0);
;Notes
*If fadeDuration is 0.0 the mesh transition will be instantaneous.
 

==SetTextureSelfIllumination==
{{MethodHeader|public native void SetTextureSelfIllumination(string texture, float r, float g, float b)}}
;Parameters
*'''texture''' = root name of ''*.texture.text'' file to query.
*'''r,g,b''' = red green and blue components of self illumination value to apply, range 0 .. 1 where 1 is equal to 100%.
;Returned Value
*None
;Syntax
SetTextureSelfIllumination("interior",0.5,0.5,0.5);
;Notes
*Applies an emissive component to the texture using the red, green and blue components specified.
*Compatibility warning: Use of this function is not recommended, it may become non-functional in future Trainz versions.
 

==StartMeshAnimationLoop==
{{MethodHeader|public native void StartMeshAnimationLoop(string mesh)}}
;Parameters
*'''mesh''' = the name of the mesh or submesh container which includes the animation file to be played.
;Returned Value
*None
;Syntax
StartMeshAnimationLoop("windmill");
;Notes
*This method plays animations and is best suited to those which are designed to run in a continuous loop.
*The speed of the animation can be altered using [[#SetMeshAnimationSpeed|SetMeshAnimationSpeed()]]
*Using [[#SetMeshAnimationSpeed|SetMeshAnimationSpeed()]] with a negative value will cause the animation to play in reverse.
*[[#StopMeshAnimation|StopMeshAnimation()]] will halt the animation.
 

==StopMeshAnimation==
{{MethodHeader|public native void StopMeshAnimation(string mesh)}}
;Parameters
*'''mesh''' = the name of the mesh or submesh container which includes the animation file to be stopped.
;Returned Value
*None
;Syntax
StopMeshAnimation("default");
;Notes
*Turns animation off for the specified mesh.
 

==SwapTextureOnMesh==
{{MethodHeader|public native void SwapTextureOnMesh(string mesh, string oldTexture, string newTexture)}}
;Parameters
*'''mesh''' = the name of the mesh or submesh container which includes the texture to be changed.
*'''oldTexture''' = the original ''*.texture.txt'' file to use as the source of the transition.
*'''newTexture''' = the new ''*.texture.txt'' file to apply.
;Returned Value
*None
;Syntax
SwapTextureOnMesh("left-passenger-door","gwr","lms");
;Notes
*Swap one texture against another texture on specified mesh.
*Similar to texture-replacement effects, but without the need for an extra texture asset.
*'''possible bug''' Texture names in the .im file must be lower case for this function to work properly.
 

==Code Examples==

==Related Methods==

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