       //////////////////////////////
      ///  TRANSRAPID TRACK SET  ///
     //////////////////////////////

The TransRapid Track Set is a maglev track replacement set featuring optically
elevated tracks. The track style is based on the tracks at the Transrapid test
facility in Lathen, Emsland, Germany.

Version:  TransRapid Track Set 1.0.0
GRF-ID:   FB FB 02 02
MD5 hash: f7fa6c6ecea645ca788b88555e118f4d  traratrk.grf


0. Contents
===========
1. License Information
2. Background Information
3. Concurrent Set Support
    3.1 Terrain
    3.2 Road
    3.3 Bridges
    3.4 Tunnels
    3.5 Stations
    3.6 Vehicles
4. OpenTTD Railtypes Support
5. Parameter Options
	5.1 First parameter
	5.2 Second parameter
6. Upgrading From Previous Version
7. Credits
8. Frequently Asked Questions
9. Building from source
    9.1 Obtaining the source
    9.2 Dependencies
    9.3 Makefile targets
    9.4 Speed issues
A. Changelog



1. License Information
======================
The TransRapid Track Set is available according to the GNU General Public
License version 2.0. For more information, see the file "license.txt". 

    TransRapid Track Set for OpenTTD and TTDPatch
    Copyright (C) 2010 FooBar

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; version 2 of the License.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License along
    with this program; if not, write to the Free Software Foundation, Inc.,
    51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.



2. Background Information
=========================
The Transrapid system is a German high-speed monorail train system using
magnetic levitation. The tracks in this set are based upon their real life
equivalents at the test facility for the system in Emsland, Germany.

Transrapid is a trademark of ThyssenKrupp Transrapid GmbH.



3. Concurrent Set Support
===============================
In this section compatibility with all kinds of other sets is discussed.

3.1 Terrain
-----------
The TransRapid Track Set has native support for the OpenGFX and TTD base graphic
sets. The OpenGFX graphics style is enabled by default. The TTD graphics style
can be enabled by a parameter setting, see section 5.

3.2 Road
--------
On OpenTTD in combination with the railtypes feature (enabled by default, 
see section 4), the TransRapid Track Set natively supports all road sets.

On TTDPatch and on OpenTTD if you choose to disable the railtypes feature, 
the TransRapid Track Set is only compatible with the default OpenGFX or
TTD roads, depending on your choice of base set compatibility (see section 5).
Support for third party road sets might be added in the future in case there
a demand for such thing.

3.3 Bridges
-----------
The TransRapid Track Set by default replaces the maglev (or monorail) bridges 
with TransRapid bridges. Due to technical limitations, this implies re-defining 
the other default bridges. The TransRapid Track Set is therefore incompatible 
with any other (bridge) set that also re-defines all bridges. If you prefer a 
secondary bridge set over good looking TransRapid bridges, you may choose to 
disable the built-in TransRapid bridges via a parameter setting (see section 5).

3.4 Tunnels
-----------
The TransRapid Track Set by default replaces the maglev (or monorail) tunnels 
with TransRapid tunnels. If this conflicts with other track sets and you prefer 
the secondary track set over good looking TransRapid tunnels, you may choose to 
disable the built-in TransRapid tunnels via a parameter setting (see section 5).

3.5 Stations
------------
The TransRapid Track Set by default replaces the maglev (or monorail) stations 
with TransRapid stations. If this conflicts with other track sets and you prefer 
the secondary track set over good looking TransRapid stations, you may choose to 
disable the built-in TransRapid stations via a parameter setting (see section 5).

The TransRapid Tracks are not compatible with other station sets. You can use 
station sets with TransRapid Tracks, but the optical illusion will be broken.

3.6 Vehicles
------------
The TransRapid Track Set works with any trainset including maglev trains. This
includes the default vehicles. Note that the TransRapid Track Set doesn't come 
with it's own vehicles.

If you find your maglev vehicles running on monorail, you might want to
consider setting the appropriate track type parameter (see section 5). This 
allows you to have the TransRapid Tracks replace the monorail tracks rather 
than the maglev tracks (default behaviour).



4. OpenTTD Railtypes Support
============================
The TransRapid Track Set supports OpenTTD's railtypes feature. Support for this
is automatically enabled in case of OpenTTD r20242 or higher (this includes
OpenTTD 1.0.3). In case of railtypes, the TransRapid Track Set replaces the
tracks with rail type label MGLV. Optionally you can choose to replace the 
rail type with label MONO instead via a parameter setting (see next section).

Additionally, you can choose for the TransRapid tracks not to replace maglev 
or monorail, but rather be added as an additional rail type with label TRPD.
At the moment of writing, there are no vehicle sets that support this rail 
type label, which means you essentially disable the TransRapid tracks.
This option is provided for future compatibility to use different style maglev 
tracks concurrently.



5. Parameter Options
====================
There are two parameters which can be useful. The first parameter controls 
visual aspects of the TransRapid Track Set. The second parameter controls 
technical aspects of the track type.

For OpenTTD r20255 and higher, parameter settings are defined from an ingame GUI.
The information in this section does not apply to OpenTTD r20255 and higher.


5.1 First parameter
-------------------
This parameter controls how the tracks look in the game. The options of this
parameter are listed in the table below. To enable multiple options at the same
time, simply add the values of those options and set this sum as parameter
value.

-------------------------------------------------------------------
|Bit|Value|Enables                                                |
-------------------------------------------------------------------
| 0 |   1 | TTD terrain, tracks and GUI support                   |
| 1 |   2 | -                                                     |
| 2 |   4 | Enable fences                                         |
| 3 |   8 | Disable level crossings (only with OpenTTD railtypes) |
-------------------------------------------------------------------

Example:
If you use the TTD base graphics with fences, set the parameter value to 5 (i.e.
1 + 4).


5.2 Second parameter
--------------------
This parameter controls how the tracks are added to the game. The behaviour of
this parameter depends on the platform used (OpenTTD or TTDPatch) and platform
version. Again, to enable multiple options at the same time, simply add the 
values of those options and set this sum as parameter value.

-------------------------------------------------------------------
|Bit|Value|Enables                                                |
-------------------------------------------------------------------
| 0 |   1 | Replace monorail instead of maglev [A]                |
| 1 |   2 | Add as TRPD railtype instead of replacing [B]         |
| 2 |   4 | Disable railtypes [C]                                 |
| 3 |   8 | Disable TransRapid bridges                            |
| 4 |  10 | Disable TransRapid tunnels                            |
| 5 |  20 | Disable TransRapid stations                           |
-------------------------------------------------------------------

Notes:
Some combinations of settings make no sense and will result in undefined behaviour.
[A] Cannot be used with bit 1 set.
[B] Cannot be used with bit 0 and/or bit 2 set.
[C] Has no effect in TTDPatch and OpenTTD < r20242 (< 1.0.3)

Example:
If you don't want the options of the first parameter, but do want to replace the
monorail tracks with TransRapid Tracks, set parameter value 0 1 (note the
space).



6. Upgrading From Previous Version
==================================
TransRapid Track Set 1.0.0 is compatible with release 0.9.0-beta. If you remove 
the 0.9.0-beta release from your system and have version 1.0.0 in a place where 
the game can find it, it will be automatically selected as compatible NewGRF and 
your existing game will be upgraded with this new version.

If you are upgrading from a very old version of the TransRapid Track Set, you
should disable all previous versions of TransRapid Track Set that you have
active. If you neglect to do so, the newest version of TransRapid Track Set will
disable itself.



7. Credits
==========
Track graphics drawn by:     FooBar
Code written by:             FooBar

The set contains (parts of) graphics by others:
TTD Graphics:                Simon Foster.
OpenGFX Tracks:              Zepyris (Richard Wheeler).
OpenGFX Bridges:             Zimmlock, Thgergo, Purno and Zephyris.
OpenGFX GUI:                 Bubersson and LordAzamath and Zephyris.

The repository contains code by others:
Makefile system:             Ingo von Borstel (aka planetmaker)

Transrapid is a trademark of ThyssenKrupp Transrapid GmbH



8. Frequently Asked Questions
=============================
Q: The colours of the tracks look weird!
A: That's not a question, but if the graphics have a lot of brownish/pinkish
pixels in them, then you are using the DOS version of the base graphics. In
OpenTTD, open the NewGRF configuration window, select the TransRapid Track Set
and use the option to toggle the palette. This will give you the correct
colours. TTDPatch users will have to decode the grf and then recode it using a
palette translation using GRFCodec.

Q: The TransRapid Tracks are not buildable, why is that?
A: The TransRapid Tracks are only availabe if there are TransRapid vehicles
available. The TransRapid Track Set does not come with it's own vehicles.

Q: My TransRapid vehicles are running on some other track than the TransRapid
Tracks, can you fix that?
A: You can easily fix that yourself using the parameter options as described in
section 5, allowing the TransRapid Tracks to replace the monorail tracks.

Q: The bridges/tunnels/stations of some other track type look weird, why is that?
A: The TransRapid tracks are heavily based on an optical illusion. This means that 
it cannot use the default bridges/tunnels/stations for that will break the illusion.
If you rather have the other track type or bridge replacement look good, there are 
parameter settings to disable the TransRapid bridges/tunnels/stations, see section 5.

Q: Where can I ask a question that is not listed here?
A: Feature requests and bug reports go into the TransRapid Track Set Development
topic at TT-Forums.net: http://www.tt-forums.net/viewtopic.php?t=34753.
Compliments and questions about getting the set to work go in the TransRapid
Track Release topic: http://www.tt-forums.net/viewtopic.php?t=45437.



9 Building from source
======================

Usually there's not much which needs to be changed when you obtain the
source. Your friends will usually be
    make
	make install
Both will build the grf from source, the latter will also try to copy
the grf into your grf folder so that it is available for testing and
use straight away.


9.1 Obtaining the source
------------------------

The source code can be obtained from the #openttdcoop DevZone at
    http://dev.openttdcoop.org/projects/transrapidtrackset
or via mercurial checkout
    hg clone http://hg.openttdcoop.org/transrapidtrackset


9.2 Dependencies
----------------

Requirements for running the Makefile successfully:
	grfcodec
    nforenum
	gcc
	md5sum (or md5 on Mac)
	make
    mercurial (recommended)
    python (recommended)

If you want to bundle the grf, you'll need additionally
	tar
	zip
	bzip2
	unix2dos (optional)

Windows only:
On Windows systems this means that you'll need to install MinGW and MSys
in order to obtain a posix compatible environment. Then the makefile can
be called the very same way as it is on linux and mac systems.
MinGW/MSys contain the above mentioned programmes (except NML of course) 
and can be obtained from http://www.mingw.org/ That site also features 
an excellent walk-through on how to install it.0

If you use for OpenTTD data folder a non-default path or Windows with a
non-English localization make sure to copy Makefile.local.sample to
Makefile.local and edit the line with
	INSTALLDIR =
accordingly so that it shows the full path to your OpenTTD data
directory.


9.3 Makefile targets
--------------------

A brief overview over all Makefile targets is given here:

all:
	This is the default target, if also no parameter is given to
	make. It will simply build the grf file, if it needs building

depend:
	Re-run the dependency check. Usually not manually needed.

docs:
	Build the documentation files

bundle:
	This target will create a directory called "<name>-nightly" and
	copy the grf file there and the documentation files, readme.txt,
	changelog.txt and license.txt

bundle_zip
	This will zip the bundle directory into one zip for distribution

bundle_tar
	This will tar the bundle directory into a tar archive for
	distribution or upload to bananas

bundle_src
	Creates a source bundle

install:
	This will create a tar archive (like bundle_tar) and copy it
	into the INSTALLDIR as specified in Makefile.local (or the
	default dir, if that isn't defined). Don't rely on a good
	detection of the default installation directory. It's
	especially bound to fail on windows machines.

distclean:
	This phony target cleans everything from a source bundle which
	wasn't shipped.

clean:
	This phony target will delete all files which this Makefile will
	create

mrproper:
	This phony target will delete also all directories created by
	different Makefile targets

remake:
	It's a shortcut for first cleaning the dir and then making the
	grf anew.

addcheck:
	Check whether there are some files required but not part of the
	repository.

check:
	Check the md5sum of the built newgrf against the supplied md5sum
	(Intended to be used when building from tar balls)


9.4 Speed issues
----------------

A note concerning the speed of the makefile:
It seems that the required tools using MinGW and / or msys are thoroughly
slow on Windows. A few example run times for OpenGFX, same processor type
(both core 2 duo, 2.26GHz for the windows machine, 2.0 GHz for the OSX
machine). Note that the values given are the 'real' time. Even though
this varies more and is dependent on the processor load, that's what you
have to wait for; the 'user' times are quite low on the Windows machine
(~16s), but that by no means reflects the build time. Times are from
OpenGFX r539 with makefile r199.

DEP_CHECK_TYPE         Windows               bash native
                 native       in VM            (OSX)
none            1m23.360s      -             0m32.781s
mdep            1m54.484s   0m30.164s        0m33.807s
normal          2m37.857s      -             0m36.528s



A. Changelog
============
Please refer to changelog.txt.
