Script Feature Requests

This page is where the scripting community gets to post all their API feature requests. Request any additions that you think will enhance the game. Things to keep in mind:

• We are unlikely to add a feature which breaks any existing content.
• Script is for control purposes, and is not intended to enable significant modifications to the underlying game engine. We are very unlikely to introduce a feature where the obvious uses are going to result in significant performance penalties.
• We are far more likely to add features which are directly blocking something that the community is working on. If you have something cool, and need just a few minor additions then please detail what you're working on (ideally, on another wiki page linked from both here and your Content Creation Groups page) and why you need the additions.
• MiniBrowser requests should go on the separate MiniBrowser Feature Requests page.

Requests

Requests are placed in this section by the community, for discussion and possible inclusion.

• Str.Tokens("Foo", "") should return ["F", "o", "o"] when called without separator in 2nd argument analogous to other languages (String.split()). --Sachsenbahner 19:53, 10 December 2018 (AEST)

• Add a method that will let you identify the industry at which a vehicle is located. If an industry track section can also carry the industry identifier, it would be most helpful.

• Add a handle to allow a custom bell animation to be played when the bell is played on a locomotive (Vehicle.StartBell() and Vehicle.StopBell(), perhaps?). Justification: Script can currently listen for the bell message, but since the message is a toggle, it is easy to get out of synch with the true state of the bell. For example, when coupling a locomotive whose bell is ringing to a locomotive whose bell is not ringing, the end result depends on which locomotive is currently in focus. - Curtis

• Scale the visible bulk load animation on a traincar such that it takes Vehicle.GetLoadTime() to complete. For example, if Vehicle.GetLoadTime() returns 5 seconds, the bulk animation would take 5 seconds to transition from the full state to the empty state. This would be useful for industries that take more than one second to load / unload a car, as the visible load animation could be synced more closely with the industry animation. -Curtis

• Extension to the function World.GetAssetList(string kind, bool OnlyIfUsedInCurrentMap) -Andi06

• Ability to play an avi and wait for it to finsh (no user interaction allowed) ~Jenolan

• The ability to modify scenery trigger radii on the fly in script. This is really aimed at crossings so that train detection can be varied in line with track speed limits. -Andi06

• A method of refreshing the Property Browser to take account of any change in the target object's name during a property editing session. (Objects which have 'autoname 1' in config will often be renamed by the user. In some circumstances I am using the object name to set other properties. Typically an object might be created as 'Double Slip 1' and might refer to its constituent nodes as 'Double Slip 1,Track 1'. This is to enable other objects to refer to it in a user friendly way. On a name change the Property Browser continues to use the old name until the browser has been closed and reopened. This is counter intuitive) -Andi

• Ability for a script to be able to read/change loco/rolling stock parameters (ie to simulate one loco losing air etc etc etc) ~Jenolan

• SetFXCoronaTexture() A means of resetting to config.txt defaults.

• Be able to play mp3 as well as wav. ~Jenolan

I've been able to do this where the asset doing the playing is a script library, I had Acker Bilk coming over a station tannoy at one point. Not sure why it doesn't seem to work elsewhere. -Andi

• Interface.MessageBox(Caption,Text), calling up a small browser with a close button would be helpful, especially for novices. Interface.Print() is a monumental PITA because it prints out upside down, doesn't hold enough lines, and only works in Driver. For sure its possible to write your own version of this but browsers aren't all that easy to get your head around and its a very basic facility that should be built in. -Andi

• A standard config.txt tag 'junction-type normal/singleslip/doubleslip' etc together with a spec for construction and behaviour might be helpful. I already have a complete schema for this. -Andi

Uncertain what you're expecting to achieve here? -chris

see Animated Fixed Junctions Thread

• Is it possible to make a mesh available which matches the existing graphic direction indicators, it appears to be some sort of directional corona or variant. If not could a new marker mesh be developed that could be used with both types? The existing one has nasty alpha effects in any case. -Andi

• Ability to dynamically change the length of a piece of rolling stock as part of the load / unload process; to support logging disconnects (see http://www.trainzone.co.nz/logging.htm for examples)- Curtis

This is an interesting concept, but sounds difficult to implement. I can't think of any way of adjusting the length unless it was the end item of a consist, since adjustment at any other time would require displacing the remainder of the consist. Could you expand on your ideas please. -chris

The entire car, including lmfront & lmback, would be part of the loading / unloading animation. When loading, it would probably be necessary to displace the consist by moving one of the ends - perhaps the end with the locomotive? Potential issue: if when loading, the increase in consist length causes the end of the consist to run off the end of the track or collide with another train. When unloading, you could break the consist at either or both lmfront / lmback - whichever move as part of the unloading animation. - Curtis

May be simpler to just break the consist at both lmfront and lmback; centering the car in-between the two halves. -Curtis

• Allow SetFXNameText(effect,text) to accept an empty string in the second parameter - Reason: It's really irritating having to write workarounds for this. ~Andi

• SetMeshScale(X,Y,Z) and corresponding config tags. Positive or negative values would implement mesh mirroring at the same time. As an example of potential a placement option for trees might allow random scale factors (within reasonable limits) and random rotation. Each tree placed would then vary in size, shape and rotation getting much more variation from the same mesh asset. ~Andi

• Update to product loading / unloading functionality to allow incremental loads and unloads.

Potential usages:

- Animation that plays once per item being loaded; such as a forklift carrying a crate to a boxcar, or a crane lifting a log to a flatcar.

- Allow dynamic load times of bulk loads (small cars load faster than large cars), with the animated load rising / lowering synchronously.

Potential implementation:

Extend vehicle.LoadProduct(report,units) where units = integer number of queue to be loaded each increment. 0 would be everything, defaulting to current LoadProduct() behavior, and add additional calls BeginIncrementalLoad(), EndIncrementalLoad(), BeginIncrementalUnload(), and EndIncrementalUnload().

During a load operation that loads 3 increments (units=1, target queue on the car = 3), the flow would look like:

BeginLoad() // open car doors; station doors

BeginIncrementalLoad() //  start loading animation, start sounds; pfx; add any delays
TransferProductFrom() // maximumToTransfer = units
EndIncrementalLoad() // animate forklift returning to station / end sounds / pfx / other cleanup

BeginIncrementalLoad()
TransferProductFrom()
EndIncrementalLoad()

BeginIncrementalLoad()
TransferProductFrom()
EndIncrementalLoad()

EndLoad() // close car & station doors

• Ability to add a vehicle to an existing consist like Vehicle.Reposition( Train, MyCouple, OtherCouple ) this would save needing a work track mark to add vehicles which would be very helpful ~Jenolan

• Extension to AddHandler to allow this syntax: AddHandler(target,"","","MessageHandler"), passing all messages to the specified handler, for justification see discussion page. -Andi

• Ability to store any information along with the layout and not the session (i.e. PropertyObject.SetLayoutProperties and PropertyObject.GetLayoutProperties, taking/returning Soup objects respectively). Rationale: the non-existence is a major drawback with configurable signals - Klausm

• Access to asset location, height, rotation in script. This came up twice - once when I wanted to keep traffic lights upright when the containing asset is rolled, and once when I wanted to add simple real time ground shadows to assets. -Andi06

• Ability to arbitrarily add an attachment point to an item. To allow things like FRED/BOG sundry animations and so on ~Jenolan

• Not really script. A generic clickable mesh object, its an easy hack using a fixedtrack junction but it would nice to have an official version - click on the engine shed to open the doors, click on the signal box to open a track browser etc etc. Mappable click regions too if its not too much to ask :-) -Andi

• Extension/Alternative to World.GetJunctionList to return fixed track junction objects or nodes, I can script this easily for objects using my library but this would not be the case for all junctions. -Andi

• World.Play2DSound(Asset,filename) allows sound files to be saved in a 'sound library' asset and avoids duplication. Can we have a similar facility for images to be used in html assets. A lot of the dependencies that I use are images and icons. I'm consciously trying to avoid this now - its the source of much pain - but to do this for the Junction Kit for instance I would have to have copies of all necessary images in all of the placeable assets (there are more than 50) If I could simply keep one copy in the script library it would save much bandwidth, diskspace and support. -Andi06

• genesteal : cab features.

- methods for light controls in cabin : Control.SetFlash (float frequency).Make the control visible/invisible on the intervall frequency. may be Meshobjects.gs for more general purpose. The same for texture swapping in texture replacement. - New conrol cab "button" with vertical translation limit : method set and get value as usual, method for "while depressed" behavior: Setdepressed ( method to run).

- Speedlimiter method : Set a speedlimit replacing the max speed possible on cab mode.(engine)

- Set engine methods : Locomotive.SwapEngine(kuid); replace engine by another for a locomotive. feature existing on actual loco to set a traction service if the loco have to drive freight or passengers consists. This method can replace speedlimit above and may be more accurate : speedlimit and power will be set together as prototypical setting before a journey. - Locomotive.EngineStop(): stops the enginesound and play a stop.wav, located in enginesound folder. - Locomotive.EngineStart() : starts enginesound like this : play a start.wav located in enginesound folder, then idle 0.wav.

• Allow function Vehicle.SetTractionMultiplier(float) to set multiplier to 0. ~Mike

UPD: sorry, misunderstood functionality of this function. But could there be a method to disable traction on locos?

• Ability to change (or only to reduce) the presure in auxilary reservoir of a vehicle. This provides a way to create different types of tripte valves for long-length trains (~70 vehicles), where using Train.SetVelocity() is unrealistic

• Make in addition to Vehice.GetTrackGradient() also float Vehice.GetTrackCurveRadius() which return 0 for straight sections of track (instead of infinity). ~tram
• Make a function for smooth control of "soundscript"'s sound volume. For example like void MapObject.SetSoundScriptVolume(string soundTrigger, float NewVolume, float Duration). ~tram

• Ability to set the camera view within an interior by a script to one of the defined cameras in the cameralist container. It would also be handy if the camera orientation be configurable via a method call. --pcas1986 (talk) 18:14, 20 February 2014 (EST)

• Ability to place a bogey in an interior via the interiors config file. This would allow for me to make a realistic gangways for my Amlfeets i.e. i have set created gangways for my exteiors using bogeys which allow them to rotate and remain aligned realistically. The issue arrizes when in the interior. I cannot aninate the interior gangway to aligne itself according to the curvature of track. If i could get the named bogey visible from the interior (similar to how one could make the exterior visble from interior) that would help.~ Ashton

• Locomotive.SetEngineSetting(string setting, float value) - Ability to mute/activate engine sound for a locomotive adding setting "enginesound" to the list of settings, value 0 to mute, 1 to activate engine sound ~manweb

- setting = The name of the setting to save (enginesound).
- value = The value of the named setting. (0 - 1)

• Math.sin,cos,tan,arcsin,arccos,arctan - Trigonometric functions to get the sine, cosine, and tangent of a float, and inverses of these

Complete

• Simple destructor routine, or some other method of receiving notification of the deletion of scripted objects during a Surveyor session. (In the absence of World.GetJunctionBaseList() my new junction objects are maintaining a list of fixedtrack junctions via library calls in the Init() method of each object. Apart from using the list myself, it is intended to be returned on demand to any script making the appropriate LibraryCall. Since I have no way of telling that an object has been deleted, I need to rescan the entire list before returning it to ensure that each object still exists, this seems a touch inefficient when it could be easily kept up to date without a complete parse) -Andi

Now a function of the TrackSearch system. -chris

• The ability for TrackSearch to return the trigger or track reference found for SceneryWithTrack descendants, including turntables and the ability to initiate a search from a specified trigger or track in SceneryWithTrack descendants. A million reasons for this including trains being able to detect which track of an industry they can see in a proposed 'Call-At All Stations' rule. -Andi06

Now a function of the TrackSearch system. -chris

• Compatibility of the TrackSearch with the animated fixed junctions. When I first got TRS2006 in my hands, I tried out my TrackView rule, but quickly discovered that it was impossible to find out the track topology (forgot the exact details, though) - Klausm

TrackSearch system is now considerably more robust. -chris

• Extensions to TrackSearch()/GSTrackSearch() covered elsewhere to be sufficient to allow the topography of multi node junctions to be fully discovered. -Andi

TrackSearch system is now considerably more robust. -chris

• If we are going to use radians now (SetMeshOrientation()) could we please have PI?

Math.PI -chris

• Ability to configure permit structure to allow multi node junctions to coexist with the AI, whilst denying conflicting paths, as discussed above. -Andi

Added named mutex support for attached junctions. See KIND SceneryWithTrack. ~chris

• Fix World.GetAssetList("texture-group"), this has been broken since TRS2004. -Andi06

Now returns all assets with category-class 'JO'. This seems to contain all 'texture-group' type assets - though there maybe some unexpected extras. -James

• Ability to detect the use of 'Pause' easily (a message would do) to stop cheating in shunting puzzles ~Jenolan

New messages "World", "Paused" and "World", "Unpaused" now exist and should be broadcast at the appropriate times. -James

• World.GetCurrentTrain() Not essential obviously but it would save a lot of work. -Andi06

Now exists. -James

• Ability to optionally detect mouseclick/ Keys [J] & [^J] without switching the junction. This can be hacked by making node 0 an invisible junction, but this will result in other objects querying the junction structure not getting the answer they expect (or not one they can understand). This is needed to allow objects with more than one junction node to cycle through their options in response to the user. -Andi

I believe this is now possible via script overrides on the map object in question. ~chris

• A method of subclassing or outright using a script from another asset (ie. a script which is written once and reused heavily, allowing any fixes to be released as a single asset update.) - chris

TS2009 now has the ability to cross-include scripts from another asset. ~chris

• Dreamland, a new message: Junction,AboutToToggle -Andi

How do you expect to act on this? -chris

see Animated Fixed Junctions Thread

'I believe this concept has been fulfilled via the UserRequestToggle overrides. ~chris

• On a similar note is there any chance you might amend the Exception dialogue to specify the object, (or even the Asset) which is causing the exception :-) -Andi

I think we did this one a while back. ~chris

• SetMeshPosition("meshname", x,y,z) absolute positioning of a Mesh or Object. -Caby

This exists ~Andi

Not necessarily - we support relative positioning, not absolute. This may or may not achieve what he wants. ~chris

This has been added. ~chris

• GetMeshPosition("meshname", "x")["Y"]["Z"] receive the absolute position of a Mesh or Object. -Caby

Since you have used SetMeshPosition() to move the mesh, this is unneccessary

Absolute position can be set in Surveyor. Relative position can be set in the config.txt file. I wouldn't say that this is completely unnecessary. ~chris

Thanks a lot for MapObject.GetMapObjectPosition() and MapObject.GetMapObjectOrientation() ~tram

This has been added. ~chris

• Ability to load a menu asset directly from the command line ~Jenolan

This exists with "-scriptedmenu=<KUID>" ~chris

Rejected

If there's a request that we're clearly not going to entertain at the current time, we'll move it to here. This includes both flat rejections and also requests which sound good but won't be done for the next version of Trainz.

Rejected Script Feature Requests