Program ZR
==========

Introduction
============

    Program ZR is intended initially to be a GNU version of OpenRails, the open source program based on MSTS (Microsoft Train Simulator), using Mesa/OpenGL and X11 for the 3D graphics and GLUT or SDL2 for the window and user interfaces.  It is written in C.

    The basic design principal is the engineers' KISS (Keep It Simple Stupid).  GNU does not support C#, so as ZR is a bit-shoving program we are limited to C or C++.  ZR started as a C++ project but I was concerned about speed (not helped by some comments in Stroustrup's book) and I was not convinced that the extensions (overtyping etc) were optimal (or needed) for a relatively small project like OpenRails.  So I chose C.

    I have thought about the name and after some thought junked either GLOR or GOR (Gnu-Linux OpenRails or the Great Ocean Railroad), for ZR (Zero Rails).  Zero is the typographical sibling of 'O' and it means that any special names can start with the shorter 'zr' or 'zr_' without possibly confusion with dictionary words.

    At the lowest level the program includes routines to read most, if not all,  OpenRails and MSTS style text, compressed and binary files.  This allows the files describing the landscape, fixed shapes (stations, tracks, buildings, rail crossings, signals, etc.) and wagons (including engines, carriages and freight) to be read and the contents used to generate the display.

    In version 0.6.0 most, if not all, of the basic train operations are animated.  Wheels and engine running gear rotate and move correctly.  Trains can be split and joined.  The settings of junctions can be changed to allow trains to reach any part of the track.  Signals respond to the position of trains and the setting of junctions.  Turntables and water towers are also animated.

    There are compiler options which separately display wagons/engines, shapes and textures.  However the remaining OpenRails code, which includes the detailed dynamics, still has to be converted.

    The program has been developed using the "Great Zig Zag Railway" route available from:
       https://www.zigzag.coalstonewcastle.com.au/
       
       
Version 0.6.4
=============

    The program now includes sound, the later requiring the OpenAL libraries, and forests.  Trackside equipment sounds are missing.
       
Versions 0.6.1-3
================

    These are primarily bugfix versions.  See the files Commit_0.6.# for details.  Version 0.6.3 also contains some changes to the way that the configuration file is processsed.

Version 0.6.0
=============

    The program now animates signals, reading and interpreting the signal script files using software described in the sister github repository ZR_Scripts.
    
    Turntables and transfers (i.e. water towers) are now animated.
    
    Trains can be split (using the F9 key and a mouse click).  Engines, wagons and carriages couple when 'colliding' at slow speed.
    
Version 0.5.1
=============

    Adds moving level crossings and moving points at junctions.
       
Version 0.5.0
=============

    The program now works with the seven standard MSTS routes as well as the Australian "au_great_zig_zag" route.
    
    The program can be compiled and run on 64-bit Windows computers using the SDL2 interface and the MinGW64 package. This contains a Windows compatable set of GNU compilers, include files and libraries. Instructions on installing the required software is given in the document "README.WINDOWS".

Version 0.4.0
=============

    Up to this stage ZR has been developed using glut to interface with the operating system, mainly for handling the graphics window and keyboard.  Version 0.4.0 allows the choice of either glut (freeglut.sourceforge.net) or SDL2 (www.libsdl.org) for the interface.

    In principal there are (or have been) glut packages designed to run on Windows and other systems but SDL2 has the advantage of being much more actively supported.  For the moment ZR will not compile on Windows although this version does contain some changes designed to work with MinGW on Windows (www.mingw-w64.org).

Version 0.3.0
=============

    Version 0.3.0 adds support for one or more trains, each consisting of one or more wagons.  The key combination 'Alt-F7' switches between trains.  Wagon loads are now displayed and the program animates wheel rotation and steam engine running gear.  Trains now stop at end-of-track instead of being reflected.  They also stop when trying to enter a junction from the wrong branch.

    The F1 key toggles a help screen and the F8 key toggles the display of points/switches in front of and behind a train.  Keys '1' to '9' toggle different camera views.

    Display rates can still be low - but will depend on the graphics card being used.  The code includes an option to use vertex arrays for the topography, which should speed things up.  The code also uses viewport clip planes, again to reduce the amount of data processed by the graphics card.

    At this stage of development, the code is likely to contain bugs and hit problems with common misspellings of MSTS tokens - which MSTS and OpenRails either ignore or allow for.  For this reason it is suggested that users first test the code using the zig-zag route, before trying the it out on other routes

Compilation
===========

     The program is designed to be compiled and run from a Linux bash shell. It uses a GNU style makefile to compile the program and the shell command "./zr -p" to run the program.

     More details are given in file "Documents/README.COMPILE".  This also contains information on generating the config file which contains information on the location on the route directory and the other directories needed by the program.

Running the program
===================

    The program starts with the viewpoint showing one of the yards and a engine with three trucks.  You can move around the 3D scene using the arrow keys.  If the "-Dkb_dev" option is used in the makefile, the arrow keys will move the viewpoint forwards, backwards and sideways at the same level.  The keys page-up and page down will move up and down.  The normal steps are 32 m, increased to 1024m if the 'Shift' key is depressed and reduced to 1 m if 'Alt' is depressed.  The arrow keys with 'Ctrl' depressed turn the direction of view to the left, right, up or down in steps of 1 degree. If both 'Ctrl' and 'Shift' are pressed the step is 30 degrees.

    Without the -Dkb_dev option, the behaviour is nearer the standard MSTS behaviour, the arrow keys moving forward and backward but not necessarily at the same level.  In this case the default steps are 1 m (10 m with Shift) and 0.1 degree.

    These values are defined by the variables del_d and del_a in file keyboard.c.

    As with the MSTS keyboard, 'Shift-Z' gives an estimate of frames per second.  The value displayed is an cumulative average over the previous 5 seconds - so it takes 5 seconds to stabilise.

    Keys 'd' and 'a' speed up and slowdown the current train by 1 m/s.
    Key  's' stops the current train.
    Keys 'g' and 'G' change the points in front of and behind the current train.

    Key 'F1' displays a help panel.
    Key 'F8' displays the position of the points/switches in front of and behind the train.
    Key 'Alt-F7' moves the viewpoint and control to the next train.

    The keys '1', '2', '3', '4', '5', '6' and '7' move the viewpoint to positions (mostly) similar to the standard MSTS camera positions.

Other Options
=============

     Main compiler options in makefile:

       #CFLAGS  += -Dsketch_tracks_and_roads
         This option plots the path of railway tracks and road at an additional elevation of 1 meter above the actual path.  This option also provides data on the model index of each section of track.

       #CFLAGS  += -Dgrid_lines
         The generates a rectangular grid, with a spacing of 2048 m, which spans the model region and shows the boundaries of model tiles.  Not all tiles are used, but those that are in use have associated files specifying the topography and the fixed structures within the tile.

       #CFLAGS  += -Dfull_topog
         Because of the time taken to display the contents of each tile, MSTS, OpenRails and ZR usually only display the 9 tiles immediately surrounding the viewpoint - the 9 tiles changing as the viewpoint moves from one tile to the next.  If the comment sign '#' is removed and the program is recompiled, this option displays the full topography.

       CFLAGS  += -Dkb_dev
         Discussed above.

     Three compiler options replace the standard display with either the available set of fixed structures, the set of engines, wagons and carriages or the textures.  These are triggered, by removing the '#' comment tag at the beginning of one of the following lines in the makefile and recompiling the program:
        #CFLAGS  += -D_Display_Shapes #       For fixed structures
        #CFLAGS  += -D_Display_Wagons #       Engines, wagons and carriages, with loads.
        #CFLAGS  += -D_Display_Textures #     Textures
    The 3D figures and 2D textures are displayed on a regular grid.  The names are also displayed.

       CFLAGS  += -Dculling_off_for_wagons
         Solves the problem due to parts of some wagons having the shape triangles ordered clockwise instead of the standard anti-clockwise direction.

       CFLAGS  += --Dzr_freetype
         When using the glut interface this option uses the Freetype libraries for text.  Otherwise the glut text routines are used.

       CFLAGS  += --Duse_vertex_arrays
         Use vertex arrays for topography

     The remaining flags have been used for tests during development of the program.   They should normally not be used.

       CFLAGS  += --Dgeo_coord
       CFLAGS  += --Dtexture_short
       CFLAGS  += --Dnormal_byte


Contributing
============

    Obviously a lot more work is needed.  Most of the software needed to read and decode the MSTS format ascii and binary, compressed and uncompressed files is provided.

    I admit that the organisation of the code needs improvements, it is also not easy to read (also true of OpenRails) and my OpenGL knowledge is still limited to version 2.1.  However despite all of that, I hope that there is enough here to attract other people to develop the project.

    Of course if you just want to take a copy and do your own thing - that's fine.  However if you are interested in collaborating, it would be a good idea to first have a look at the OpenRails code and then let me know of which aspects of the model you would like to develop.

    Three simpler things that currently need development are water, forests and adding texture to topography.  After that it should be primarily about the user interface, the makeup of trains, interaction with track features and better dynamics.

    djw - October 2021