User Manual - iRunTrains v0.4 Prerelease

Introduction


Welcome to iRunTrains. This user manual describes the controls and features of the iRunTrains v0.4 Prerelease. The controls are very simple and can mostly be learned in a few minutes.  This manual is divided into three sections covering train & turnout controls, view controls, and additional miscellaneous controls.

Train & Turnout Controls


Upon starting  iRunTrains v0.4, up to three numbered trains will start running automatically. The number of each train (numbered 1, 2, and 3) is displayed above its engine and caboose. To select a train (making it the "current train" ... the one you can control), simply type its number on the keyboard. Note that each train number is displayed in blue, except for the current train's number which is displayed in red.

To decelerate and accelerate the current train, press the "[" and "]" keys, respectively. Each key press will change the train's target speed by a fixed amount, then the train will gradually reach that new speed. The target and actual speeds of each train are displayed graphically in the bottom left corner of the screen. As a shortcut, the delete or backspace keys can also be used to immediately cut the target speed of the current train to zero, then the train will gradually slow to a stop. If the shift key is held down while pressing the "[" or "]" keys, then the target train speed is changed by one-quarter of the normal amount. This is handy when you want very slow and precise control of train speed.

Any time a train is stopped, a red arrow is displayed above each engine showing its current forward-reverse direction. To toggle the direction of the current train, press the "\" key on the keyboard, then the train's red arrow will flip direction. NOTE:  You can only change the direction of the current train when it is stopped and its direction arrow is being displayed.

Switching turnouts is also done by number. Each turnout has a red "T-number" that is displayed directly above it, as well as a green/yellow line between the rails that shows where the trains will go on that turnout. To switch any turnout, simply type "T" then type its number, then you will see its green/yellow line flip.  As with a real model train, you should avoid switching turnouts while they have a train traveling over them, since it will cause the train to split apart.

Lastly, the return key can be used to toggle the turnout and train number displays on and off. Initially you will probably want them all displayed, but later you may wish to turn them off once you've memorized the number of each turnout and train.

View Controls


The iRunTrains v0.4 viewing options support five viewing modes, and you can control most of these viewing modes with your mouse, as well as the keyboard.  The five viewing modes allow you to experience your trains in some very cool ways, as described in the table below.
Manual Table View
 This is the default viewing mode, where you control everything manually. Specifically, you control the area you're looking at, the angles you're looking at it from, and the distance from which you're viewing it. Note: In iRunTrains v0.2 and earlier, this mode was simply called "table-view".
Helicopter Chase View
 In Helicopter Chase View mode, your eye follows the selected train automatically, and your viewing angle and viewing position both change automatically to follow the orientation of the selected train. You control your viewing angle relative to the train, and the distance from which you're viewing it. This view simulates the experience of following a train in a chase-helicopter. Note: In iRunTrains v0.2 and earlier, this mode was simply called "train-view".
Motion Match View
 In Motion Match View mode, your eye and viewing position both follow the selected train automatically, so you're literally matching the motion of the train.  You control your viewing angle, and the distance from which you're viewing.
Rail Fan View
 In this mode, your eye follows the selected train automatically, but your viewing position is stationary unless manually changed by you. This simulates what many "railfan" enthusiasts experience when watching full size trains in real life. It also simulates what most model railroaders experience when standing next to their real world layouts.
Engine Rider View
 In this mode, you're riding on the engine of the selected train, much like what the operators of ridable quarter-scale model trains experience.  As in real life, you are free to look all around while riding on the train.


Pressing the spacebar displays a sub-menu containing the above five viewing modes, numbered 1 to 5.  So to change your viewing mode, simply press the spacebar and then the number of the desired viewing mode. The current view will then change to the new mode.  Note that the current viewing mode is always displayed in the top left corner of the screen.

 The table below describes the keyboard and mouse controls that you can use in each viewing mode.
Viewing Mode
 Keys: Up, Down, Left, and Right Arrows
or
The Mouse
Keys:  "E", "S", "D", "F"
 Page-Up and Page-Down
or
Keys "+" and "-"
Manual Table View Control the angle from which you are viewing your  layout.
 Control the position on the train table that you are looking toward. Control the distance from which you are viewing your train table.
Helicopter Chase View Control the angle from which you are viewing your selected train. This angle is relative to the train's orientation.
Control the distance from which you are viewing your selected train.
Motion Match View Control the angle from which you are viewing your selected train. This angle is independent of the train's orientation.
Control the distance from which you are viewing your selected train
Rail Fan View
Control the horizontal position that you are viewing from. Control the vertical height that you are viewing from.
On-Train View Control the direction you are looking while riding on the selected train.



The above table is actually simpler than it first appears. In general, the arrow keys  are used to control the viewing angle in each mode. You also have the ability to use the mouse in addition to (or instead of) the arrow keys. Simply drag the mouse left, right, up, or down to change the viewing angle. The "E", "D", "S", and "F" keys are used in two view modes to shift the current view horizontally forward, backward, left, and right, respectively. Lastly the page-up and page-down keys (or "+" and "-" if you prefer) are used to control the viewing distance or viewing height. Note that on laptop keyboards, you may need to hold down the fn key to access the page-up and page-down keys.

Each time you press-and-release one of the above keyboard keys, within a couple seconds the target view will smoothly change by a set amount. So to change the view twice as much, you simply hit the appropriate key twice. Note that the key action is always press-and-release (not holding them down) ... the only exceptions are option and shift as described below.

Note that when you are in the Helicopter View mode, left-arrow and right-arrow are controlling your view angle relative to the current train. For example, the default train-view angle is to follow the train from behind, looking from the caboose toward the engine. However, you may wish to follow the train always looking at it from front to back, or perhaps always from one side of the train. In the Helicopter View mode, this train-relative viewing is done for you automatically.  Note that regardless of the current viewing mode or changes you've made, you can always return to the default from-above table-view at any time by pressing the home key on your keyboard.

If the shift key is held down while pressing any of the view modification keys listed above, then each key-press changes your view by one-quarter of its normal amount. This is handy when you want more precise control of your viewing angles or zoom levels.

If the option key is held down while pressing most of the view modification keys, then the key initiates "continuous" motion instead of a fixed change. For example, the left arrow key normally changes your view to the left about 30 degrees. However with option held down, your view will instead start spinning to the left at about 4 degrees/second and will continue spinning. Pressing option+left again will increase it to 8 degrees/second, or pressing option+right will decrease it back to zero. The up and down arrows and zoom keys work with option in a similar way. This takes a little practice to learn, but is great fun once you do. In some viewing modes, it almost feels like you're flying around your trains. If you ever lose track of these continuous changes, the end key can be used to immediately stop all continuous view changes that you may have initiated as described above.

Miscellaneous Controls

You can use the right-button on your mouse to access a pop-up menu providing some additional commands. These commands allow you to select a different layout or change the terrain color and horizon.

By default, a block of help text is displayed in the top-left corner of the iRunTrains screen. The "H" key can be pressed to toggle this help text on and off.

The "P" key can be used to pause the iRunTrains program in case you need to reply to an email, answer the phone, etc. Once paused, pressing any key will resume the program.

By default,  iRunTrains will run full-screen, meaning you cannot see your dock, menu-bar, and other applications. You can press the "G" key to toggle between running full-screen like this or running in a normal window. When running in a window, you are free to resize and move that window, access your menu and dock, or switch to other applications as you normally would.

Lastly, the Cmd+Q key combination can be pressed to immediately quit the iRunTrains application. Since iRunTrains runs from a Terminal window on your Mac, you will need to also quit your Mac's Terminal application separately.  That's normal. Note that if iRunTrains detects any problems while running, an error message will be printed to that same terminal window to assist with trouble-shooting.