Timetable Decisions

"Decisions" is a new feature added to timetabling in loader version 4.5. It only affects timetables that explicitly use it; all existing timetables are unaffected.

This feature allows you to write timetables that do different things at random. For example, you can allow a train to only divide sometimes or to become one of two different trains. While some of these things can be done by (mis)using rules, decisions give you more flexibility.

This page describes what can be done right now; more features that use decisions will be added in the future.

What is a decision?

A decision consists of a name and a set of choices. It also has a description, but this is purely for the convenience of the timetable writer and doesn't do anything. The main F4 timetable editing window now has a "decisions" tab that lists all the decisions in the timetable.

As the simulation proceeds, it may reach an entry in a timetable that requires a decision to be made. At that point the core code will select one of the choices. From then on, anything that specifies that choice will happen as if it was unconditional, while anything that specifies another choice will be ignored.

When you load a saved simulation, the state of each decision - which choice made, or none - is restored. When you load a saved timetable, all decisions in that timetable are set to "no choice made".

So what is a choice?

A choice, as the name suggests, is one of the choices involved when a decision is made. It consists of a name, a weight, a description, and possibly an announcement. Once again the description is purely for the convenience of the timetable writer and doesn't do anything.

The weight indicates how common, relatively, this choice will happen. So if there are three choices with weights 5, 3, and 2, the first will be selected 50% of the time, the second 30%, and the third 20%. If the third is changed to 4, then the probabilities will change to 5/12, 3/12 (i.e. 1/4), and 4/12 (1/3).

The announcement will appear in the message window and the incident panel at the point that the choice is made. This allows you to say something like "Special train being run" to the user and then make appropriate changes to the timetable that are more than just running that train.

Lazy evaluation

An important thing to note is that decisions use "lazy evaluation". They are not all determined at simulation start. Instead, a decision is only made when it's necessary. This means that a saved game can have some decisions made but others not yet made, so that different things will happen each time you restart the saved game (this is like train delays; only those already announced are stored in the saved game).

What's in a name?

A decision or choice name can be any string, except that leading and trailing spaces are ignored and names cannot begin with a square bracket. Names are case-sensitive, so "SpecialTrain", "Specialtrain", "SPECIALTRAIN", "Special Train", and "Special train" are all different decisions. You can have consecutive spaces, so "A B" and "A B" are different decisions, but the timetable analyser will warn you if you do this since it's hard to spot.

Names can use square brackets except as the first character, but note that this can be confusing: in the list of decisions, "Special [run]" is used to mean "Decision 'Special', choice 'run' has been selected". They are best avoided.

The timetable analyser will warn you of duplicate names (different decisions can use the same name for a choice; that's not a duplicate) and if you use a decision or choice name that hasn't been defined.

While all names apart from those beginning with open brace will work in simple decisions, they might not work with special decisions and choices (see below). For example, a choice name with vertical bar in it can't be used with the "[any]" special choice. Therefore you are recommended to stick to letters, digits, single spaces (not groups of spaces), and the other characters ! # $ % ( ) ampersand asterisk plus minus slash comma full-stop and underscore.

So how do I use them?

Creating decisions and choices

The first thing is to create the decisions you want. This is done with the F4 "decisions" tab. The buttons on this tab are:

Edit	Edit the selected decision; this brings up a separate dialogue box. Double-clicking a name in the list has the same effect.
New	Create a new decision; this brings up the same dialogue box.
Delete	Delete the selected decision and all its choices.
Choose	Select one of the choices in this decision, at random. This is disabled once a choice has been made.
Unchoose	Cancel the choice made; this is disabled if no choice has been made. Note that this is dangerous and should only be used during testing, since the timetable may be put into an inconsistent state.

If a choice has been made for a decision then the name of the choice will be shown in square brackets in the list of decisions.

When you select a decision its description is shown in the grey area at the bottom.

The decision edit box lets you change the name and description and has the following buttons:

Edit	Edit the selected choice; this brings up a second separate dialogue box. Double-clicking a name in the list has the same effect.
New	Create a new choice; this brings up the same dialogue box.
Delete	Delete the selected choice.
Choose	Select one of the choices in this decision, at random. This is disabled once a choice has been made.
Unchoose	Cancel the choice made; this is disabled if no choice has been made. Note that this is dangerous and should only be used during testing, since the timetable may be put into an inconsistent state.
Force	Force the selected choice to be made. This is intended for testing.

The choice edit box lets you change the name, description, weight, and announcement of a given choice.

Weights are purely relative, so setting the weights of three choices to 1 is the same as setting all three to 42. Similarly, setting two choices to 1 and 3 is the same as setting them to 25 and 75.

Using decisions and choices

There are two ways you can use decisions and choices at present.

Firstly, you can make the entry or seeding of a train conditional. To do this, fill in the "Decision" and "Choice" boxes in the "Train Details" tab of the train editing dialogue box. If these aren't empty, the train will only enter or be seeded if that choice is made; otherwise it won't run.

Secondly, you can make a specific activity at a location conditional. Again, you fill in the "Decision" and "Choice" boxes in the Trip Activity editor. If they aren't empty and a different choice is made, the activity won't happen and will be completely ignored (for example, trains won't take them into account when working out where to stop). If you make an activity conditional like this, it will show with a question mark in timetable listings.

If you fill in one of "Decision" or "Choice" and leave the other empty, they will both be treated as empty but the timetable analyser will warn you.

Special decisions and choices

Special decisions

There are currently two kinds of special decisions. These can appear whenever you use a decision, but won't appear in the decision list for a timetable. Which ones are available will depend on the simulation being run and should appear in the simulation manual. (If it doesn't, ask the author to add it. If the sim author doesn't know how to determine the codes, tell them to ask Clive.)

A simulation option special decision looks like "[NSC!NBIDI]" (without the quotes, of course), where the part after the exclamation mark ("NBIDI" in this case) is specified by the simuation author. Each such code represents a startup option (not all options may have codes, or the sim author may not wish to publish those codes, and some codes can represent the effects of options, such as which of a random selection has been made). The possible choices are "Y" (option selected) and "N" (option not selected).

For example, in the Peterborough simulation, decision "[NSC!NBIDI]" choice "Y" for an seeding train means that the train will only seed if the "Spalding BiDi" option is in effect.

A chaining special decision looks like "[EXT!XCAM]", where the part after the exclamation mark ("XCAM" in this case) is specified by the simuation author. Each time the decision is tested, the core code checks to see whether an adjacent simulation - identified by the specific code - is chained (choice 'Y') or not (choice 'N'). Note that, if the chaining status changes, the choice will change - this is unlike normal decisions where the choice is frozen the first time it is made.

For example, in the Peterborough simulation, decision "[EXT!XCAM]" choice "N" for an entering train means that the train will only enter if Cambridge is not chained (this can be used in any decision if you know what you're doing; it's not limited to trains entering at the entry point that corresponds to the chaining).

Special choices

There are currently two kinds of special choices. These can appear whenever you use a decision, but won't appear in the list of choices.

A choice of the form "[any] Mon | Wed | Fri" means that a choice will be made for this decision if necessary, after which the relevant action will be taken if any of the choices "Mon", "Wed", or "Fri" has been chosen, but not if any other choice has been. This avoids the need to duplicate trains or activities that happen for more than one, but not all, choices. "[any] Mon" is, of course, just the same as "Mon".

A choice of the form "[not] Mon | Wed | Fri" means that a choice will be made for this decision if necessary, after which the relevant action will be taken if none of the choices "Mon", "Wed", or "Fri" has been chosen, but will be taken if any other choice has been. It is equivalent to "[any]" with all the remaining choices. You can write "[not] Sun" with only one choice listed.

Examples

TO BE WRITTEN

Back to Timetables, Introduction to Writing

Back to User Wiki

Last edited by clive on 08/12/2021 at 11:40