Go to Gallery           Register for MyTrainz | Login to MyTrainz

Scripts in Trainz A New Era

By Tony_Hilliam, October 14 2016

Recently on the forums, a community member questioned why a particular script would throw up a timeout error in TANE. The Driver Command in question, was designed to allow users to change a specific signal to a specific state while in Driver. The concept and script work fine in most circumstances, but the ECML route in TANE causes it to timeout. This blog post covers why this type of thing occurs and what can be done about it.

The command when called enumerates every possible state of every possible signal on the entire route and presents them in one massive list to the user. On ECML there are 93 different types of signal used and 5,400 actual signals on the route. The first limit it hits is that it runs out of screen space to display 5,400 signals, but beyond that it also runs past the performance limits. Performance here isn't necessarily related to frame rate. For example there are commonly used script libraries that when included in a session cause a 30 second pause when loading or unloading the Edit Session dialog.

We have provided the creator with an edited version to demonstrate some improvements. It isn't the perfect result but more on that later. This "fix" will avoid the timeout issue, by limiting the search to ~1000 signals which will stop processing at roughly the time it runs out of screen space. It also optimises a bunch of other stuff, which should speed it up a fair bit, but that's not enough in itself.

The suggested proper fix which would be scalable to any number of signals is to have a rule where you define a number of states that you may want to apply, and the driver command just lets you select one of those states. Rather than pick "s > signal 50328 > caution right" you might pick "permit access from mainline to XYZ station", where "permit access from mainline to XYZ station" is defined in the rule as "s > signal 50328 > caution right" plus whatever other signal states are required.

So, that's what the concept should be like to make it reasonably scalable. Once you have that concept, you realise that what you really have is a really the begins of an Interlocking Tower system, because an I.T. system is basically just defining a list of signals and what state they need to be in to activate a particular route. So longer term a better solution would be to redefine these large routes with ITs and use that system to provide the choices to the player and avoid unreasonably large lists with many thousands of permutations to choose from.

Now that routes have grown from a few km to a few hundred miles, as developers we also need to develop better systems to assist with this sort of scalability and that is something we have begun with the next iteration of Trainz (and will continue to to be expanded upon for years to come).

So here are a few more general Q&A 

Q. Why cant we just have unlimited processing time?
A. Because our users don't like long unexplained pauses, and it's not beneficial to anybody when better alternatives have been or can be developed. (i.e. look for alternative methods to accomplish similar goals that don' affect performance).

Q. But it worked in the last version!
A. No, it probably didn't. Apart from user complaints about performance which need to be addressed, the simple fact is that the UI isn't capable of displaying as many options as you're putting into the list, so the "timeout error" is  a red herring. 

Q. What did you change in the script? Did you just limit the number of signals it can process?
A. No. That's one important change, but the script has also undergone a fair bit of optimisation to reduce the amount of work required per signal.

Q. But limiting the number of signals doesn't fix the problem, it just hides it!
A. The limit is still higher than what the game can actually display, so it makes little difference to the end user. The command was broken before, it's still broken now. No more, no less. The difference is that it no longer hits the performance limit.

Q. I have some other script which does something more useful and isn't as obviously overkill, and it's also hitting timeout errors!
A. Well, that's a separate problem and we'll have to look into it separately and give you a separate answer. Keep in mind that it costs us ~$1000 per script that we thoroughly investigate in this manner, so it's unlikely that we will be able to provide this level of support for individual scripts.

Q. But why don't you just make it work?
A. The simulator works fine as long as your requirements make sense. If your requirements don't make sense, then you need to rethink what you're trying to achieve and then adopt a different strategy to meet those goals.

Q. Why should we have to do it?
A. It's your script, so if you want it to work well, that's on you. We can offer advice but we cannot afford to implement everybody's ideas for them. The ability for users to make their own modifications to Trainz is one of the great strengths of the product, but it also comes with a responsibility for making the effort to ensure that your content (scripts and otherwise) work well.

Q. Won't you just change the goalposts again in a few years?
A. Most likely yes we will. Trainz is a never-ending evolutionary product where content and code alike must be improved over time or fall by the wayside. 

Q. But your Interlocking Tower system isn't appropriate for my railroad, we use XYZ system instead!
A. Don't read too much into the name. There are a number of systems in use throughout the world, and they all have a lot in common but a few subtle differences in implementation. We had to come up with a name that encompassed the whole concept and was self-explanatory, so we went with Interlocking Towers. That doesn't mean that we don't support your system simply because the name is different from what you use in your area.
It's also true that different railroads use different control/interface techniques to control their interlockings, and we only provide a single example. The system is written specifically to be user-extensible however, and we encourage people to get involved with making alternative Tower implementations.

Finally, we are aware of various cases which we do not yet fully support. This was a deliberate design decision to ensure that we could provide a working system in a reasonable time frame, and our intention is to continue to grow the system out to support other use-cases in the future. If some feature that you require is not specifically supported at the current time, there are a few things you can do, including:

a) Ignoring the fact that it isn't supported, unless you plan to have a user-manned Tower in your session, it often doesn't matter HOW the tower actually works, because the user simply won't see that aspect of it.

b) Implementing the missing functionality via separate rules while allowing I.T. to perform the bulk of the work. Whether this makes sense depends on what you need, but the Interlocking Towers system is very open to scripted extension so you may quite possibly find that this is a reasonable solution.

c) Work with us to improve the Interlocking Towers implementation. Letting us know what you're working on, where you're blocked, and so on is a great way to ensure that your specific needs are met. We can't guarantee to get back to you straight away, because there's always a lot of work to do, but we will take any requests and complaints seriously and if we can't give you an answer on how to resolve your problem in the current system, we're more than happy to fold any necessary changes into a future revision.