X-Plane 8 High Level Scenery System Overview

	Revision History
		8/5/05 - Initial Draft.

NOTICE: I am looking for someone to help revise and flush out this document and make it more human readable!


The X-Plane scenery system is responsible for drawing a lot of what 
the user sees out the window when flying.  The scenery system is
responsible for:

-Drawing the ground.
-Drawing all of the objects that appear on the ground.
-Drawing airports.

The scenery system is not responsible for:
-Drawing the sky, clouds and weather.
-Drawing the planet as seen from orbit.

Possible illustration: a picture of the globe with all elements (sky, terrain, airports, planet) picked out
individually.

BASICS

This document explains the elements of completed x-Plane scenery as X-Plane users receive it.  The tools you use to make
scenery utilize a number of other file formats that are not described here.  Once you determine which tools you will
use to create scenery, that will decide which "editing" file formats you work in; this document describes "distribution"
file formats and directory structure.

To use an analog, if you are creating an image, you might work in photoshop and save it as a .psd with many layers.
The PSD file is big and is good because it has layer information etc.  When you are done, you would "Save As..." a
PNG file, which would create a single compressed flattened image for distribution.  PSD is the editing format and 
PNG is the distribution format.  

(Note that this is a one-way trip - even if you open the PNG and save it as PSD, you
will not get your layers back!  Similarly, when you use tools to make x-plane scenery, some of the information
in the tools may be lost when it is turned into x-plane scenery.  Therefore you should always save your work in
progress (e.g. your original 3-d models in the format your modeler uses natively, textures in photoshop format,
original elevation data, etc.)

X-Plane divides the earth into 64800 (180x360) 1x1 degree "tiles", bounded by latitude and longitude lines.
At any one time, when close to the ground, X-Plane loads six tiles and draws them to form the earth as the user sees it.
(When in orbit, X-Plane does not draw tiles, but rather draws a general picture of the whole planet.)  A number of files
control how each tile is drawn.

Possible illustration: earth with tiles illustrated.

X-Plane uses three basic types of files:

- DSF and ENV files define a single tile.  We will explain DSF and ENV later, but for now the important thing is that
  there is one file that defines each tile.  DSF and ENV tiles have names like +43-118.dsf...these numbers tell X-Plane
  which tile it is.
- Tile files then refer to graphic resource files (images like .png files and 3-d models like OBJ files) that help
  refine how the tile should look.  For example if an ENV contains a house, the house's shape is not contained in the
  ENV file but rather is contained in a graphic resource file (an OBJ or 3-d model) that the ENV then references.
- A few special control files are occaisionally needed; they will be explained below.

Note that one tile can use many graphic resources, and many tiles can use the same graphic resources.  In this sense
the graphic resource files can be shared and recycled.  If you have a house file (a graphic resource), then many of your
tiles can use this house.

The scenery files come in "packages".  A package is basically a directory full of related scenery files; the goal 
of packages is to make it easy to add new scenery by keeping all tiles and graphic resources together.

Airports are drawn on top of tiles based on the contents of two text files: apt.dat, nav.dat, that define the airport 
runway layouts and nav data.  There is one apt.dat and nav.dat file for the entire world.  It does not live in a
scenery package, but rather in the X-Plane resources folder.  It ships with x-plane.

TILE BASICS

Each tile file describes a single one x one degree area of scenery.  The tile's name is based on the latitude and
longitude of the lower left corner of the tile.  Positive numbers mean north or east, negative south or west.
Tiles on the international date line should have a west coordinate of -180, not +180.  Examples:

File				Bounds
+04+118.env			118E, 119 E,  4N,  5N
+40-072.env			 72W,  71 W, 40N, 41N
-35+005.dsf			  5E,   6 E, 35S, 34S
-90-180.env			180W, 179W,  90S, 89S

Tile files can be in one of two formats: ENV ("ENVironment" files) are the old tile format supported by X-Plane 6,
X-Plane 7, and X-Plane 8.  "DSF" (Distribution Scenery Format") is the new tile format supported only by X-Plane 8.

Both ENVs and DSFs cover a 1x1 area with terrain and 3-d stuff, but DSF allows a lot more control over the shape of
terrain, detailed water bodies, and more variety of objects and roads.  DSF files can contain a lot more detail than
ENV files.

This document only describes the X-Plane 8 scenery system; X-Plane 8 can read X-Plane 7 scenery, but if you follow
the guidelines from this document, your scenery will only work in X-Plane 8, even if you use ENVs.

Each tile contains a "mesh" - a surface of 3-d triangles that fully covers the 1x1 area.  The mesh defines the shape
of mountains and valleys.  The mesh also contains information on how it looks (how it is "textured").  This in turn
defines what part o the world appears to be a city, farm, lake, etc.  

Possible illustration: mesh with objects dropped in over it.

The textures used for a mesh can be general images of trees and grass, or actual photos of real-world cities...h
ow you texture is totally up to you.  However most texturing comes in two catagories these days:
 
 - "Photorealistic" texturing involves using photos of the real-world terrain.  The ground looks exactly like the
   real world.  This scheme can be highly accurate but can lack detail due to RAM limitations.  Also getting photos
   can be difficult for some parts of the world.
 - "Landuse" texturing invovles using a basic texture of forest for wooded areas, buildings for a city, etc. and using
   the textures over and over depending on what is in a given area.  This technique uses very few textures, so the
   textures can be very detailed without using a lot of RAM.  But the textures are approximations of what is on
   the ground, not the exact image.
   
Possible illustration: landuse vs. orthophoto texturing

The details of how the textures on the mesh look are controlled by terrain files, which are described below.

On top of the mesh a tile can also indicate 3-d "stuff": objects, forests, roads, facades, and beaches.  Each of
these kinds of 3-d stuff has a text file, described below.  This provides a way to place real 3-d models
on the terrain mesh.  For example, you could make a 3-d model of your local airport and place it on the mesh.
3-d stuff usually looks better than the mesh up close, but can slow down framerate.

Often scenery packages combine a 2-d mesh and 3-d stuff.  For example, the mesh might contain a photo of an airport
but then the terminals might be built in 3-d.

SCENERY PACKAGING AND FILE ORGANIZATION

Tile files live in a folder based on groups of 10x10 files...the naming convention is similar to the tiles; each
tile folder is named after the southwest coordinate of the folder.  Examples:

File			Folder
+42-072.env		+40-080
+40+002.env		+40+000
+32-080.env		+30-080
-29-041.env		-30-050

In your package, you will have a folder called "Earth nav data".  This in turn contains the tile folders, which contain
the tile files.  Each tile folder can have at most 100 tile files, but you do not have to put this many in; any tile can
be or not be in any scenery package.

X-System
  Custom Scenery
     My great scenery package
        Earth nav data
           +40-080
              +42-072.env
              +42-071.dsf
           +30-120
              +32-118.dsf

Possible illustration: folder view on one side, arrows point out parts of the earth on antoher

Scenery packages can have any name and live in the 'custom scenery package' folder.  They are prioritized alphabetically.

On startup X-plane finds all of the installed packages; when it needs a tile, it looks in every package for that tile,
alphabetically.  Only one tile file is ever loaded for a tile; they are never merged.  If no tile file is found, the
tile is filled with water.  (For this reason, no tile files are needed for the huge parts of the earth covered with water.)

So if two scenery packages cover the same tile areas, the higher priority one will 'replace' the tiles in the lower priority one.
An example:

X-System
  Custom Scenery
    Boston
      Earth nav data
        +40-080
          +42-072.env
    New England
      Earth nav data
        +40-080
          +40-071.dsf
          +40-072.dsf
          +40-073.dsf
          +40-074.dsf
          +41-071.dsf
          +41-072.dsf
          +41-073.dsf
          +41-074.dsf
          +42-071.dsf
          +42-072.dsf
          +42-073.dsf
          +42-074.dsf

In this example most of the area will be covered with DSFs from the New England, but the Boston package will put one
ENV in the middle of the area.

Possible illustration: two folder views (one on each side), pointing to the different tiles on the earth.

When you complete your scenery, you Zip or StuffIt your scenery package.  A user who buys or downloads your package can
then decompress it and drag it into their custom scenery folder - that's all there is to the installation process.

GRAPHIC RESOURCES

Tile files define the overall shape of the world and placement of 3-d "stuff" (which we'll define in more detail soon)
for a single tile.
In addition to your tile files, you will probably need some bitmap files to 'paint' your scenery and perhaps some detailed 
3-d models.  The files that do this are graphic resources.  They are always text or image (BMP or PNG) files.  The text files
will have an extension indicating exactly what they do:

Text files
OBJ - Object...a 3-d model, for example a house, an airport terminal, a statue.
TER - Terrain...properties about a certain terrain, like grass, swamp, or asphalt.
NET - Transportation Network...how to draw roads, powerlines, trains, etc.
FAC - Facade...how to extrude a building according to a floor plan.
FOR - 3-d Forest...information on what trees to plant in a 3-d forset.
BCH - Beach...how to add textures to beaches.

Image files
PNG - Portable Network Graphics..a single image.
BMP - Windows BitMaP... a single image.

Basically each of the text files provides the details about how to draw certain parts of your scenery.  The tile files
refer to these "definition" files.  So a tile would just say "highway" or "house" and a NET or OBJ file would tell
X-Plane _how_ to draw the highway or house.  (This allows for recycling.  There are tens of thousands of tile files
but the highway definitions need only be provided once.)

Text files can go anywhere in your scenery package; if you put them in a subdirectory, you must specify this directory
name in the tile file.  Image files go in the same directory as the text files that reference them. 

X-System/
  Custom Scenery/
    Logan Airport Scenery Package/
      Earth nav data/
        +40-080/
          +42-072.dsf
             (inside this file we would reference "jetway.obj", "terminals/terminal_a.obj" and terminals/terminal_b.obj")
    jetway.obj
      (This 3-d model would then reference jetway_tex.png for its texture.)
    jetway_tex.png
    terminals/
      terminal_a.obj
        (this 3-d model would then reference images/a.png)
      terminal_b.obj
        (this 3-d model would then reference brick.png
      brick.png
      images/
        a.png
        
Possible illustration: file system on left, zoom in to "contents" of each file, with arrows pointing back to the other
files in the file system, to illustrate linkage.        

Possible illustration: actual 3-d view of a scenery file, with 3-d elements labeled as to which files provide their defs.

Some things to note here: graphic resources can be anywhere in your scenery package.  Do not put them in the Earth nav data
folder though as this will be confusing.  You can invent your own scheme to organize your files.

Textures can be in the same folder as the resource or in a sub-folder (a.png is one level down from terminal_a.obj in this 
example).

LIBRARY SYSTEM

So far all of the graphic resources you need for your tiles are in your scenery package.  This is the easiest way to set
up your package.  However you can put graphic resources in one package and tiles in another, using the "library system".

The library system lets a package create a 'library' of graphic resources that may be used by any scenery package.  Here
is how it works:


X-System/
  Custom Scenery/
    New England/
      Earth nav data/
        +40-080/
          +42-072.dsf
            (inside this would reerence "lib/houses/red_house.obj")
    Houses Package/
      library.txt
         (contains the line "EXPORT quaint/one_house.obj lib/houses/red_house.obj")
      quaint/
        one_house.obj
          (refers to "wood.png")
        wood.png

In this example we have two packages.  The "houses package" is a library that shares its house; the New England package
uses this house.

Possible illustration: Similar picture as above but with linkage across the library system.

The key to this working is the file library.txt contained directly inside "houses package".  This text file lists 
each object to be shared (on our case "one_house.obj" and its VIRTUAL pathh "lib/houses/red_house.obj".  A virtual
path is a pretend file name that other tile files will use to refer to it.  It is called virtual because while the
tiles think it exists, it does not.  So when +42-072.dsf goes looking for lib/houses/red_house.obj, instead of
looking for a directory called "lib", it actually ends up in the directory "quaint" and gets the object one_house.obj
in a whole different scenery package!  

There are some important things to note here:
 - You do not HAVE to use library files; you only need to use them if you want to share objects with other packages.
 - The real directory and file name of your objects do not have to be the same as the virtual path.  Note how the
   tile thought it would get red_house.obj but got one_house.obj - this is fine!
 - You can share any kind of resource, not just objects.
 - Note that the "New England" never refers to "House package" by name.  A tile file can use a library object without
   knowing where it is coming from.

If X-Plane finds a number of packages sharing the same virtual path, it will pick the highest priority one:

X-System/
  Custom Scenery/
    New England/
      Earth nav data/
        +40-080/
          +42-072.dsf
            (inside this would reerence "lib/houses/red_house.obj")
    Awesome Objects/
      library.txt
         (contains the line "EXPORT brick_house.obj lib/houses/red_house.obj")
      brick_house.obj
        (uses the tex "textures/brick.png")
      textures/
        brick.png
    Houses Package/
      library.txt
         (contains the line "EXPORT quaint/one_house.obj lib/houses/red_house.obj")
      quaint/
        one_house.obj
          (refers to "wood.png")
        wood.png
        
Possible illustration: file system with linakge arrows, but showing competing usage.
 
In this case, since Awesome Objects is prioritized ahead of House Package, the red house in +42-072. would end up
being the brick_house.obj, not the one_house.obj

This demonstrates a very very powerful feature: library files allow you to REPLACE the graphic resource definition
files for a scenery package without modifying the package!  You can create a scenery package and then create a second
package that replaces all of the 3-d models with higher quality versions.  In the section on default scenery, we will
talk more about this.
 
CUSTOMIZING AIRPORTS

You can include additional airport information in your scenrey package by putting an apt.dat file in the Earth nav data folder:

X-System/
  Custom Scenery/
    New England/
      Earth nav data/
        apt.dat.
        +40-080/
          +42-072.dsf
          
Possible illustration: =file system and simple illustration of apt.dat data, with one airport replacing another.

Any airports in this apt.dat will replace the ones x-plane ships with, allowing you to customize an airport.  If an airport
is in many scenery packages, the highest priority airport is used.  

You can custommize an apt.dat _even_ if you do not have a tile file under that airport.  So you can create a scenery package
that only contains a new airport layout.

You cannot customize the nav.dat file. 

DEFAULT X-PLANE SCENERY

X-Plane ships with default scenery.  This scenery takes two forms:

Default scenery tiles.  X-Plane provides simple scenery tiles for the whole world.  These are typically in a package
called "US Scenery" or something.

Default objects and other graphic resources.  X-Plane provides a number of graphic resources by default in scenery
packages.  For example, all of X-Plane's road definitions, basic terrain types, navaid 3-d models, and buildings
are in scenery packages.

All of the graphic resources are in libraries.  The tile files reference these graphic resources using the library system.
This allows you to do two things:

1. You can use any of x-plane's default graphic resources in your own scenery system, by using a virtual path.
2. You can replace any of the objects, terrain, etc. in X-Plane's scenery system by creating your own library
and sharing your own objects using the virtual path that x-plane's default tiles reference.

Possible illustration: before and after, e.g. x-plane default scenerey linkage normally and after custom package is put in
(both a custom package that overrides defs and a custom package that overrides tiles.)

X-Plane's default scenery lives in the folder "Default scenery" which is in the resources folder.  X-plane always
uses custom scenery packages in preference to default scenery packages, so any tiles you provide replace x-plane's
default tiles, and any graphic resources you provide replace x-plane's graphic resources if they have the same
virtual path.

FURTHER READING

In creating your scenery package, you'll need to figure out a few things:

 - What area do I want to work on.  What tiles will this cover?
 - What types of graphic resources do I need for these tiles?  Can I use X-Plane's?
 - What tools will I use to create the tile files?
 - What tools will I use to create the graphic resource files.

This site contains some scenery tools as well as references to other sites.  It also contains documentation
on the file formats.  You will probably not need to read the lowest level most detailed file format information,
but you should read the overview documents for any file type that you will work with!