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!