Latest revision as of 23:59, 3 February 2010

This topic is a proposition for an helper library implementation for Incubator/PersistentSessionVariables from User:Pguy. It should need Auran's approval before starting implementation.

The Incubator/PersistentSessionVariables is an Incubator project to create a new session variables helper library that will offer a common session variables interface for supporting multi scope session variables type.

[edit] Summary

Updated 2009 August 17th

The new library interface will introduce 4 distinct scope session variables :

local scope variable is similar to current session variables and are session variables dedicated only to current session. For integer and string type local scope session variables, the variables will be replicated to the old session variables to offer upward compatibility.

global scope variables are common persistent session variables shared between all routes and sessions.

train scope variables are session variables local to a train.

named game object scope variable are session variables associated to a named game object.

All these variables can be either of string, int, bool, float and of soup type. All these variables are saved and restored under normal session save / restore operations. Global scope variables are save/restored with global trainz settings parameters.

From a script user, new session variables are available through some static helper class interface like LocalVars.xxx(...), GlobalVars.xxx(...), TrainVars.xxx(Train, ...), GameObjectVars(GameObjectName, ... ) where xxx is similar to Soup Set/GetNamedTag primitives.

All static helper class calls are transfered to the new session variable library which implements the new variables and makes the link with old libraries for variables upward compatible.

All these new variables should make more easy persistent data and inter communication data between objects under driver command script or rules behavior.

[edit] Example of potential use

The new TrainVars session variables offer many potential for future rules or driver commands development.

For example, you can associate a string mission code to a train. Some new smart scripted objects (smart trackmarks) or rules can read the mission code var and generate a new train schedule or a new path to follow based on this mission code.
You can also imagine to associate in a game object var associated to a station a list of valid mission code fo stopping. And have a new driver command that will look at the train mission code and will stop or not the train depending if there is a matching mission code or not ...

Another example. You can associate a game object var containing its final destination to each vehicle in a train. You can create a rule that will read this variable to split the train vehicles and sort them depending on their final destination in a yard ...

The new session variables library does not add by itself new functionality to Trainz, but can a be a starting brick to build new rules, driver commands, smart scripted assets that will read these variables and will do different tasks depending on the current vars value.

[edit] a first look to the implementation

Variables in the same scope can be implemented a named tags in a soup. There will be in a session a local soup (saved with the session), a global soup (from a global library and saved with Trainz global parms), an array of trainvars soup (one for each train with at least one variable - saved also with the session) and an array of gameobject vars (one for each gameobject with at least one variable - saved also with the session).
Reusing soup named tags offers by construction string, int, float and soup value support. When writing a variable, two tags are writen : one for the value and one for the variable type, enabling to query the type of a variable before using it.
For numeric vars, minimum and maximum values are also supported by writing some other tags to the soup. For string vars, you can add value validation by creating a tag with a list of authorized values.

Save / Restore of sessions is supported by standard GetProperties(...)/SetProperties(...) operations. For train session variables, the tags are associated to the first vehicle name and are restore to the same train by retrieving the vehicle's train ... For game object session variables, those variables are simply associated with the game object name ...

User interface will be through a rule QuickSessionVars that will offer an interface similat to QuickDrive both in surveyor and driver mode to add, edit and delete vars either local scope, global scope, train scope or game object scope.

One other interest to implement train vars as a soup associated to the train is to be able with another rule Quick Portal Manager to save trainvars when a train leaves through a portal and to restore them when the same train is recreated later either through another portal on the same route or on another route.


By the way, if there was a generic user field in GameObject class where a script can store a soup reference and that in this case the soup is then saved and restored during save / restore operations, it should make quite more easy to implement such an variable extension to those objects ...