Help:MissionCode Manager Rule

Revision as of 16:51, 9 June 2016

Mission Code Manager rule

MissionCode Manager is a rule ( <kuid:61392:8200> ) which enables to add, edit and manage Mission Code strings, which can be assigned to trains and can be used to auto select paths in interlocking towers to route the trains to their destination.

This page is currently under construction. The MissionCode Manager rule is currently under development but will be soon uploaded to DLS. The idea is to have finished publishing this help before release of MissionCode Manager rule so that all trainers will benefit from this online help using the rule.

This page relates to the use of the MissionCode manager rule in both Surveyor and Driver.

Train Mission Codes : what is it and for which purpose ?

A train mission code is any string choosen in a list of arbitrary mission code strings that needs first to be defined by editing the MissionCode Manager Rule (<kuid2:61392:8200>) under surveyor. After defining all the train mission codes you will use in your session, you can assign a train mission code to any train using the driver command SetMissionCode ( <kuid:61392:8201> ). All trains, by default have no mission code assigned but may be assigned a train mission code using the SetMissionCode driver command. The mission code will stay linked to the train until a new mission code is assigned to the train or the mission code is cleared using also the SetMissionCode driver command. Mission codes linked to a train are kept when a session is saved and later restored. Several trains may be assigned simultaneously the same mission code.

After defining and setting a train mission code to a train, you can also select while editing the Mission code Manager rule any existing interlocking tower and path and assign to the path any mission code and options. Later in driver mode, when a train with a mission code, will reach the entry signal, the Mission Code Manager Rule will be called as a listener for the interlocking tower, and will activate a path at this entry signal for which the mission code has been assigned.

Train Mission Codes : in practice how to define them

To use train mission code features in a session, you need first to add to your session rules the Mission Code Manager rule, then edit the rule and define your list of available train mission code strings for this session. When editing the MissionCode Manager rule, the first page displayed will show the list of all available mission code strings already defined and will offer to add some new mission code, to rename or clone or delete existing ones.

In the example above, six mission codes strings (GABCAR,GARCAB,GARMON,GARTUR,MONGAR,TURGAR) have been defined for the current session.

Train Mission Codes : how to assign a code to an interlocking tower and path

The Mission Code Manager rule has several tabbed pages that can be accessed using the tabs at the top left of the screen. On the example above, you can see that the Mission Codes page is currently displayed ( tabs in pink ) and that just below you can select the Interlocking Tower page tab and the Interlocking Tower Path tab. To select the path in order to assign a mission code, first select the interlocking tower page by clicking on the interlocking towers tab. Mission Code Manager will now display the list of all available interlocking towers in the current session :

Then to select an Interlocking Tower Path in an Interlocking Tower, just click on the interlocking tower view paths link you want to display. It will then display the Interlocking Paths page with all the defined paths in the selected Interlocking Tower.

And finally, to display, add or suppress mission codes assigned to a path, just click on the view details link for the path you want to look at.

On this path details page, you have some links to add new mission code to the current selected path or to remove some already assigned mission codes. On the example above, you are editing mission code assignment for the path SouthV4 in tower IT Garrenac South (with entry signal C132 and exit signal C331) and two mission codes are valid for this path : mongar and turgar.

It is also possible to define a priority between 1, 2 and 3 for a path mission code assignment. This priority will be used when the Mission Code Manager has to activate a path for a train at an entry signal. If several paths are available at the entry signal and the mission code is valid for several of these paths, the mission code manager will try first to activate an eligible path (available path with mission code assigned to this path) with mission code priority 1, then 2 and last 3. If several paths are eligible for a mission code at the same priority level, the mission code manager will try to activate a randomly chosen path between paths with same priority. This feature may be usefull for passengers train at a station or goods train at a yard : mission code manager will first try to activate one of the eligible paths with priority 1. If none are activable, it will then search for paths with priority 2 and then priority 3. Using adequate priorities, you can send a passenger train on a path to a preferred platform, with the opportunity to send the train to another platform using another path if the first one is already occupied.

The option follow path is an option by default set to none, that can be set to either "on path activation" or to "on train entering path". When the option is set to "on path activation", when the current path will become active, Mission code manager will search forward for the next entry signal after the current path exit signal, and will try to activate a new path (follow path) for the current train at this new entry signal using the same assignment process than above. With the on train entering path, it is only when the current train enters the current path (leaves the current path entry signal) that the follow path at the next entry signal is searched. Using these options you can in fact chain paths activation following either the activation or the progression of the train in the previous paths.

Train Mission Codes : how to assign a code to a train

Now that we have defined Train Mission codes and that we have assigned to Interlocking Tower Paths all the mission codes valid for this path, the last step is to assign Train Mission code to a train.

This is done by using the driver command SetMissionCode ( <kuid:61392:8201> ). In order to do so, the first step is to enable SetMissionCode driver command for the current session. To do so, you just edit the DriverCommands rule under surveyor and you tick the SetMissionCode driver command.

Then you can select in any driver order bar the SetMissionCode driver command and choose the mission code to assign to the current driver train. You can also do the same in the DriverSetup rule to insert SetMissionCode driver command in a scheduled driver order bar.

In the example above, after enabling the SetMissionCode driver command, you can use it either to assign to a train one of the defined mission code in Mission Code Manager rule or to clear the current existing mission code. And now with mission codes defined, mission codes assigned to specific paths and to specific trains, everything is in place for auto path assignment while a train arrives at an entry signal.

Train Mission Codes auto path assignment : how it works ?

When you have defined your mission codes, assigned them to specific interlocking tower paths and to your trains, how all these will work. Quite simple: when a train approach an entry signal, then interlocking tower will call the mission code manager rule as a listener to assign a path for the current train. The mission code manager will look at the incoming train ,check if it has a mission code. If it has no mission code, it will return to the interlocking tower that it does not support the train and the normal interlocking tower processing will be done for this train with no mission codes. For a train with mission code, the mission code manager will return to the interlocking tower that it takes care of the current train path and that no further processing is needed. Then the mission code manager will look at all the available paths at the current entry signal and will extract only the list of all paths eligible for the train mission code. It will first look in this list to paths with mission code priority 1 then 2 then 3 and will try to assign a path available (not occupied) in the priority order. It is smart enough that if there is only one path available at an entry signal, it will assign it even if no mission code has been assigned to the path. If there are several paths available and no paths are eligible the train is stuck at the entry signal.

When looking to available paths when a train reaches an entry signal, Mission code Manager uses a method similar to the standard Interlocking Tower QueryAutomaticPathAssignment method to find the available paths : this means that only paths with the AI auto assign flag set are available for AI trains and only paths with the Player auto assign flag set are available for players driven train. if no paths are available meeting these criteria, no path assignment is done and the train will be stuck when arriving at the entry signal. If you are using manual paths (paths with no AI auto assign flag set or Player auto assign path set ), you will need to use path trigger (explained later below ) to auto assign manual paths.

So when you have configured all your mission codes, paths and trains. You only need to run your session and the paths will be auto assigned based on the current train mission code and paths configuration in Mission Code Manager.

Train Mission Codes auto path assignment : and what are path triggers ?

PathTriggers are standard trackmarks or triggers that help to assign path following the method above when the standard assignment routine called when the train approaches the entry signal is not convenient. PathTrigger enables to do the same assignment process, but earlier or later than with the standard routine called when the train approaches then entry signal (about 1 mile before reaching it). It enables also to assign manual paths (paths with the AI auto assign and Player auto assign flags not set).

To assign paths earlier, you need only to position a trackmark or trigger on the track to the entry signal before the 1 mile standard distance for path assignment. You need to register in the pathtrigger tab of the mission code manager rule your path trigger. And that's all. when a train will reach the path trigger, MissionCode Manager will be called, will look forward for the entry signal along a distance of maximum 10 km and when the next entry signal is found will immediately launch the auto path assignment process as if the train had already reached the 1 mile distance to the signal. This way you can fire some early auto path assignment before the standard signal reached routine is called.

PathTrigger can also do some late path assignment, but this need some more configuration for the path. Path standard auto assignment routine fired by train reaching an entry signal will look only to path with the AI or Player auto assignment flag set. It will never look to manual paths : paths with both AI and Player auto assignment not set. If you configure your path with these two flags unset and you position a path trigger at less than the 1 mile distance from the entry signal, you will be able to have some late or delayed auto path assignment as the standard routine will first be called but will not assign any path, and then when the train will reach the path trigger, the path trigger processing will also look to manual paths with no AI or Player flag set, and will assign eligible paths if there are some. Using this feature, you can have some late auto path assignment but only if at the entry signal there are no paths with the AI or Player flag set.

PathTriggers are optional and need to be used only when the standard path auto assignment routine fired when a train approaches an entry signal is not convenient for your session. Mots of my sessions using Mission Code Manager do not have any path trigger, but sometimes in some specific cases path trigger may be very usefull for some specific train behavior.

There is also in the package a driver command ITMissionCodeAssignNextPath ( <kuid:61392:8202> ) that will do the same processing as a path trigger on the current train when the command is executed. This driver command may be usefull for train stopped at a platform or a yard to start some auto path assignment process chain with follow on options.

Train Mission codes : some other miscellaneous features

Another usefull feature is on the interlocking paths list display. The interlocking paths are displayed in high green when the current selected mission code has been added to the interlocking path. It is displayed in low green, when there is only one path available at the entry signal, and in this case Mission code Manager is smart enough to assign the unique path at run time under driver for any mission codes. And the path name is displayed in grey, when several paths are available at the entry signal but the current selected mission code has not been assigned to this path. On the example above, SouthV4 and SouthV5 have selected mission code MONGAR in their mission codes assignments. SouthV2 is not eligible for mission code MONGAR. And V1South, v2South, v3South, v4South, V5South have all a unique path defined at their entry signal that will be selected for any mission code train. This path list page screen supports filtering on both interlocking tower and mission code. You can also select "no filtering" for the interlocking tower, and all the available interlocking towers and paths will be displayed with the high green, low green or grey color and it can be usefull to check for a mission code what are the paths eligible and not.

I think that it is all what is needed to use Train Mission code. I hope you will enjoy this new rule to help you for interlocking tower path assignment. And do not hesitate to post in the forum if you need some help or only to make some some comments.

Regards. Pierre GUY (61392)