###### HOW TUG LIVERIES WORK ######

Each tug contains a "liveries" folder, which contains one or more
".livery" subfolders, e.g.:

+ AST-3F.tug
  + liveries
    + generic.livery
    + LEOS.livery
    + Swissport.livery

A livery can consist of up to three PNG files:

1) the standard (base) texture file
2) the "LIT" (night lighting) texture file
3) the "NORMAL" (normal map and material properties) texture file

Unless you're going for something very special, you only ever need to
repaint the standard texture and not the LIT or NORMAL texture.

The "generic.livery" folder is special. It contains all the default
textures of the tug. If a texture isn't found in the appropriate livery
folder, it is fetched from the "generic.livery". This is so that you
don't have to copy the same LIT and NORMAL textures into every livery,
which saves on a lot of disk space.

The exact names of the texture files are hard-coded in OBJ file and
shouldn't be changed in the livery. So in the above example, the texture
files in the livery folders would something like this:

+ AST-3F.tug
  + liveries
    + generic.livery
      - AST-3F_tex.png		# default base texture
      - AST-3F_lit.png		# default night lighting texture
      - AST-3F_norm.png		# default normal map texture
    + LEOS.livery
      - AST-3F_tex.png		# LEOS-specific repaint of the base texture
    + Swissport.livery
      - AST-3F_tex.png		# Swisport-specific repaint of the base texture

When contributing liveries to the BetterPushback project, please submit
your repaints in PNG or XCF format, as pretty soon we will be jettisoning
DDS textures because of their huge size and migrating to PNG textures in
the shipped plugin.

### HOW LIVERIES ARE SELECTED AT RUNTIME ###

When a tug is called, BetterPushback asks X-Plane what the currently
nearest airport is to the aircraft (presumably that's the one we're
located at) and determines its four-letter ICAO identifier. It then
proceeds to select a tug. The exact details of the tug selection
algorithm are beyond the scope of this short writeup. Once a tug is
selected, BP selects a livery for the tug.

To select a livery, BP enumerates the liveries (folders ending in
'.livery') inside the "liveries" subfolder in the tug. Each '.livery'
folder MUST contain a special "info.cfg" file which tells BP where that
livery should be used ("generic.livery" is special in that it contains
no "info.cfg", because it is the default fallback for when no other
livery was found).

The "info.cfg" file is a simple text file that looks something like this:

	### This is a comment - BP ignores what's on this line
	#
	# The keyword "icao" specifies that an ICAO selector follows.
	# BP matches this against the airport the aircraft is currently
	# at. Please note that the quotes around the value are mandatory.
	icao "EDDF"

	# To allow for more flexible selection rules, BP allows you to
	# provide an arbitrary Perl-style regular expression as the
	# match rule:
	icao "LS[A-Z]{2}"
	# The above rule matches any airport with an ICAO code of
	# "LSxx" where 'x' is any capital letter from A-Z.

	# You can provide as many icao keywords in a single info.cfg file.
	# It's enough if one matches.
	icao "EDDV"
	icao "EDDM"
	icao "EDDL"

	# You can construct matches based on the aircraft's livery name.
	# See below for more information airline livery matching.
	airline  "\\bDLH\\b"
	airlinei "Lufthansa"	# same as "airline", but case-insensitive

You can get as creative with the regular expression as you like. Please
note that when BP asks X-Plane what the nearest airport is, it can't
filter out tiny airports or heliports that might be closer to the
aircraft if the airport premises are particularly large. In those cases
you should add the neighboring airport to the "info.cfg" to make sure
there aren't dead spots on the major airport where your livery won't be
applied because of this quirk. A good look at the sectional charts should
reveal to you if this could happen to you.

If multiple liveries match the airport, BP randomly picks one. This can
be annoying while painting the livery if there are multiple 3rd-party
ones which match. Section "HOW TO TEST LIVERIES" on how to force BP to
pick your livery over any other.

### AIRLINE LIVERIES ###

If you provide an "airline" or "airlinei" specifier in the info.cfg, BP
considers the livery to be airline-specific. This has a number of effects
on its selection criteria:

1) If the aircraft is NOT an airliner (see "What's an airliner?" for
   details on how airliners are detected), the tug livery is ignored.
2) If the aircraft is an airliner, but its livery name doesn't match any
   of the "airline" or "airlinei" match commands in the info.cfg file, the
   tug livery is ignored.
3) Rules #1 and #2 may be overridden by specifying an "airline_opt" command
   in the info.cfg file. In that case, if either rule #1 or #2 applies AND
   an "airline_opt" command is present, the livery is NOT ignored by BP,
   but it is moved to the tail of the list of candidate liveries. This
   means if ther are any non-airline tug liveries, they are preferred over
   any airline liveries.

The regular expression match for the "airline" or "airlinei" commands are
applied in the same fashion as "icao" - if any part of the livery name
(as stored under the "liveries" folder of the aircraft model) matches,
the match is considered a success. Please be sure to use a sufficiently
specific match rule to avoid embarrassing situations such as pushing back
a competitor airline's aircraft!

### HOW TO TEST LIVERIES ###

Create a new ".livery" subfolder in the tug of your choice, put in your
texture file in PNG format and write an "info.cfg" text file using the
rules outlined above. Please note that you DON'T have to restart X-Plane
when you make alterations to your livery. Simply restart the pushback
operation. BP reloads all the livery configuration and texture files when
starting a new pushback. Binding a key to the "connect first" and "stop
pushback" commands is particularly useful for this case, as it allows you
to quickly force BP to reload the tug over and over.

If you don't want to write an "icao" list just yet, or if multiple
existing liveries match your airport and you don't want to randomly cycle
through them each time you want to test your livery, you can put this
line:

	paint_debug

at the start of your info.cfg. This forces BP to always pick your livery,
irrespective of the presence of any other livery that might match, or
even irrespective if a match "icao" specifier is present.

When you are ready to write your "icao" and "airline" lines and wish to
use a more complex regular expression selector, it can be helpful to know
whether your selector matches correctly. You can put this line:

	match_debug

at the start of your info.cfg. This makes BP print a short diagnostic
message in X-Plane's Log.txt for each match attempt that follows.

Obviously when shipping your livery, be sure to remove any "paint_debug"
or "match_debug" lines.
