Revision as of 10:32, 31 October 2010

The following features are newly added to TrainzScript in TS2009.

Cross-asset script includes

As of trainz-build 2.9, any scripted asset may directly include script files from the top-level directory of any other scripted asset. In your script code, you use the 'include' keyword as normal to import the script file. In order for Trainz to find the include file, you must make the following config.txt file changes:

• Add a script-include-table and list the KUID of the asset(s) from which you will be including files.
• Add the same KUIDs to your asset's kuid-table.

You must ensure that there are no script filename conflicts between any assets involved.

Global script context

Trainz now runs multiple concurrent script virtual machines (VMs). Objects in each VM are largely disassociated, but because the native interface is shared, there is some level of cross-talk. This has not been clearly delineated, and is likely to change in future versions once we've had time to investigate it further. For now, you should treat the VMs as completely distinct except where Auran documentation explicitly declares otherwise.

The two obvious script contexts are the global menu system, and the active module.

• The global VM is responsible for global settings libraries, menubar interface addons, etc. and does not have access to the World. It persists until Trainz exits.
• The active module VM is responsible for maintaining the session, route, and gameplay aspects and does not persist beyond the lifetime of the module.

Libraries can be forced to always load in the global script context using a config.txt tag

always-load-in-global-context 1

If a library is shared between assets, it is important to be aware in which context the library is loaded. A script running in a gameplay context can make calls to a Library in the global context. The reverse is not possible. If always-load-in-global-context is not used, assets running in gameplay context will access an instance of the library also running in gameplay context. Assets running in global context however access an instance of the library in global context. In other words, there are two parallel instances of the ibrary. To prevent this situation the always-load-in-global-context tag forces the library to only load once (in global context). The library resisting in global context is then available to other assets in gameplay and global context.

CAUTION: there are some pitfalls when passing data between objects in different contexts. No references to objects of another context can be stored as members. This means you must make a copy of every reference type (e.g. strings and arrays) you want to store in another context. In other words, you need to extract any relevant details during the cross-context call and keep copies. Strings are copied using Str.CloneString() and arrays can be copied using the copy() operator. There are also possible limitations to cross context message passing, sniffing, etc.

Scripts running in global context cannot use some of the functions which are intended for the game context (e.g. driver module). This concerns mainly functions of class World and class Interface. Calling these functions from global context causes a ER_NativeCallError script exception.

Global settings libraries

Global settings libraries are standard script libraries with an additional tag entry in their config.txt files.

custom-category-list "GSET"

The global settings libraries are loaded into the global VM in the following scenarios:

• The user clicks on the library in the Trainz Settings dialog.
• Another script in the global VM calls GetLibrary().
• The library is a built-in settings library recognized by Trainz, and Trainz wishes to read the current settings.

note: Currently there is nothing to stop a global settings library from being loaded into a module VM. It is likely that we'll change this prior to release, to ensure that they're loaded into the global VM regardless of from where they're instantiated.

Libraries loaded into the global module have their properties saved to the global settings file.

The following TS2009 built-in content are Global Settings Libraries:

• "Video Settings" <kuid:30501:1021>
• "Surveyor Settings" <kuid:30501:1022>
• "Global Interface Addons" <kuid:30501:1026>

Interface Addons

Interface Addons are standard script libraries with an additional tag entry in their config.txt files.

custom-category-list "GADD"

Interface Addons are loaded into the global VM by the "Global Interface Addons" library. The user must choose to enable the interface addon before it is loaded.

note: As they are normal script libraries, the interface addons may be loaded through other means. The "Global Interface Addons" library also provides a mechanism for users to unload addons. At the current time, this requires the user to reload Trainz; it is likely that we will add a script mechanism to truly unload the library, or at least tell it to clean up. We are also likely to provide a mechanism for interface addons to determine whether they were loaded by the Global Interface Addon (and should display their UI) or by some other mechanism (in which case they should remain hidden.)

The following TS2009 built-in content are Interface Addons:

• "iTrainz Chat Interface" <kuid:30501:1003>

iTrainz URL Helper library

This script library provides a unified mechanism for handling custom trainz://xx/yy style URLs, regardless of where they occur in the game. The library is used by native code, and by scripts via the new TrainzScript.OpenURL() function. Script code should never call into this library directly where a call to TrainzScript.OpenURL() would suffice, as the native code may perform some URL parsing before handing over to the script library.

The "iTrainz URL Helper library" is <kuid:30501:1025>.

note: Currently there is nothing to stop this library from being loaded into a module VM. It is likely that we'll change this prior to release, to ensure that it's loaded into the global VM regardless of from where it's instantiated.

The current version of the library supports the following URL styles:

• trainz://buddy/NAME - routed to the "iTrainz Chat Interface"
• trainz://channel/NAME - routed to the "iTrainz Chat Interface"

The OpenURL() call will additionally support the following URL styles internally:

• trainz://install/KUID - opens an 'asset details' window which allows the user to install the specified content.