New TrainzScript Features - TS2009 - Revision history

Tonyhilliam: Tonyhilliam moved page New TrainzScript Features to New TrainzScript Features - TS2009

2018-03-14T01:47:09Z

Tonyhilliam moved page New TrainzScript Features to New TrainzScript Features - TS2009

← Older revision	Revision as of 01:47, 14 March 2018
(No difference)

Marinus: /* Global script context */

2010-10-31T00:32:42Z

Global script context

← Older revision		Revision as of 00:32, 31 October 2010
Line 21:		Line 21:
	always-load-in-global-context 1		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. If ''always-load-in-global-context'' is not used, assets running in ~~local (active module)~~ context will access an instance of the library also running in ~~local~~ 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 ~~local~~ and global context.		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. [[Types#string\|Strings]] are copied using [[class Str#CloneString\|Str.CloneString()]] and [[Types#Array\|arrays]] can be copied using the [[Arrays#copy\|copy()]] operator. There are also possible limitations to cross context message passing, sniffing, etc.		'''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. [[Types#string\|Strings]] are copied using [[class Str#CloneString\|Str.CloneString()]] and [[Types#Array\|arrays]] can be copied using the [[Arrays#copy\|copy()]] operator. There are also possible limitations to cross context message passing, sniffing, etc.

Marinus: /* Global script context */ - added always-load-in-global-context information

2010-10-31T00:20:12Z

Global script context: - added always-load-in-global-context information

@@ Line 16: / Line 16: @@
 * 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.
 = Global settings libraries =

Windwalkr: /* Cross-asset script includes */

2010-05-26T04:56:29Z

Cross-asset script includes

← Older revision		Revision as of 04:56, 26 May 2010
Line 8:		Line 8:
	* Add the same KUIDs to your asset's ''kuid-table''.		* Add the same KUIDs to your asset's ''kuid-table''.

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

	~~''note: This functionality is untested and may be withdrawn.''~~


	= Global script context =		= Global script context =

Windwalkr: 1 revision

2010-02-03T13:59:31Z

1 revision

← Older revision	Revision as of 13:59, 3 February 2010
(No difference)

imported>John259: /* Global script context */ Expanded VM on first occurance

2009-11-24T16:38:02Z

Global script context: Expanded VM on first occurance

New page

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.

''note: This functionality is untested and may be withdrawn.''

= 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.

= Global settings libraries =
Global settings libraries are standard script libraries with an additional tag entry in their [[config.txt file]]s.

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 file]]s.

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.