MissionCodes Manager

Revision as of 20:08, 17 February 2019

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 has been updated to support new features brought with version 60 of Mission code Manager and associated stuff.

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 one or several train mission codes to any available train using either the trains tab while editing MissionCode Manager rule, or using the driver command SetMissionCode ( <kuid:61392:8201> ) to assign the first mission code to your current train and AddMissionCode ( <kuid:61392:8203> ) to add another mission code to the current train. All trains, by default have no mission code assigned but may be assigned one or several train mission codes. The mission codes will stay linked to the train until new mission codes are assigned to the train or the mission codes are 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 codes.

After defining and setting train mission codes for a train, you can then 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 mission codes, 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 matching one of the the mission codes currently assigned to the train.

You may look at mission codes as a set of keys assigned to a train. When searching for a path at an entry signal, MissionCode Manager will only look to paths matching one of the keys assigned to the train. Only paths with matching mission code will be used for a train when searching for a path at an entry signal.

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, four mission codes strings (CentralToSouth,NorthToSouth,SouthToCentral,SouthToNorth) have been defined for the current session.

This page enables also to set the default global values for Mission Code Manager options like default follow path depth, default follow path option, follow path search distance, exit signal track check mode, unique path select mode option, process all trains option and debugging mode which will be detailed later below in their respective section. The page includes also links to copy MCM data to the common clipboard and to paste MCM data from the common clipboard in order to enable copying MCM data between sessions. It has also a link repair mission codes from internal data that enables to try to recreate missing mission codes from internal MCM data if you have by mistake deleted some still needed mission codes.

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

Now that we have defined the mission codes to be used, the next step is to assign mission codes to trains.

There are now two methods to assign mission codes to train. you can either use the trains tab while editing Mission Code Manager Rule or you can use one between several driver commands to assign mission code at run time.

Using the trains tab in Mission Code Manager rule

As you can see in the above example, the trains tab in Mission Code Manager Rule will list all the trains available in your session ( it is in fact a copy of the list of all trains defined in the driver setup rule ) and the mission codes assigned to it. Using the add mcode and remove mcode links, you can add or suppress a mission code in the set of mission codes assigned to this train.

When the session will start, the MissionCode Manager rule will assign all the mission codes that were defined to each of the available train.

This method is the easiest way to assign mission codes to a train as it does not need to use any driver command in schedules.

Using driver commands

The other method is to use driver commands to assign mission codes to a train.

SetMissionCode driver command ( <kuid:61392:8201> ) will first clear any existing mission codes set assigned to the current train and will then assign the mission code selected in the menu to the current train. AddMissionCode driver command ( <kuid:61392:8203> ) will add the mission code selected in the menu to the current train mission codes set. RemoveMissionCode driver command ( <kuid:61392:8204> ) will do the reverse and will suppress the mission code selected in the menu from the current train mission codes set if the mission code had been previously added to the set.

In order to use these commands, the first step is to enable SetMissionCode, AddMissionCode and RemoveMissionCode driver commands for the current session. To do so, you just need to edit the DriverCommands rule under surveyor and tick the SetMissionCode, AddMissionCode and RemoveMissionCode driver commands.

Then you can now select in any driver order bar the SetMissionCode driver command (or AddMissionCode or RemoveMissionCode ) 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.

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

The last step is now to assign mission codes to Interlocking Tower Paths.

In order to do so, just 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.

Since release 28, this page has also now a link to globally enable or disable the path auto assignment standard routine which is automatically called when a train is on approach of a signal at 0.5 mile. With the option disabled no path auto assignment is done for train with mission codes and explicit path assignment must be done using ITSetPathXXX, ITMCAssignNextPath, path trigger or follow path options

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.

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.

It is also possible on this page to edit the auto assign AI flag and auto assign flag for the current path.

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.

You can set a global default value for the follow path option, which can be overridden by a default value at the path level, which can also be overridden at the mission code level.

Chaining path activation by using follow path option is limited by the current follow path depth. The follow path depth defines the maximum number of paths activated but not entered that a train can have. If a follow path activation is requested but the follow path depth is exceeded, the follow path activation will be delayed until the current number of paths activated but not entered will decrease under the follow path depth. The follow path request is not lost but is only delayed.

There is a global default follow path depth which is set on the initial mission code page. This value can be overridden at the mission code level by entering another value for any mission code on the initial mission code page.

There is another way to add/remove mission code eligibility for a path. This can be done using the "view paths" link for a specific mission code on the initial mission code page. This link will display all the available paths in all towers :

The paths displayed in low green are path that are unique (only path available) at their entry signal and are by default considered as eligible for any mission codes without the need to configure anything. Paths displayed in high green are paths that have been explicitly made eligible for the selected mission code by validating the selected mission code for the path. Paths displayed in low grey are paths not eligible for the currently selected mission code.

On each path line, depending on its current status, you will find either a "add selected mcode to path config" or "suppress selected mcode from path config" to add or suppress mission code eligibility for the path. By listing for a selected mission code all paths eligibility, it is easy to have a global value of all the paths already enabled for a mission code and to update the configuration if needed. The view details link remains available also on this page to switch to a path view of all eligible mission codes for entering other specific parameters like priority and follow path option.

The page includes at its beginning an option to display all paths or only eligible paths and a tower name filter to enable to tailor this page to your need. To add new mission code eligibility to a path currently not eligible, of course you need to have the display option set to all paths and not limited to eligible paths.

Train Mission Codes auto path assignment : how it works ?

And now that you have defined your mission codes, assigned them to trains and to specific interlocking tower paths, how all these will work together for path assignment.

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 and retrieve all the mission codes assigned to the train. If the train 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. But for a train with some mission codes, 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 available paths at this entry signal eligible for one of the current train mission codes set. A path is eligible for a train only if there is a matching mission code in the list of the path supported mission codes.

To choose the target path, Mission Code Manager will then look in this list of eligible paths for paths with matching mission code at priority 1 then 2 then 3 and will try to assign a path 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 this unique path even if no mission code has been assigned to it. If there are several paths available and no paths are eligible the train will remain 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 : it will look only to paths with the AI auto assign flag set are available for AI trains and only to 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, trains and paths assignment, you only need to run your session and the paths will be auto assigned based on one of the current train mission codes and following your paths mission codes assignment configuration defined 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 then need to register in the pathtrigger tab of the mission code manager rule the path trigger you are using. And that's all. When a train will reach a registered 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 it 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.

Path assignment when fired by a PathTrigger is a little different from standard path assignment. As with standard assignment, it will first search for paths with AI auto assign flag or Player auto assign flag set for AI trains or Player train, but if it does not find any available paths, it will then do a second search where it will also look to manual paths (paths with no AI auto assign or Player auto assign flags set). This dual step search is mainly done to enable late path assignment. To do some late path assignment (later than the standard method called at 1 mile from the entry signal) , you need to only use manual paths at the entry signal. When the standard routine will be called at 1 mile from the entry signal, it will find no available paths and so will not assign any path for the train. When later, the train will reach a path trigger, the process will restart, will still find no available paths with AI auto assign or Player auto assign flags set, but it will then look to manual paths and will then assign a path between the eligible manual paths at the entry signal. Using this feature, you can also do 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. Most 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 ITMCAssignNextPath ( <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)