Project ][ -- Trains and Roller Coasters -- Documentation.txt
By: Michael Young -- November 3rd, 2003 -- Computer Science 559

http://cs.wisc.edu/~myoung  --  mgyoung@wisc.edu
http://www.mikesshorts.com  --  mike@mikesshorts.com


This project is a train and rollercoaster graphics program.  See "readme.txt"
for features and credits.

To start the program run "Coaster.exe"

You will then be prompted to input the screen width and height that you would
like to run at.  Input your Windows resolution for a quazi fullscreen display.

The main window will then open.  Hold the right mouse button down and drag the
mouse to rotate around the middle of the board (sky-view).  You can also press
[A] to track your view in, and [Z] to track your view out.

To insert a point on the ground press [M].  The view will be shifted to face
the point, highlighted in yellow, looking down the Z axis.  When it is
highlighted in yellow it can be dragged in the X/Z axis by clicking on the
left mouse button and dragging.  To move it in the Y axis click the right
mouse button and drag up or down.  You can also press [A] and [Z] to zoom in
and out.  If you want a different view of the point that is not straight on
then press [1].  Is best to keep a straight-on view of the board when
modifying the track because the mouse axes are bound to the X/Y/Z axis of the
world.  Moving objects around from a side or back view (a view not looking
down the Z axis) will not be intuitive to the movement.

To deselect all control points press [R].  You can continue to add more
control points by pressing [M] (up to 100 control points in this
implementation).

To select (iterate through) control points to modify, press [Q] until the
control point you want to modify is highlighted in yellow.  Again, [R]
deselects all control points.

To insert a pine tree press [N].  The pine tree can be translated in the same
way as a control point.  Clicking the right mouse button and dragging the
mouse along the Y-axis will shrink/grow the tree.  To iterate through trees
to manipulate, press [E].  To deselect any tree selection, press [R].

Once you have specified more than 2 control points, the track will be drawn
with the train.  Pressing [SPACE] will start/stop the train.  Pressing [1]
will toggle through all of the available train and track views.

As far as train movement is concerned, there are two modes available.  The
default mode is train movement with conservation of energy.  When the track is
created the maximum point on the track is automatically calculated and the
total energy of the train is chosen so that the train will have a slow speed
at that given highest point.  You can specify other values for the total
energy of the train.  To increase the train's energy press [UP] and to
decrease the train's energy press [DOWN].  In the event that the train does
not have enough energy to climb the track, it will be forced to move at a
constant, slow speed until it again has enough energy to begin moving from
its own energy.  The forced constant speed simulates a car pulling mechanism
on a real roller coaster.  To reset the train's energy based on the track's
maximum height press [F4].  To increase the gravitational constant press
[PGUP] and to decrease it press [PGDN].  To restore default speed,
gravitational constant, and train energy press [D].

You can also get statistics on the track and the train's motion at any instant
by pressing [F5].  The statistics are printed in the console window.

The other, admittedly much less exciting, mode of movement is constant speed.
To get constant speed, press [F3], which is the movement mode toggle key.  To
switch back to conservation of energy again, press [F3].  Once you are in
constant speed mode you can press [UP] to increase the speed and [DOWN] to
decrease it.

To enable/disable drawing track supports, rail ties, and parallel tracks,
press [3].

You can specify the track orientation by pressing [W].  That will select the
blue boxes initially located above each red control point created.  The
direction from the red control points (track position) to the blue control
points specify the orientation of the track's up-vector in that part of the
track.  This allows for you to make tracks with barrel rolls and true loops.
Once a blue box is selected (highlighted in yellow) you can move it in exactly
the same way you move a regular control point.  When you are done making a
move press [W] to select the next control point, or press [R] to deselect the
control point.

Lighting can be repositioned by pressing [L].  It is moved in the same fashion
that control points are moved.  To deselect the light movement press [L]
again.  Lighting can also be enabled/disabled by pressing [4].

After you have specified all the track points and the track's orientation you
can disable/enable control points being drawn by pressing [2].

If you want to create a track that has an overpass you can adjust the
distribution of the track support beams that are drawn (so that your train
won't run into the beams).  Press [[] to decrease the support density and
press []] to increase the density.  You can also adjust the train track tie
distribution.  Press [+] to increase the track tie density and press [-] to
decrease the the track tie density.

The whole track can be cleared by pressing [C].

To toggle between the Catmull-Rom spline method and the B-Spline method for
constructing the curve press [B].  Due its smoother ride and better general
behavior, the B-Spline construction method is the program default.

Once you have constructed your track you can save it by pressing [F2].  You
will then be prompted to specify a name.  Be careful as it will overwrite
any file that you specify that already exists.

To load a track that has been saved, press [F1].  Then type in the name
(including path, if necessary) of the file you want to load and click "OK."

Keyboard Commands:

[M]     Create a new control point
[N]     Create a pine tree
[Q]     Select a track position control point for manipulation
[W]     Select a track orientation control point for manipulation
[E]     Select a scenery object for manipulation
[R]     Deselect all control points and scenery objects
[1]     Toggle camera view/control point manipulation view
[2]     Enable/disable control point drawing
[3]     Enable/disable track support drawing
[4]     Enable/disable lights
[F1]    Load a track from file
[F2]    Save the current track to a file
[F3]    Toggle train movement mode
[F4]    Reset the train's default energy
[F5]    Output statistics
[SPACE] Run/stop the train
[B]     Toggle Catmull-Rom/B-Spline curve construction mode
[C]     Clear the current track
[D]     Restore default values
[L]     Select/deselect lighting for manipulation
[A]     Translate the camera forward
[Z]     Translate the camera backward
[+]     Increase track tie distribution
[-]     Decrease track tie distribution
[]]     Increases track support distribution
[[]     Decreases track support distribution
[UP]    Increase the train's energy/speed
[DOWN]  Decrease the train's energy/speed
[PGUP]  Increase the gravitational constant
[PGDN]  Decrease the gravitational constant
