DSF X-Plane Integration Reference

Revision History:
	 2/ 4/09   Updated for X-Plane 930
	12/26/07   Updated For X-Plane 900
	 7/25/07   Initial Draft

This document outlines how the DSF file format is used by X-Plane. DSF is a container format - new features can be added to the X-Plane scenery system without changing the file format. This document lists the different legal DSF configurations that X-Plane understands.

Note: this document is a low level reference, intended for programmers who intend to create tools to edit DSF files. Authors who want to edit DSFs should simply use higher level tools like OverlayEditor, or PhotoSceneryX.

DSF Properties

DSF contains a series of properties, with string values. These are the properties X-Plane recognizes:

Bounding Box and Location Properties

All DSFs must contain four properties indicating the bounds of the DSF tile. These bounds are in degrees and must be integers. DSFs should contain a planet tag, which is optional, and assumed to be earth if missing.

Property NameDefaultValue
sim/north(Required)degrees
sim/south(Required)degrees
sim/east(Required)degrees
sim/west(Required)degrees
sim/planetearthearth|mars

Object Density Control Properties

X-Plane only loads part of the facades and objects in a DSF, based on the "number of objects" setting. The "require" properties force X-Plane to load certain objects. Each require statement applies to either facades or objects, and specifies both the minimum setting where the objects are guaranteed loaded and the minimum index within the DSF of the object/facade it applies to.

More than one requirement statement can be used; all are combined together to meet all requirement constraints. Thus you can bring in objects incrementally through proper organization of the DSF object definition order.

Property NameValue
sim/require_objectobj_level/first_required_index
sim/require_facadeobj_level/first_required_index

Overlay Properties

The overlay properties control how a DSF is used as an overlay to other DSF files. The overlay property signals to X-Plane that the DSF should be loaded as an overlay and not a base mesh.

The exclude properties cause X-Plane to eliminate scenery from lower priority DSFs that are loaded underneath the overlay. Each exclusion zone is a rectangle specified in latitude and longitude. A DSF may contain multiple exclusion zones of the same type, and they may overlap.

Property NameValue
sim/overlay0|1
sim/exclude_objwest/south/east/north
sim/exclude_facwest/south/east/north
sim/exclude_forwest/south/east/north
sim/exclude_bchwest/south/east/north
sim/exclude_netwest/south/east/north
sim/exclude_linwest/south/east/north
sim/exclude_polwest/south/east/north
sim/exclude_strwest/south/east/north

The quality of culling depends on the type of scenery being excluded. In some cases, culling may over-remove or under-remove scenery.

[X-PLANE 9] X-Plane 9 improves the quality of forest exclusion - while X-Plane 8 forest exclusions remove a forest polygon if any vertex is in the exclusion zone, X-Plane 9 forest exclusion zones exclude on a per-tree basis for more precise cuts.

LOD Properties

[X-Plane 930:] Historically, X-Plane measures the distance of a mesh patch based on an arbitrary center point computed from the geomerty. Since two different LOD mesh patches may have different vertices, their centers will be different. This cannot be predicted by authors. So for example, if a first patch has an LOD of 0 -> 20000 ad the second one has 20000 -> -1, the first mesh patch may not disappear when the second one appears because they are being measured using different center points.

Setting the property sim/lod_mesh to 1 changes X-Plane's behavior in the following way: the center point for LOD calculations of a mesh patch with a non-zero LOD start value will be taken from the previous mesh patch in the commadn stream.

This in turn means that a series of consecutive mesh patches with increasing LODs (starting at 0) will all have the same center point, and can be switched between using consecutive LOD values. (Also note that when this option is used, the closest LOD must come first, to establish the center point!

Other Properties

For historical reasons X-Plane will only flatten a terrain mesh if these properties are present.

Property NameValue
sim/creation_agentX-Plane Scenery Creator 0.9
sim/internal_revision0

Mesh Types and Coordinate Organization

X-Plane uses .ter files to specify the way mesh patches are drawn. The coordinate organization is:

  1. Longitude
  2. Latitude
  3. Elevation
  4. Normal - X
  5. Normal - Z
  6. Additional Coordinates...

.ter files may contain "border" textures - the border feature of a .ter file is only used if the overlay flag is set in the mesh patch.

Mesh normals: the normal vector is stored as the X and Z ratio of the normal vector, basde on a coordinate system of Y = up and Z = north at the mesh point's location.

Additional coordinates are ordered optionally S1, T1, then optionaly S2, T2. If an odd coordinate is provided, it is treated as alpha. If an alpha is needed but not present, X-Plane generates one using seeded random numbers.

Base Texture is ProjectedComposite Texture Is ProjectedBorder+Overlay FlagST1 ControlsST2 Controls
nononobase-
nonoyesbaseborder
noyesnobase-
noyesyesbaseborder
yesnonobase-
yesnoyesbaseborder
yesyesno--
yesyesyesborder-

X-Plane 8 does not use the alpha channel right now that a DSF may have.

Water terrain ("water" as a patch definition file) uses no ST or alpha coordinates.

Object Types and Coordinate Organization

Objects are placed with three coordinate values:

  1. Longitude
  2. Latitude
  3. Heading

Polygon Types and Coordinate Organization

Only one beach .bch definition may be used per DSF. Subtypes within the beach are used to create variety.

X-Plane uses a number of graphic resource files for DSF polygons. The meaning of the coordinates varies based on the type.

File TypeHoles Allowed?Parameter MeaningCoordinates
FacadeNoHeight (meters)LonLat
ForestYesDensity (0-255)LonLat
BeachNo0=chain,1=ringLonLatElevationdxdzsubtype
LineNo0=chain,1=ringLonLat
LonLatCtrl LonCtrl Lat
StringNoSpacing (meters)LonLat
LonLatCtrl LonCtrl Lat
Draped PolygonYesTexture HeadingLonLat
LonLatCtrl LonCtrl Lat
65535LonLatST
LonLatCtrl LonCtrl LatSTCtrl SCtrl T

For forests, the density is a scaling factor - 255 makes the maximum number of trees, 0 makes none. This control is mulitplied by the rendering settings to set a final number of trees. Tree density will not exceed the maximum possible density from the .for file.

For beaches, the parameter can specify a ring, which connects the end point to the beginning - this will create a correct texture transisition from the end to the beginning. The dx and dz coordinates for the beaches are a normal vector, similar to a DSF's normal vector, and are used for draping the beach. The subtype parameter is an integral subtype which describes which beach from within the .bch file is used.

For draped lines (.lin), object strings (.str) and draped polygons (.pol) if bezier coordinates are present, then bezeir curves are generated.

For object strings, the spacing of objects is controlled by the polygon parameter. For draped lines, the polygon may be treated as a ring or chain - like beaches, best results come from using the ring feature rather than duplicating the first point. For a draped polygon, texture coordinates (ST from 0 to 1) may also be included - the parameter value 65535 indicates this.

Road Types and Coordinate Organization

Only one road.net definition may be used per DSF. Subtypes within the road file are used to create variety.

Road network files use 7 coordinates. The last 3 are optional (used only for bezier roads). Note: x-Plane does not yet visualize bezier roads -- while the DSF spec and X-Plane's usage of it call for bezier curves, the control points are ignored as of X-Plane 860.

  1. Longitude
  2. Latitude
  3. Elevation
  4. Junction ID
  5. Control Longitude
  6. Control Latitude
  7. Control Elevation

Road segments are connected via junction IDs with the following rules:

  • The DSF file's junction IDs must start at 1 and contain no gaps. 0 is reserved as the "no junction" flag.
  • A road chain must start and end with a junction.
  • A junction must be used any time an intersection is desired.
  • A junction must be used any time a road chain changes subtype.
  • All nodes that share the same junction code must share the same coordinates.
  • A junction should not be used for nodes that are designed only to change the path of a road ("shape" points), because the processing overhead is higher for junctions.

Overlay DSF Restrictions

DSF overlays have restrictions on the types of files they may use:

  • [X-Plane 8] Road networks are not allowed in overlays.
  • Mesh patches are not allowed in overlays.

X-PLANE 9 relaxes the road network rule - in X-Plane 9 a DSF overlay may contain a road network, but the one-.net-per-DSF rule still holds. When a DSF overlay has a road network and the base mesh does too, the junction IDs between the two do not connect.

Guidelines for DSF Extension

  • Consider all properties starting with "sim/" as reserved.
  • Do not add extra coordinates to vertices beyond what is in this spec.