User Manual - iRunTrains Concept Demo

User Manual - iRunTrains For Macintosh - v0.7

INTRODUCTION

Welcome to iRunTrains for Macintosh. This user manual describes the controls and features of iRunTrains v0.7. The controls are very simple and can mostly be learned in a few minutes. This manual is divided into four sections covering Basic Controls, Train & Turnout Controls, View Controls, and RailModeller Compatibility.

BASIC CONTROLS

By default, four blocks of help text are overlaid across the top of the iRunTrains screen. The "H" key can be pressed to toggle this help overlay on and off. On older Macs, you may notice a better frame-rate (eg smoother animation) with the overlay turned off.

You can use the right mouse-button to access a pop-up menu. This menu allows you to select different layouts or change your display/control preferences. The preferences include terrain color and texture, help-overlay text color, various display toggles, keyboard preferences, and the amount of train momentum. Note that on laptops with no right-button, you can configure right-button behavior using the Apple Menu -> System Preferences -> Trackpad settings. The iRunTrains -> Preferences -> Mouse dialog also contain settings for right-button behavior.

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.

iRunTrains can be run either full-screen or in a window. When full-screen, you cannot see your dock, menu-bar, and other applications. You can press the "G" key to toggle between running full-screen or running in a normal window. When running in a window, you are free to re-size and move that window or switch to other applications just 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 also need to quit your Mac's Terminal application separately. That's normal. Note that if iRunTrains detects any problems while running, an error message should be printed to that same terminal window to assist with trouble-shooting.

TRAIN & TURNOUT CONTROLS

Upon starting iRunTrains v0.7, three numbered trains will start running automatically. The number of each train (numbered 1, 2, and 3) is displayed above its engine. 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. 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. 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. For quicker stops, 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.

Any time a train is stopped, a red arrow is displayed above the 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" displayed 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 hear and 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 that will cause the train to split apart or derail.

Although it is not yet possible to couple or uncouple cars, you do have limited control over each train's "consist" of cars. This is still an experimental feature that needs improvement, but for now here is how it works. For the selected train, press "c" (lower case) to highlight the current car. The highlight will either be a horizontal red marker over a visible car, or a vertical yellow marker where a car can be placed. Press "C" (upper case) to change the selected car to the next type of car. This can also be used to make a car not visible, then it is replaced by the yellow marker.

You can also control several different train sounds. For example, when using Helicopter Chase View (described in the next section) you will hear the sound of the helicopter you're flying in. Press the "M" key to mute the helicopter if you would rather just hear the trains. A full-size train's bell is generally used for safety when arriving or departing a station. You can press the "B" key at any time to start/stop the warning bell of the current engine. You can also press the "W" key to sound the whistle of the current train. You will hear a "long" whistle by default, or type shift-"W" for a "short" whistle. Train whistles are generally used to signal the engineer's intent. For example, here are the signals used at the Walt Disney World Railroad:

One Short - Attention
Two Short – Forward Movement
Three Short – Reverse Movement
One Long, One Short – Approaching Station "Here Comes the Train"
One Long, Two Short – Crew spotted along track, or used as a general greeting.
Two Long, One Short, One Long – Public Crossing ahead.
Two Long, One Short – Meeting Point (Junction)
One Long – Stop Immediately / Emergency stop.
Four Long – Train in distress.

VIEW CONTROLS

The iRunTrains v0.7 view controls support six viewing modes, and you can control all six modes with your mouse as well as the keyboard. The six 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 angle you're looking at it from, and the distance from which you're viewing it.
Helicopter Chase View	In this 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 you control the distance from which you're viewing it. This view simulates the experience of following a train in a chase-helicopter.
Motion Match View	In this 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 "rail-fan" enthusiasts experience when watching full size trains in real life. It also simulates what model railroaders experience when standing next to real world layouts.
Engine Rider View	In this mode, you're riding on the engine of the selected train, much like what the engineers of outdoor quarter-scale model trains experience. As in real life, you are free to look all around while riding on the train. You can also ride the sides or front of the engine as described below.
Caboose Rider View	In this mode, you're riding on the caboose of the selected train, much like what the passengers of outdoor quarter-scale model trains experience. As in real life, you are free to look all around while riding on the train. You can also ride the sides or back of the caboose as described below.

To change view modes, press the spacebar to display the menu of viewing modes, numbered 1 to 6. Then press the number of the view you want, and the view mode will change to it. Note that the current viewing mode is always displayed in the top left corner of the screen. In the three modes where your eye automatically follows the train, typing the train's number a second time will toggle between following the front and back of the train.

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 (by dragging)	Keys: "E", "S", "D", "F" or The Mouse (by double-clicking)	Keys: Page-Up & Page-Down or "+" & "-" or The Mouse (by [option]-dragging)	"Z" Key
Manual Table View	Control the angle from which you are viewing your layout. Or shift-drag to control the point you are looking toward.	Control the position on the train table that you are looking toward.	Control the distance from which you are viewing your train table.	Zoom in/out.
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.	Zoom in/out.
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	Zoom in/out.
Rail Fan View		Control the horizontal position that you are viewing from.	Control the vertical height that you are viewing from.	Zoom in/out.
Engine / Caboose Rider Views	Control the direction you are looking while riding on the selected train.			Zip around.

The above table is actually simpler than it first appears. To control your viewing angle, use the arrow keys in each mode. You also have the ability use the mouse in addition to (or instead of) using the arrow keys. Simply drag the mouse left, right, up, or down to change the viewing angle. As a shortcut, the "A" key will spin your view angle by 180 degrees. This is great for checking what's behind you. In Manual Table View, you can also shift-drag to specify the point you are looking toward. To pan, the "E", "D", "S", and "F" keys are used in manual and rail fan modes to pan horizontally forward, backward, left, and right, respectively. Panning can also be done with the mouse by double-clicking near the sides of your screen. To control viewing distance/height, the page-up and page-down keys (or "+" and "-" if you prefer) are used. Note that on laptop keyboards, you may need to hold down the fn key to access the page-up and page-down keys. The viewing distance/height can also be changed by dragging the mouse while holding down [option] on the keyboard. And the "Z" key can be used to zoom in/out or zip around to different parts of the engine/caboose.

Each time you press-and-release most 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 that 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. 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 performing most of the view modifications described above, the view change will be 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 the view modification keys (excluding "E", "S", "D", & "F"), 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 slowly start spinning to the left and will continue spinning. Pressing option+left again will increase the spin speed, 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.

RAILMODELLER COMPATIBILITY

Introduction

It is now possible to export your RailModeller v4.x layouts as "SLIF" files and load them into iRunTrains. Note that this feature is still considered "experimental", since it is not yet 100% reliable and has several known limitations. The rest of this section describes this new capability, how to use it, and how to avoid problems. If you encounter issues not described here, please let us know (using our web site Contacts page) so we can fix those issues. Thank you.

Importing Your RailModeller Layouts

Loading a RailModeller layout into iRunTrains is a simple 3-step process:

1) Prepare your RailModeller layout by deleting unwanted tracks and making sure that all your track sections are properly joined. Please review the Avoiding Potential Problems section below for more detail.
2) In RailModeller, select File -> Export SLIF to save your layout's SLIF file in the iRunTrains SLIF folder, which is inside the iRunTrains-Library folder where you installed iRunTrains (usually in your Applications folder).
3) Restart iRunTrains and select your layout name from the right-click pop-up menu. Then iRunTrains will read your SLIF file and your layout will immediately appear. If not, quit and check the iRunTrains Terminal window for any error messages.

Now you should be able to see your track plan and view it from any angle. If not, please review the sections below on known limitations and troubleshooting. Note that although RailModeller does not (yet) allow you to edit scenery contours, you can force RailModeller scenery to different elevations using stand-alone pieces of track. For example, you can use this technique to create mountains or flat areas in the scenery. For this reason, iRunTrains will completely ignore all stand-alone (both ends un-joined) pieces of track, since it assumes you were just using them to manipulate the RailModeller scenery.

You can also use the right-click menu to change the way your SLIF file is displayed (colors, textures and whether it is displayed as a table, an island surrounded by water, a valley, a valley containing lakes, etc). If you do choose to display water in the scene, you can use the "L" key to change the level of the water. Upper case "L" to raise the water, and lower case "L" to lower the water. Note that none of these changes can (yet) be saved ... they will all return to their default values the next time you load your SLIF file.

Adding and Removing Trains

So now you're looking at your track-plan in iRunTrains, but it has no trains on it. Why? Well, iRunTrains doesn't recognize your track-plan, so it doesn't know where to put the trains. Fortunately, you can easily add the same three trains which load automatically on our bundled track plans.

The "N" key is used to add the currently selected train (either 1, 2, or 3) to your track-plan. Important: The trains will always be added on the track section that is closest to where you are looking. This usually works best viewing from above using the Manual Table View. First use shift-drag with your mouse to look at the location where the train should go, then press "N". That's all there is to it.

If the added train is facing the wrong direction, you can remove it by pressing Option+Delete, then add it in reverse by pressing Shift+"N" (upper case) instead of just "N" (lower case). Once the train is added, you can drive it the way you normally would. If your new train is accidentally hanging off the end of a siding, simply drive it back on. Sorry, but you must re-add the trains each time you load your SLIF layouts, since iRunTrains cannot (yet) remember their location on your layouts.

Avoiding Potential Problems

Following the tips below should allow your RailModeller layouts to load in iRunTrains with a minimum of problems.

Most of the time, you should export SLIF files using RailModeller's default standard resolution setting. The higher-resolution option looks slightly better, but it quadruples the amount of scenery data. On larger layouts, this can result in memory limitations and jerky animation due to frame-rate performance limitations.
Verify that all intended RailModeller track segments are joined. In iRunTrains, any non-joined section will render with red "bumpers" shown at the non-joined ends. Normally these are only seen at the ends of sidings, so if you see red bumpers where you don't expect them, it means something at that location is not properly joined. If so, correct the track plan in Railmodeller, then re-export your SLIF file and try again.
In most non-simple layouts, it is usually not possible to perfectly join all track sections. There will be some small gaps. Although iRunTrains will usually close such gaps (up to 4 cm) automatically, this works best if you position these gaps between two straight track sections. So if you must leave gaps, position the gaps between longer straight (not flex) track sections if possible.
Turnouts have one extra requirement. Be certain that all legs of each turnout are properly joined to adjacent track sections with no gaps. Otherwise, these gaps may make it impossible to switch those turnouts.

Known Limitations and Troubleshooting

The ability to import your own SLIF files is only support on the Macintosh, not the iPad or iPhone since their memory resources are too limiting.
In iRunTrains, the trains and track are roughly equivalent to On30 rolling stock running on HO gauge track, and there is currently no way (yet) to change this. So although you can import any scale layout, scales that are significantly larger or smaller will not look to scale. A future release will correct this limitation.
If you load your own SLIF file, it will not contain any structures (loading docks, buildings, bridges, etc) such as those seen on our bundled layouts. For now, you will only see scenery, the track, and the trains.
Turntable operation is not supported at all, but any track sections that make up the turntable will be displayed.
If you contact us for assistance, please be prepared to email us your RailModeller track plan file (not SLIF file), since we will probably need it for debugging. We promise not to use, sell, or share your track plans.