---------------------------------
                       - 128x128 Image Painting How-to -
                       ---------------------------------


This document is intended to help painters to get acquainted with some basic
rules that need to be followed in order to make their images fit well to the
Simutrans game as a whole. It should be compilation of all exiting documents
posted so far.

It has following sections:
* Basic rules and scales
* Allowed properties of buildings
* Coloring rules
* Hints and tips
* How to make .pak
* References
* Appendix


                        Basic rules and scales
                        ----------------------

Overall perspective of Simutrans is isometric, so lines parallel in real world
remain parallel in Simutrans.

In game sun shines from south (bottom left corner of screen) and it is slightly
more than 45° degrees above real ground in game. (to better understand this, you
can look at image called "lighting_example.jpg")

One square represents approximately 20x20 meters, and thus 12 pixels are about 2
meters. This scale applies to buildings, and other terrain objects.

For buildings this means those pixel values:
* A story is about 14 pixels tall. 12 or 16 pixels may be ok for extremely small
  or large buildings. Avoid other heights, this looks *very* strange when
  combined with the existing buildings. Believe me!
* Standard windows usually have a height of 8-10 pixels. (special sized windows
  of course keep appropriate sizes)
* Don't use the whole square for your buildings. When a town is build from
  the buildings it looks better if there are small gaps between the buildings.
  (there can be exceptions from this rule, but be very careful. Rather consult
  it first.)
* Proper shading is vital. Try to look on existing buildings. (there may be few
  errors though.)


Vehicles have slightly different scaling. It is because of their importance for
the player, they cannot be so tiny to fit the standard scale, they are bigger.

Positioning and sizes of trains is shown in file:
"train-align-center-example.png"

To see allowed sizes and positioning of busses and trucks, look at file:
"128x128 Vehicle template.png"

Since this size does not offer enough place to properly scale vehicles of all
sizes, following agreement on pixel length and represented metric length was
made, to ensure that all vehicles fit to each other:

       pixel length in x dimension   =   real length of vehicle in meters
                 30px                =                  15m
                 27px                =                  12m
                 23px                =                  10m
                 20px                =                  8m
                 18px                =                  6m

There is no special agreement on size of ships, but please make your own such,
that it will fit to already existing ships. So small fishing boat surely should
not fill whole square.

Please follow official examples, otherwise your vehicles will not fit into the
game and cannot be officially included!




                        Allowed Properties of Buildings
                        -------------------------------

Simutrans gfx engine poses some restrictions on building sizes and properties:

* Buildings can be animated (currently only buildings)
* City buildings can be only 1x1 square large!
* City buildings need to be placed on standard city pavement manually.
  (industries use browner version)
* There can be more types of city buildings for each level.
* Most of player buildings are limited to 1x1 (stations), post is exception.
* Industries are unlimited in size, but 10x10 industry is really too large.
  They can have base of any rectangular shape, but if you use uneven dimensions
  (like 2x3), it is  necessary to provide arrangements for both possibilities
  (2x3, 3x2).
* Here is a description of factory image:
  BackImage[orientation: 1|0][x][y][z 0..2(for buildings taller than 1
  square)][animation frame]=unix_style_image_path(no .extension).row.column
* Most of buildings can be higher than one square - then frames are put on top
  of each other so the building using two frames can have 256 pixels from top to
  bottom. But don't use too high buildings, two squares are usually way enough.



                                 Coloring Rules
                                 --------------

In 16bit ((5,5,5) + 1special) Simutrans graphic engine you have relatively large
freedom in coloring your images. But you shall keep in mind these few facts:

* In most cases in real world, you will not find large areas of single color so
  try to use shading, texturing and adding noise for larger spaces like walls or
  so. It looks much better.
* Except for some shiny emails, most colors are not fully saturated, eg. 255 0 0
  color can look ok on picture of new Porshe, but will be very strange on a
  roof, even if it is painted metal roof!
* _there are reserved colors_ with special behaviors, use them where it is
  appropriate, avoid them on places where they are not wanted. Special colors
  are these (all are 8bit per channel precise!):
* To see full list of reserved colors, look at the file:
  "palette - reserved colors.png"
* The most important special color is:
  transparency key: R231 G255 B255 (cannot be seen in game)

It is important to check your images for unwanted occurrence of those colors!!!!
Recommended way of creating of image is to create it as it is, without keeping
reserved colors in mind - then scan it for occurrence of these colors and
eliminate them. AND THEN add them on places where they are wanted.



                                 Hints and Tips
                                 --------------

* Download image set, so you can have all images stand alone and get inspired
  in terms of sizes and scales, and also see what we are missing.
* Again be careful with scaling, improperly scaled images are nice by themselves
  but cannot be put into the game; there can be no exceptions!
* Try to benefit from 16bit color engine - use variety of colors, use shading,
  use light noise, all that makes images more real. But be careful with that,
  too much is worse than too little.
* Don't hesitate to use special colors on windows, on lights, on sidewalks under
  the lights, it looks neatly in the night.
* You can upgrade an old image or create brand new one, you can choose freely.
* Generally there are some old images in the image set, still in 256color
  paletted fashion, these shall be first ones on rework list.



                   How to make .pak file from image (example)
                   ------------------------------------------

* This section has been removed. Many superior examples can be found at:
  http://www.simugraph.com/forum/viewtopic.php?id=12&t_id=3

* Be careful, dat files vary quite bit between different building types, so if
  you want to crate for example city building, try to obtain some dat file of
  existing city building, so you will see what you need to put in. :-)

* As you can see png files usually contain more images and have a structure of
  matrix (square width is 128x128) with more separate images. Then position of
  the image in this matrix is given by mentioned coordinates. You can also use
  separate files for each image, then coordinates are always .0.0




                                   References
                                   ----------

-Painting rules
-Painting rules 16
   all created by Hj. Malthaner
-Object documentation
 http://groups.yahoo.com/group/simu_gfx/files/SimObjects/SimObjects.txt
   Volker
-Images
   of various authors.



                                    Appendix
                                    --------

This text had been written by:
Tomas Kubes

05-Jan-2003

updated:
18-Feb-2003 - Minor language updates.
01-Sep-2003 - Now Howto reflects all rules for images for 128x128 Simutrans.