Personal tools

Anatomy of the X-Plane Scenery System

From X-Plane Wiki

Jump to: navigation, search


This is a broad overview of the architecture of X-Plane's scenery system. It provides a road map for authors on how the various components fit together.

Contents

Components of a Scenery Package

  • A scenery package is the folder that contains scenery.
  • An art asset is a texture, mesh, or other definitions used to visualize scenery.
  • A tile defines what is on a small portion of the earth.
  • The library forms a "master list" of all art assets for use in all scenery packages.
  • Airport data defines the layout of one or more airports.

Scenery Packages

In X-Plane, all scenery content comes in a scenery package. A scenery package is a folder with a predefined file organization.

Custom scenery is typically distributed as a single scenery package. A scenery package can contain art assets for the library, tiles, airport data, or any combination of the above.

Scenery packages are installed in the "Custom Scenery" folder. Scenery packages have a priority order, defined by their file name alphabetically; X-Plane also stores the default "global scenery" in packages (stored in the Global Scenery folder) and the sim's built-in art assets are stored in packages in Resources/default scenery. All third party scenery should be packaged and installed in the "Custom Scenery" folder.

See the Scenery Package Organization article for further reading on package files, or see the Expanding X-Plane section of the manual for information on how to download and install a custom scenery package.

Scenery Tiles (DSF)

X-Plane divides the planet into thousands of 1x1 degree "tiles," which are "cut" along latitude and longitude lines. For a given area of the earth, tile files are loaded to build the local contents of the planet. There are two kinds of tiles: base mesh and overlay.

X-Plane normally maps a 3x2 tile region (3 east-west, 2 north-south) to provide about 200x200 km of loaded scenery at any one time.

There are two kinds of tile formats: DSF (distribution scenery format) is the current tile format, supported in X-Plane 8 and 9. ENV (environment file) is the legacy tile format supported in X-Plane 6 and 7 (and supported but deprecated in version 8 and 9). The rest of this article will refer only to DSFs. Any new scenery you create should use DSFs.

Tiles are named by the latitude and longitude of their southwest corner. They live in a folder that defines a 10x10 block of tiles, defined by its southwest corner, and that folder in turn lives in a per-planet folder, which lives in your custom scenery package. Example:

X-Plane Install/

Custom Scenery/
My Awesome Boston Scenery/
Earth nav data/
+40-080/
+42-071.dsf
+42-072.dsf

"My Awesome Boston Scenery" is the name of the package. Note that there can be no sub-folders introduced in this particular layout--layout of DSF tiles is fixed.

DSFs are binary files - they contain the coordinate and location data for a tile but not the art assets. For example, in an orthophoto scenery package--that is, scenery where the ground texture is taken from a real photo--the shape of the mesh (the elevations) will be in the DSF, but the image of the orthophoto will be in separate art asset files.

Tile files can contain:

  • Base mesh triangles (base mesh tiles only).
  • Beach placements, defined by 3-d polygonal outlines of the land-water polygon (base mesh tiles only).
  • Road grids, defined as a connected set of line segments with road type information.
  • Model placements, defined as points and rotations.
  • Facades (that is, buildings extruded from a footprint), defined as a polygonal footprint + height.
  • Forests of trees, defined as a polygonal footprint + density information.
  • Draped polygons, defined by polygon, for overlaying orthophotos or other repeating textures, like pavement.
  • Draped painted lines, defined by a polygon path, typically used for custom taxiway lines, etc.
  • Strings of objects, defined by a path, often used for adding a series of runway lights.

In all cases, the DSF file contains the coordinate location information and a reference to an art asset file that is stored separately.

Base Mesh Tiles

For any given tile, only one tile file can provide the base mesh, or ground. The base mesh is a textured triangle mesh used to model mountains, water, land, etc. Base mesh tiles can also contain all of the components of overlay files if desired.

For further reading, see the DSF File Specification and DSF Usage by X-Plane articles.

Overlay Tiles

A tile file can be marked as an overlay - in this case, its contents are superimposed over other tile files. Overlay files cannot contain any base mesh information. An overlay file is often used to add additional details. For example, an overlay tile could add the buildings of an airport.

Overlay tiles are loaded in priority order. An overlay can contain "exclusion zones", which are lat-lon rectangles that prevent elements of lower-priority tiles from being loaded. For example, if an overlay tile contained placements for custom buildings for Manhattan, the author would also create an exclusion zone around Manhattan that would prevent the default buildings (that ship with X-Plane) from appearing there.

For further reading, see the About Overlays article.

Art Assets and the Library

All art assets are stored in scenery packages, but never directly inside a DSF. Typically an art asset is built from a combination of text files and image files. X-Plane supports DDS, PNG, and BMP; BMP is not recommended. DDS is the preferred format for scenery use. The text files often contain information on how to use the texture and other useful properties. For example, the ".net" file format, which defines a road network, indicates the shape of roads to be built, the physical properties of the roads (e.g., how bumpy they are), how to map the texture to the roads, and where to place cars on those roads.

A quick cheat sheet to art asset file types:

  • .ter - A terrain definition; the file lists physical properties, scaling information, and texture files.
  • .obj - OBJect - that is, a 3-d model/mesh. This is not the same format as an Alias/Wavefront OBJ files.
  • .fac - Facade definition; the file describes how to extrude a building from a footprint using a texture.
  • .for - Forest definition; the file describes how to build trees from a texture for placement within a polyogn.
  • .bch - Beach definition; the file describes how to tile a beach from a texture.
  • .net - Road network definition; the file describes how to build 3-d roads and place traffic for several road types from several textures.
  • .pol - Draped polygon; describes how to texture a polygon that is "draped" over the existing mesh using a texture.
  • .str - Object string; describes how to place a number of OBJ files along a line.
  • .lin - Line; describes how to paint a line along the mesh.

Note that .pol (draped polygons) can be used in an overlay, while .ter (base mesh terrain) can only be used in base meshes. Base mesh performance is significantly faster than draped polygons; draped polygons should only be used to customize small areas of the world, like an airport surface area. These files are not appropriate for large-scale orthophoto scenery!

Art asset "primary" files (e.g. OBJ, FAC, etc) can be in any location within a scenery package--they are defined by relative paths. So you can organize your art assets as desired. The dependent ("secondary") files like DDS textures should be in the same folder as the art asset. An example: X-Plane Install/

Custom Scenery/
My Awesome Boston Scenery/
Earth nav data/
+40-080/
+42-071.dsf (references kbos/hangar.obj)
+42-072.dsf (references bos/fenway.obj)
kbos
hangar.obj (references hangar.dds)
hangar.dds
bos
fenway.obj (references fenway.dds) 
    fenway.dds

In this layout, the .obj files can be moved anywhere within My Awesome Boston Scenery as long as the relative paths in the DSF are adjusted.

Objects

OBJ files are the main way to get 3-d models into X-Plane. They are used for both scenery models (e.g. buildings) and the 3-d visualization of airplanes. An OBJ is a text file, but typically they are edited using a 3-d editor like AC3D or Blender and exported. Objects can be animated, and have a number of specialized features that can be used only in airplanes.

For further reading, see the OBJ Overview and OBJ8 Specification articles.

Polygons

The polygon definitions in a DSF can sometimes have holes and sometimes they can be bezier curves; what is allowed depends on the art asset type. For example, bezier curves are allowed for draped polygons but not facades; holes are allowed for forests but not facades.

For further reading, see the DSF Usage by X-Plane article.

Road Networks

Road networks may be specified in overlay files, but they require MSL elevation (that is, their altitude is predefined). The lack of on-the-fly elevation adjustment for overlay road networks is a problem for making add-on road packs; fixing this limitation is an area of ongoing development.

For further reading, see the NET File Specification article.

Library

The library provides a way to locate art assets by a virtual file system, rather than by the physical file system. The library allows one scenery package to "publish" an art asset (by providing it with a virtual file name in the library) and another scenery pack to use that art asset (by referring to it by its virtual file path).

The library system is useful for a few reasons:

  • It hides the actual layout of art assets from third parties, breaking a dependency. Laminar Research can (and does) rebuild our art assets periodically; this does not affect third parties because we map our assets to the legacy virtual paths.
  • It allows scenery packages to share art resources independently.
  • It allows scenery packages to augment or replace or customize the art assets that ship with X-Plane.
  • It allows a many:many relationship between art assets and usage. For example, we map many car .obj files to one virtual path, allowing for a variety of traffic. We map a particular building to both legacy and current virtual paths, so that we can provide legacy art asset support without having to duplicate the files on disk.

Note that image files are not shared via the library system; instead the text file that references them is shared.

Art assets do not have to be placed into the library system--a package can simply access them by relative file paths. Or, a package can put its art assets into the library and then reference them by virtual path, allowing for customization by other packages.

Art assets are placed in the library by putting a file called "library.txt" into the root of your package, like this: X-Plane Install/

Custom Scenery/
My Awesome Buildings/
library.txt (maps houses/house1.obj to lib/g8/buildings/60_30.obj and houses/house2.obj to lib/g8/buildings/60_30.obj)
houses
house1.obj (references house.dds)
house2.obj (references house.dds)
house.dds

Note that in this case, another scenery package that references houses/house1.obj will not use these files. That is because scenery packages can only use each other's art assets via virtual path. A scenery pack that references "lib/g8/buildings/60_30.obj" (a virtual path) might end up with either house1.obj or house2.obj.

Library files let you specify the replacement semantics for art assets--that is, a library file can provide additional variants of an art asset or replace the art asset completely. Libraries can specify what tiles (in latitude/longitude) can use the art asset for 'regionalization'.

For further reading, see the Tutorial: Airport_Customization, Using the Library System, The X-Plane Library System, Library File Format Specification, and Tutorial: Customizing X-Plane's Default Scenery Artwork articles.

Airport Data

The data that describes the layout of an airport are stored in apt.dat files. Robin Peel maintains the file format and the master database of airports that form the "default" scenery for X-Plane.

There is one apt.dat file per package per planet, like this: X-Plane Install/

Custom Scenery/
My Awesome Boston Scenery/
Earth nav data/
apt.dat

The apt.dat file can contain one or more airports; each one fully replaces the previous airport's definition. (That is, you cannot simply add a runway to the existing KBOS, you must fully re-specify KBOS).

You do not need to provide tiles for the airports you cover, or vice versa.

Airport data does not affect the terrain type below the airport; airports in the default scenery that X-Plane ships have grass underneath them because the base mesh creation process added the grass. If you add a new airport, you may need to include an overlay tile with .pol placements that drape new terrain over the old; X-Plane's art assets for airport grass are all exported into the library for this purpose.

For further reading, see Robin Peel's airport data home page.

Airport vs. DSF overlays

Airport definitions do not use any specific art assets; the file format models airport data and lets X-Plane use built-in art assets to draw.

However, all of the types of drawing that are possible in an airport (pavement, lines, lights) can be created using DSF overlay data. The intention is for authors who want to truly customize the look of their airport to use DSF overlays.

  • .pol files have the same functionality as taxiway and runway pavement.
  • .lin files have the same functionality as taxiway lines.
  • .str files have the same functionality as taxiway lights.
  • .obj files are actually used to build the lights that are placed in an airport--each runway light is actually an OBJ!

Some of X-Plane's art assets for airports are available via the library.

For further reading, see the Advanced Airport Customization article.

Types of Custom Scenery

Here are some examples of scenery add-ons:

  • A customized airport. The package contains OBJs for the various buildings, an apt.dat file with a new layout, and an overlay DSF placing the objects.
  • A new base mesh. The package contains a base mesh DSF and .ter files for the orthophotos. Because of the amount of data required to create a base mesh, this is for advanced scenery authors only.
  • Regionalized Buildings. The package contains only OBJ files for customized buildings and a library.txt file to place them in the library.
Retrieved from "http://wiki.x-plane.com/Anatomy_of_the_X-Plane_Scenery_System"
Navigation