topic: Scenery

Painted Line (.lin) File Format Specification

Painted line files (.lin) define taxiway markings that can be draped over DSFs, although they could can be used for other purposes too.

Painted line files are standard X-Plane 8 text files starting with a header and then commands. The # defines a comment.

A
850
LINE_PAINT

Painted lines are defining polygons in the DSF file. The polygon may have windings – only lat and lon coordinates are needed. The polygon parameter is used to indicate a closed loop (1) or open chain (0).

If two coordinates are provided (lon, lat) then the line is made of line segments. But if it is made of four coordinates (lon, lat, control lon, control lat) then it is interpretted as bezier curves.

The commands define the line:

TEXTURE <texture>

The texture command specifies the texture to be used for the painted lines. It is located relative to the .lin file. Night lighting is not available for painted lines.

SCALE <horizontal> <vertical>

The scale command defines how large the texture is in meters when applied. The parameters are in meters and represent the size of the entire texture.

TEX_WIDTH <pixels>

The horizontal coordinates are specified in terms of a texture of this width. In other words, this defines the scale in which horizontal coordinates are specified. So if your TEX_WIDTH is 1024, your middle pixel is 512, even if your whole texture size is only 16 pixels wide.

S_OFFSET <layer> <s1> <sm> <s2>

Each line is drawn in multiple layers, numbered consecutively starting at 0. Each line has three horizontal texture coordinates – a left, middle and right. The middle coordinate is aligned with the DSF line. The texture is simply repeated from top to bottom.

LAYER_GROUP <offset> <name>

[XP930:] This specifies which layer group (z order) to draw the polygon in. The definition is the same as the ATTR_layer_group command in the OBJ8 spec.

MIRROR

[XP930:] Normally a rounded or bent line is made by stretching the texture, forming trapezoids out of the lines. However when the mirror command is present in the file, X-Plane may reverse the texture direction to form clean cuts at sharp corners. This lowers the artifacts due to sharp corners in lines with lateral markings, but is in appropriate if the line has a clear longitudinal “direction” (e.g. a line with text in the texture along the long axis).

ALIGN <segments>

[XP1135:] Normally the texture for a .lin is repeated vertically over and over based on the vertical resolution parameters, and then it stops. To aid in alignment with end-caps, the ALIGN directive divides the line texture vertically into one or more segments. The line’s vertical texturing will then be stretched or shrunk to ensure that the line starts and ends on a segment boundary. If end-caps are used, they are subtracted out of the line before the stretching is done.

Note: ALIGN_SPLITS and MIRROR are incompatible – only one can be used at a time.

START_CAP <layer> <s1> <sm> <s2> <t1> <t2>

[XP1135:] This defines a start cap – a square of texture that will be used once before the line is drawn. Besides the horizontal positioning (left, middle and right), two vertical parameters (t1, t2) define the bottom and top of the cap. The start cap is applied to the “beginning” of the line, defined in a DSF as the first point in the polygon in DSF file order.

END_CAP <layer> <s1> <sm> <s2> <t1> <t2>

[XP1135:] This defines an end cap – a square of texture that will be used once before the line is drawn. Besides the horizontal positioning (left, middle and right), two vertical parameters (t1, t2) define the bottom and top of the cap. The end cap is applied to the “ending” of the line, defined in a DSF as the last point in the polygon in DSF file order.

Note: start and end caps are not used if the DSF file specifies a closed loop.

TEX_HEIGHT <pixels>

[XP1135:] This tells X-Plane the height of your texture in pixels.  All “t” (vertical) coordinates int he file are interpreted in terms of this directive, not the actual texture height.

Example file:

A
850
LINE_PAINT

TEXTURE taxilines.png
SCALE 10.0 2.5
S_OFFSET 0   0.03125  0.046875 0.0625
S_OFFSET 1   0        0.015625 0.03125

Vector Network (.net) File Format Specification

X-Plane uses a vector definition file (.net as in network) to visually render road networks. DSF files specify vectors by type and subtype. The type indicates what .net file to use for the roads; the subtype indicates a style of road within the .net definition file. The default scenery defines 62 vector types; you may replace the default road artwork by using the same subtypes, or use your own subtype numbers for your own custom scenery. Vector Network definition files are standard X-Plane text files with 3-line headers. Each command then takes one line, with parameters separated by spaces. A vector contains one or more subtypes and uses one or more textures. Each road subtype must use only one texture.

        A
        800
        ROADS

TEXTURE

This command specifies a texture to be used by the vectors. The bitmap should have the file extension on it. The numeric parameter indicates the amount of Z-buffer offseting to use when using this texture. A positive number helps X-Plane draw the vector on top of the terrain mesh without Z-buffer thrash. Zero indicates no offsetting; this setting is good for bridges. The texture command establishes an index number for that texture within the .net file. The first texture command will be texture 0, the second texture command 1, etc. Note: if you need to sometimes use a texture with z-buffer offsetting and sometimes without, simply include it twice with different Z-buffer offsets. This will establish two indices for the texture, but X-Plane will only load the texture into VRAM once.

TEXTURE <z offset> <filename>

TEXTURE_LIT

This command establishes a night-lit texture to go with the main texture for a road network. If this command is used at all, there must be one for each texture command, and they must follow in the same order. X-Plane will not automatically find _LIT bitmaps without this command.

TEXTURE_LIT <filename&ht;

SCALE

Normally texture coordinates are specified fractionally, e.g. 0.2 for a pixel 2/10ths of the way through the texture. The scale command indicates that all texture coordinates are multiplied by a fixed constant. If this command is not included, it is as if the scale is 1.0. The scale is applied to all commands that follow the scale command. Note: This allows you to work in terms of the pixel positions of the texture instead of fractional coordinates. But X-Plane does not take the real texture size into account. You can use a scale of 1024 even if the texture is not 1024×1024 pixels.

SCALE <scale>

ROAD_TYPE

This indicates information about a new road type. Segment, wire, and object commands apply to the previously declared road type. The road type takes seven parameters:

1. The numeric road subtype. This is an integer defining the road subtype. X-Plane matches this road type against the “subtype” field in the DSF file. (See the DSF spec for more info.) Road subtypes do not have to be consecutive or in ascending order in a road network file, but each road subtype should only be used once.
2. Segment width (meters). This defines how wide the vector is. All width-related info is relative to this defined width.
3. Repetition length (meters). This defines how many meters one length of the texture are applied to.
4. Texture index (zero based). This defines which texture to use, based on the texture commands previously defined.
5. Red fraction – a ratio from 0 to 1, indicating the percentage of red to use to draw this vector in the map view.
6. Green fraction – a ratio from 0 to 1, indicating the percentage of green to use to draw this vector in the map view.
7. Blue fraction – a ratio from 0 to 1, indicating the percentage of blue to use to draw this vector in the map view.

ROAD_TYPE <subtype>  <width> <length> <texture>  <red> <green> <blue>

SEGMENT

The segment command defines one quadrilateral section of a road. Segments are extruded along the length of a road vector. The simplest possible road would have one segment. Segments are defined in terms of their lateral extent, meaning how far across the road they go, and their vertical extent, meaning how far above and below the road they go. Lateral extent is defined as a ratio, where 0.0 is the left side and 1.0 is the right side. (Segments cannot extend outside the width of the segment – if you need ot make a wider segment, define the whole vector type to be wider using the ROAD_TYPE command.) Vertical extent is defined in terms of meters, where 0 is the height of the road, positive is above the road and negative is below. Texturing of segments is performed as follows: the texture’s vertical axis is aligned along the length of the vector and repeats continuously, with length meters of vector (as defined in the ROAD_TYPE command) corresponding to one repetition of the texture. The texture’s horizontal axis crosses the road, or goes up and down vertical “walls”. Horizontal texture positions are normally stored as “S” coordinates, meaning fraction of the distance across the texture, but the SCALE command (see above) can be used to change these units. Segments have associated level-of-detail parameters. You can define at what range/how far out segments are visible, so that small details (like guard rails) are only drawn when close to the vector segment. The segment command takes 8 parameters:

1. Near LOD (meters). The closest distance at which the segment is visible.
2. Far LOD (meters). The farthest distance at which the segment is visible.
3. Beginning lateral fraction. The lateral position of the start of this segment, as a ratio where 0 = the left side of the vector and 1 = the rgiht.
4. Beginning vertical offset. The height above the road that this segment starts at, in meters, positive means up.
5. Beginning texture coordinate. The horizontal position on the road texture to use to start drawing this segment.
6. Ending lateral fraction. The lateral position of the end of this segment, as a ratio where 0 = the left side of the vector and 1 = the rgiht.
7. Ending vertical offset. The height above the road that this segment ends at, in meters, positive means up.
8. Ending texture coordinate. The horizontal position on the road texture to use to end drawing this segment.

SEGMENT <near lod> <far lod>  <start lat> <start vert> <start tex>  <end lat> <end vert> <end tex>

WIRE

The wire command instructs X-Plane to string a powerline wire along the vector segment. Powerline wires may be added to any vector type; the “powerline” vector type is simply a vector with powerlines, no roads, and objects forming the towers. The texturing/coloring of the wire is handled by X-Plane. The wire command takes 5 parameters:

1. Near LOD distance (meters). This is the nearest the wire will be seen.
2. Far LOD distance (meters). This is the farthest the wire will be seen.
3. Lateral offset (meters). This is the position of the wire, relative to the width of the vector. 0 = left, 1 = right.
4. Vertical offset (meters). This is how far above (or below) the vector the wires will be at their endpoints.
5. Droop Ratio (meters). This is the percentage of the vertical height that the wire droops at its lowest; 0.0 means no droop, 1.0 means the wire is dropping all the way down to the vector itself (e.g. touching the ground).

WIRE <near lod> <far lod>  <lateral offset> <vertical offset> <droop ratio>

OBJECT

The object command instructs X-Plane to place an object (OBJ) at a location along the vector. Objects are positioned laterally along the width of the vector, but unlike segments, can be placed to the left of the vector (using negative ratios) or to the right of the vector (using ratios greater than 1). Objects can be placed at a fixed interval of meters, or they can be placed at every “shape point” along the vector, e.g. each time the vector changes direction. (See the DSF spec for more on shape points.) Objects can be rotated; normally they are placed at a heading of 0 for a north-heading vector. When a vector turns a corner, if an object is placed at that corner its heading is the average of the two vectors touching that corner. Objects may be placed at the height of the vector, or they may be repositioned on the ground. In this case if the vector is above the ground (e.g. a bridge or overpass) the object will still be placed on the ground. The object command takes six parameters:

1. Object name (with .obj) extension – the filename of the object. The object should be in the same directory as the .net file that references it, or a subpath may be specified in this name.
2. Lateral offset – a ratio positioning the object, where 0 = left side of teh vector and 1 = right.
3. Rotation – a clockwise rotation to turn the object additional to the heading of the vector.
4. On ground – 1 if the object should be placed on the ground, 0 if the object should be placed at the same height as the vector.
5. Object frequency – how often the object should be placed, in meters, or 0 if the object should be placed once per shape point.
6. Object offset (meters) – if the object is placed by distance, it will start at the beginning of the vector; with this offset you can start the object n meters along the vector.

OBJECT <name> <lateral offset ratio> <rotation> <force on ground> <placement frequency> <placement offset>

REQUIRE_EVEN

[X-Plane 820] Normally textures are applied to a road by scaling the vertical axis of the texture along the road (longitudinal axis) based on the length of the road, e.g. a “30 meter” road gets one full repetition of the texture every 30 meters. This implies that a 70 meter road gets 2.3 copies of the texure and the raod ends midway through the texture. When the REQUIRE_EVEN attribute is applied to a road type, the length of the road is scaled as it is applied so that the texture will be used an even number of times. In the case above, the road would be rescaled from 30 meters to 35 meters, and would be applied exactly twice. This rescaling is done differently for every segment of the road so that the texture is never chopped. This command affects segments and objects that are placed by distance; distance-placed objects have their distances scaled by the same factor as segments so that the relative relationship of objects and texture is maintained. Objects that are placed as a fraction of the segment and wires are not affected by this command. The command must be after the ROAD_TYPE command and affects the previously stated road-type only; use this command once for every road type that will be scaled.

REQUIRE_EVEN

SEGMENT_HARD

[X-Plane 850] The segment hard command is just like the regular segment command, except that it declares that the road segment will be “hard” (similar to hard polys in an object), allowing the plane to land on them. The hard surface command takes all regular surface commands, plus a surface name, which are the same names as in the OBJ8 format. See the OBJ8 spec for a list of surfaces. The hard segment command takes 9 parameters:

1. Near LOD (meters). The closest distance at which the segment is visible.
2. Far LOD (meters). The farthest distance at which the segment is visible.
3. Beginning lateral fraction. The lateral position of the start of this segment, as a ratio where 0 = the left side of the vector and 1 = the rgiht.
4. Beginning vertical offset. The height above the road that this segment starts at, in meters, positive means up.
5. Beginning texture coordinate. The horizontal position on the road texture to use to start drawing this segment.
6. Ending lateral fraction. The lateral position of the end of this segment, as a ratio where 0 = the left side of the vector and 1 = the rgiht.
7. Ending vertical offset. The height above the road that this segment ends at, in meters, positive means up.
8. Ending texture coordinate. The horizontal position on the road texture to use to end drawing this segment.
9. Surface code. The name of the hard surface type.

SEGMENT_HARD <index> <lod> <lod> <dx1> <dy1> <s1 <dx2> <dy2> <s2> <surf>

CAR

[X-Plane 850] The car command defines a lane of cars. The car command defines how fast and what kind of cars can traverse a lane and also controls the generation of cars.

• Reverse – if 1, the car goes in the opposite direction of the road’s natural direction, otherwise it goes with it. Please note that the lateral offset is “from the left” relative to the car direction! So for example in the US (where cars are on the right side), the lateral offset should be greater than 0.5 even if the reverse flag is set to 1.
• Lateral offset – a ratio from 0 to 1 indicating how far from the left to right of the road the center of the lane is.
• Velocity – the speed of the traffic in that lane in meters per second. Must be greater than zero.
• Spawn ratio – a fraction indicating how many cars per kilometer are generated. But this is scaled by X-plane based on user settings, so you should probably copy the existing ratios from existing road types.
• Traffic type – an index into the CAR_MODEL commands (see below), 0 is the first command, indicating the type of car to use.

CAR <reverse> <lateral offset> <velocity> <spawn ratio> <traffic type>

CAR_MODEL

[X-Plane 850] The CAR_MODEL command defines an object to be used as a car model. These commands are referenced by car commands – the first CAR_MODEL command defines traffic type “0”, the second one traffic type “1”, etc. The input is an object name. The object name may be a library path – in this case all objects matching the library path will be used, creating a variety of cars. In this way you can create variety in traffic. Each library path should reference multiple objects all of a similar type since all of those matching objects may be sharing a traffic lane.

CAR_MODEL <object path>

TRAIN

[X-Plane 900] The TRAIN command defines a train (a string of objects) to be used as a car model. A train command takes up one index just like the CAR_MODEL command does. (That is, if you use CAR_MODEL, then TRAIN, then car type 0 is the object specified by the CAR_MODEL command and car type 1 is the train specified by the TRAIN command. The train sub-commands that follow help define the train.

TRAIN

TRAIN_VARIANT

[X-Plane 900] A car command points to a single object, but the library system randomly substitutes any of the matching objects for that car type. So with a carefully built library, a lot of traffic variation is possible. However with trains, each object substitution (representing one railroad car) must be the same length as all others that go in a certain “slot” or the train will not connect together properly. The train-variant command is provided to allow for more train variety within this constraint. A train variant is a sequence of object-paths and spacings that defines how a train looks – a train may have one or more variants, and each variant can have a different number of cars or a different choice of train-car object paths.

TRAIN_VARIANT

TRAIN_CAR

[X-Plane 900] The train-car command adds one more train-car to the current train-variant. For each car, two lengths are specified – the first is the length from the center of the OBJ (0,0,0) to the front of the car (along the -Z axis) and the second is from the object center to the back of the car (along the +Z) axis. The object path is a virtual path in the library. Note that every object that matches this path must fit into the “slot” specified by the two lengths, or the train car will not align properly. (The library system is used, so given the length of a train car, multiple variants can be selected.)

TRAIN_CAR <length 1> <length 2> <object path>

Modern and Virtual Road Segment Directives (10.00 and Newer)

These directives provide more control over road segments including draping on the ground and variants based on height above the ground.

VARIANTS

TBD

VARIANTS <count>

ROAD_CENTER

This declares the distance from the left edge of the road’s surface area to the centerline. Normally road types are declared only by width and assumed to be symmetrically extruded off this center line; this directive can be used to, for example, have a road with “extra” area on one side, e.g. for a one way road with certain decorations.

ROAD_CENTER <distance>

ROAD_DRAPED

This directive defines a new virtual road type. The virtual road contains a list of specific road types (via the ROAD_TYPE directive) to be used under varying conditions.

Draping modes define whether the road is to be treated as graded, traped, or both.

0: the road is draped on the ground and will follow the ground’s contours.


1: the road can be draped or graded


2: the road must be graded (drawn solidly in 3-d in its own 3-d space, crashing into the mesh

type is the virtual type ID for this specific road – this is what is referenced in the DSF.

Pitch and roll are pitch and roll limits; these are ignored by the sim.

ROAD_DRAPED <mode> <type> <pitch> <roll>

ROAD_DRAPE_CHOICE

This directive adds a real road type as a possible type for a virtual type, given an AGL constraint – that is, how far above the ground the road actually goes. The idea is to allow different variants for roads on the ground, roads high enough to be on embankments, and full bridges.

ROAD_DRAPE_CHOICE <max AGL> <real type>

BIDIRECTIONAL

The bidirectional directive declares one or more road types (virtual or real) to be fully reversible – X-Plane can reverse this road’s direction to optimize the network.

BIDIRECTIONAL <type> [...<type>]

ONE_SIDED

This directive changes road geometry to not be two-sided. In the original .net spec, all geometry was visibly two-sided (for vertex efficiency), resulting in infinitely thin polygons and incorrect lighting.

A modern road art file can declare one-sided geometry and fully extrude “solid” walls on roads, e.g. for barriers. This directive will then tell X-Plane that the lighting can be calculated for full 3-d meshes.

ONE_SIDED

SEGMENT_DRAPED

This directive creates an extruded rectilinear segment on a road that will be draped on the ground.

• material is the zeor-based index of the shader to use for this segment.
• lod near/far are the draw distances in meters within which to draw this segment.
• t_scale is a multiplier to scale the road along its longitudinal axis compared to the normal expected resolution for the material.
• dx1 and dx2 define the horizontal offset (+x = right) in meters from the centerline of the road.
• s1 and s2 define the UV map horizontal texture coordinates (normalized) of the texture.
• surface, if present, is a keyword for a physics surface type, e.g. asphalt, concrete.

SEGMENT_DRAPED <material> <lod_near> <lod_far> <t_scale> <dx1> <s1> <dx2> <s2> [<surface]>

SEGMENT_GRADED

This directive creates an extruded rectilinear segment that follows the road’s centerline in 3-d space.

• material is the zeor-based index of the shader to use for this segment.
• lod near/far are the draw distances in meters within which to draw this segment.
• t_scale is a multiplier to scale the road along its longitudinal axis compared to the normal expected resolution for the material.
• dx1 and dx2 define the horizontal offset (+x = right) in meters from the centerline of the road.
• dy1 and dy2 define the vertical offset of the segment in meters (+y = up) from the road’s centerline in 3-d space.
• s1 and s2 define the UV map horizontal texture coordinates (normalized) of the texture.
• surface, if present, is a keyword for a physics surface type, e.g. asphalt, concrete.

SEGMENT_DRAPED <material> <lod_near> <lod_faR> <t_scale> <dx1> <dy1> <s1> <dx2> <dy2> <s2> [<surf>]

SEGMENT_NORMALS

When present following a SEGMENT_GRADED directive, this defines custom normal vectors for a segment. The X and Y components of the normals are provided for both end-points, with Y = up, +X = right. The Z component is assumed to be zero since the Z axis aligns with the length of the segment.

SEGMENT_NORMALS <nx1> <ny1> <nx2> <ny2>

LOCKED_POWERLINES

[X-Plane 10.30 and newer]: if present, this disables X-Plane’s attempts to reposition powerlines to avoid crashing into other roads; powerlines will appear exactly where there are junctions in the raw DSF data.

Modern Directives for 3-d Clutter

These directives (X-Plane 10.00 and newer) add objects and vehicles to roads.

CAR_DRAPED/CAR_GRADED

This directive spawns traffic on a road segment.

• reverse: 0 if the car travels in the direction of the network link, 1 if opposite
• dx: the offset of the car from the centerline
• speed: of the car in m/s
• spawn ratio: defines frequency of car per meter of road
• car type: a zero-based index into the traffic definitions of the file

CAR_DRAPED <reverse> <dx> <speed> <spawn ratio> <car_type>
CAR_GRADED <reverse> <dx> <speed> <spawn ratio> <car_type>

OBJECT_DRAPED/OBJECT_GRADED

These directives place 3-d models along a road segment. Draped objects sit directly on the terrain while graded ones are aligned to the road itself. Both can be used regardless of the road mode, e.g. for a graded bridge, a draped object can be used to anchor “footings” for a bridge to the ground.

Most parameters are given in pairs, and a random value between them is picked.

Mode: an enumeration for how the objects are placed.

`SEG` - an object is placed once per segment, based on the distance parameter.


`VERT` - an object is placed at every vertex.


`DIST` - an object is placed at fixed distances along the road, based on the distance parameter.


`BEGIN` - an object is placed at the beginning of the road.


`END` - an object is placed at the end of the road.


`CREASE` - an object is placed at each shaping point along the road that is a ‘crease’ and not a gentle curve. The object heading is the average of the two headings.

dx1/2: defines the range of offsets lateral to the road to place the object from the centerline, +x=right.

angle1/2: defines the rotation of the objects clockwise, zero faces the -Z of the object along the direction of the road segment.

distance1/2: defines the distance between each object or along each segment.

offset1/2: these are defined in pairs from the start and end, e.g. 10/20 would mean the object must be offset 10m or more from the start and 20m or more from the end; this is used to keep objects from appearing at the ends of roads whhere there migt be junctions.

lo hi: if present, defines the x-plane level of object clutter where these start to appear (lo) and fully appear (hi). At ‘hi’ user setting, the object is guaranteed to be present, and below ‘lo’ it will be removed.

OBJECT_DRAPED <mode> <model> <dx1> <dx2> <angle1> <angle2> <distance1> <distance2> <offset1> <offset2> [<lo> <hi>]
OBJECT_GRADED <mode> <model> <dx1> <dx2> <angle1> <angle2> <distance1> <distance2> <offset1> <offset2> [<lo> <hi>]

OBJECT_FREQ

This directive defines randomization for a previous OBJECT_DRAPED/GRADED directives.

The four periods (in meters) and amplitudes (from 0 to 1) shape four random noise fields to provide multi-level fractal noise. If the noise field (as shaped) results in a frequency (normalized) between lo and hi, the object is selected.

Because the noise field base is universal to X-Plane, different lo/hi ranges can be used to select object alternatives by using the same period/amplitude parameters.

OBJECT_FREQ <freq lo> <freq hi> <prd1> <amp1> <prd2> <amp2> <prd3> <amp3> <prd4> <amp4>

OBJECT_ALT

This directive defines alternate model sets from the library for a previous OBJECT_DRAPED/GRADED directive. Each road network chain will pick exactly one alternate set and randomize within it (via the library) for that chain.

OBJECT_ALT <model library path>

Directive for Road Junctions

[X-Plane 10.0 and later]: these directives define road junction artwork.

Road net files for X-Plane 10.0 and later require custom artwork to create the junctions between roads. There are two types of junctions:

• Regular junctions fit an exact topology of incoming roads and are customized for this use case.
• Composite junctions are small pieces that are stitched together to form a multi-polygon covering N arbitrary roads.

X-Plane will prefer to use regular junctions, and will fall back to composite junctions for unusual cases.

Each junction consists of:

• Some meta-data describing the junction’s use.
• A bone table, which describes the positioning of a coordinate system (a ‘bone’ in an animation system) relative to the road system. Since each junction can have multiple bones, the vertices can be stretched to fit exact situations.
• A vertex table, providing the vertices of UV-mapped meshes.
• Material and primitive directives, defining one or more triangles or quads to be rendered. A materials are provided by indices and multiple materials can be used in a single junction.

JUNCTION_DRAPED/JUNCTION_GRADED/JUNCTION_EMBANKED/JUNCTION_BRIDGE

These directives define a new complete junction. The directives are named by how they manage vertical extents:

• Draped junctions sit flush on the terrain.
• Graded junctions are on the ground but sit in their own coordinate system, with 3-d intersecting the ground.
• Embanked junctions are elevated but do not form a bridge
• Bridge junctions are clearly above the ground.

The valence is the number of roads that will enter this junction.

JUNCTION_DRAPED <valence>
JUNCTION_GRADED <valence>
JUNCTION_EMBANKED <valence>
JUNCTION_BRIDGE <valence>

MATCH

A match directive provides the topology of road types that a junction can match. Each match directive specifies the roads that can match each slot in the valence; there should be one match directive per valence degree.

Each match directive consists of a list of one or more road types; the road types are annotated by an enumeration specifying the direction followed by the road virtual type. Legal enumerations:

• in – the road’s direction must go into this junction.
• out – the road’s direction must come out of this junction.
• io – the road may go into or out of the junction.

MATCH <direction> <road id> [...<direction> <road id>]

JUNCTION_COMPOSITE_CORNER

This directive defines a corner element for a composite junction; this junction will define only a corner between two incoming roads. The junction will need two match directives to define the two roads coming into the junction. The draping mode is one of

• DRAPED – the junction sits on the mesh
• GRADED – the junction is “on the ground” but in 3-d colliding with the mesh.
• EMBANKED – the junction is in the air but with no passage under it.
• BRIDGE– the junction is in the air and there is space under it

JUNCTION_COMPOSITE_CORNER <draping mode>

JUNCTION_COMPOSITE_APPROACH

This directive defines the part of a composite junction just before a single road entering the junction, not the shared space; it needs a single match directive to specify the type of road that it can “cap off”.

JUNCTION_COMPOSITE_APPROACH <draping mode>

JUNCTION_COMPOSITE_CENTER

This directive defines the center area of a composite junction – it forms an N-gon based on its valence. Unlike corners and approaches, composite centers are not matched to any road type – requiring an exact type of incoming roads would defeat the flexibility of the system. (If you know the exact type of roads coming in, you can use a non-composite junction.

JUNCTION_COMPOSITE_CENTER <valence> <draping mode>

JUNCTION_COMPOSITE_STUB

While composite junctions provide a powerful way to build arbitrary junctions for arbitrarily weird road topology, the animation scheme does not cope well with very large angles between roads.

A phantom road type is a virtual road type that will never exist, but that is added to the junction to create a smaller angle between incoming roads. For example, a T-style junction with 180 degrees between the two vectors of the “uninterrupted” road could have a phantom inserted opposite the dead-ned road to make a four-way junction with 90 degree angles.

The expectation is that there will be a composite approach junction matching the phantom road type and its art will “cap off” the composite junction. For example, if the main road has side walks, the phantom road type’s corners and approaches would continue the sidewalk along the composite junction’s “empty” side.

The direction/ID list works the same as. MATCH directive, and defines all road types that can have this phantom road type adjacent to them.

JUNCTION_COMPOSITE_STUB <phantom road type> <direction id> [...<direction> <id>]

BONE_INTERSECTION_EDGE_LEFT/BONE_INTERSECTION_EDGE_RIGHT

This adds a new bone to the current intersection defined by the intersection of the centerlines of the two roads, with an offset.

• The bone “index” is the index number of the road going into the junction. (Numbering is established by matching declarations, e.g. index 0 will be a road matching the first MATCH in the file.)
• off1 and off2 are positive offsets insetting the bone from the total edge of the roads (defined by their widths).
• x,y,z is the rest position of the bone in junction coordinates (with 0,0,0 at the true intersection of the two roads)
• dx,dy,dz is the rest direction of the bone, which will be rotated to match the indexed junction

BONE_INTERSECTION_EDGE_LEFT <road index> <offset 1> <offset 2> <x> <y> <z> <dx> <dy> <dz>
BONE_INTERSECTION_EDGE_RIGHT <road index> <offset 1> <offset 2> <x> <y> <z> <dx> <dy> <dz>

BONE_INTERSECTION_APPROACH_LEFT/BONE_INTERSECTION_APPROACH_RIGHT

This directive adds a bone to a junction for a composite approach or center junction. The bone is either on the right or left edge of the road facing into the junction.

• The index is based on the matching order of the junction; for approach junctions this is usually 1, but for center junctions this can be used to index each part of the junction.
• offset1 is an offset along the road from the nominal center of the plug.
• offset2 is an offset parallel to the actual edge of the center, which can be skewed based on the types of roads entering the junction.
• x, y, z is the rest position of the road, relative to the junction.
• dx, dy, dz is the rest direction of the indexed road.

BONE_APPROACH_LEFT <index> <offset1> <offset2> <x> <y> <z> <dx> <dy> <dz>
BONE_APPROACH_RIGHT <index> <offset1> <offset2> <x> <y> <z> <dx> <dy> <dz>

BONE_CENTROID

This defines a bone at the centroid of the junction. This bone is typically not used because it has no rotation from its rest position. X, Y, Z is the position of rest position of the bone.

BONE_CENTROID <x> <y> <z>

BONE_BEZIER

This defines a bone along the bezier curve of a road, in the direction of the curved road.

The bone is defined by an indexed road into the junction and a number of meters out from the junction to follow the curve. Like previous bones, the position and direction vectors define the rest position of the bone for authoring.

BONE_BEZIER <index> <distance> <x> <y> <z> <dx> <dy> <dz>

BEZIER_OFFSET

This directive moves the origin for a junction in a fixed distance along a particular road, which will bias the amount of road available for junction matching.

BEZIER_OFFSET <index> <distance>

MAX_SHEAR

This directive overrides the maximum amount of “shearing” distortion a junction can be subject to and still be used. The default maximum is 45 degrees. For example, this directive can limit how far a “plus” junction can be distorted into an “X” junction.

MAX_SHEAR <angle>

CUTBACK

This defines how much to cut back roads going into a junction to make more space for junction art. If missing, roads are not cut back at all. If present, there must be one entry for each road in matching order. Cut backs can be numeric distances or none to bypass cutback for a particular road.

CUTBACK <distance> [...<distance>]

JUNCTION_MINIMA

If present, JUNCTION_MINIMA defines the amount of road distance necessary to fit a junction. This presents junctions with large art footprints from being crammed into a very small space. There must be one distance for each road in the junction.

JUNCTION_MINIMA <distance> [...<distance>]

JUNCTION_LEVEL_SET

This directive defines which road types interact with a junction and which pass over each other. Each directive defines a bit-field per junction; the default level set for any road is 1 – if left alone this will make all roads intersect with each other.

This can be used to ensure that powerlines do not need junctions with roads, or to allow some rail artwork to collide with roads.

JUNCTION_LEVEL_SET <virtual road type> <bitfield>

Directives for Junction Meshes and Clutter

VERTEX

This adds a vertex to the vertex table of a junction. The vertex is defined in the spatial coordinates of the rest position of the junction, and will be transformed by its bones. Each vertex can have up to four. bones; the weights of the bones must add up to 1.0. At least one bone must be specified. Texture coordinates are normalized

VERTEX <x> <y> <z> <normal_x> <normal_y> <normal_z> <s> <t> <bone 1> <weight 1> [<bone 2> <weight 2> [<bone 3> <weight 3> [<bone 4> <weight 4>]]]

JUNC_SHADER

This defines the material to be used by the following TRI/QUAD directives for a junction. A shader must be specified before TRI/QUAD directives. The physical surface can be one from an .obj file like asphalt, concrete, etc.

JUNC_SHADER <material index> <max draw distance> [<physical surface>]

TRI/QUAD

These directive add one triangle or quadrangle to the junction by referenced index number.

TRI <index 1> <index 2> <index 3>
QUAD <index 1> <index 2> <index 3> <index 4>

JUNC_OBJECT

This directive adds an object model to a junction.

• x, y, and z define the position of the object’s origin relative to the junction rest position.
• r defines the rest rotation of the object, where 0 matches the rest coordinates of the junction.
• drape is a draping flag: 0 means position in the 3-d coordinates of the junction, 1 means drop the object to register with the terrain mesh (drape).
• The bone/weight list provides four bones and weights to blend to move the object. Use 0 weights for unused bones; weights must add up to one.
• model is the library path for the model to be used.
• lo/hi if present define when to draw the object with X-Plane’s settings; the object will not be drawn when settings are below ‘lo’ and will be drawn when the settings are at ‘hi’ or above.

JUNC_OBJECT <x> <y> <z> <rotation> <draping flag> <bone 1> <weight 1> <bone 2> <weight 2> <bone 3> <weight 3> <bone 4> <weight 4> <model path> [<lo> <hi>]

Example Vector Definition File

This is an example network definition file. (For a more detailed road.net file, see the .net files in the “default scenery” folder.)

A
800
ROADS
TEXTURE 3 roads_legacy.png
TEXTURE 0 roadbridges_legacy.png
TEXTURE 3 trails_legacy.png
TEXTURE_LIT roads_LIT.png
TEXTURE_LIT roadbridges_LIT.png
TEXTURE_LIT trailsLIT.png

SCALE 1024

ROAD_TYPE 0   18 18 0        1.0 1.0 1.0
SEGMENT    0 30000   0 0 0.0 1 0 0.5

ROAD_TYPE 3    24  500 0      1.0 1.0 0.2
WIRE        0 30000   0.15 22.8 0.4
WIRE        0 30000   0.85 22.8 0.4
OBJECT      powerline_tower.obj 0.5 0.0 1 0.0 0.0

ROAD_TYPE 6    3 3 2        0.0 0.0 0.0
REQUIRE_EVEN
SEGMENT    0 30000  0 -3 0.5    0  0 0.625
SEGMENT    0 30000  0  0 0.625  1  0 0.875
SEGMENT    0 30000  1  0 0.875  1 -3 1.0

Draped Polygon (.pol) File Format Specification

Draped polygons (.pol) define how a DSF polygon should be turned into pavement or some other ground that is draped over the existing terrain mesh. One use is to make custom taxiways, but any texture could be used.

.pol files are used via bezier polygons. Multiple windings may be used to specify holes in the pavement. The polygons should have two coordinates (lon,lat) for line segments or four coordinates (lon,lat, control lon, control lat) for bezier curves. The parameter is used as a rotation of the texture in degrees.

Note that .pol file textures are not aligned to any particular coordinate system so they are only appropriate for repeating texture, not orthophotos.

[New in 860:] Starting with X-Plane 860, a polygon’s texture coordinates may be specified in the DSF file. To do this:

Set the polygon instance’s parameter to 65535 in the DSF.
Pass two (or four for bezier curve) ST coordinates at the end of each vertex that will be used as ST coordinates.
X-Plane will ignore the SCALE command.
The header of a .pol file is:

A
850
DRAPED_POLYGON

The rest of the file is made of commands, or # for a comment line. The commands are:

TEXTURE <texture name>

This defines the texture to use – the texture name is relative to the .pol file.

TEXTURE_LIT <texture name>

If present, this defines a night lighting overlay to use, again relative to the .pol file.

SCALE <horizontal scale> <vertical scale>

This defines how large one iteration of the texture is, in meters.

(860: if the polygon has specific ST coords in the DSF, the scale command is ignored.)

LAYER_GROUP <group name> <offset>

This specifie which layer group (z order) to draw the polygon in. The definition is the same as the ATTR_layer_group command in the OBJ8 spec.

SURFACE <surface type>

If present, this defines the type of hard surface that the polygon will create. Surface codes are the same as for ATTR_hard in the OBJ8 spec.

TEXTURE_NOWRWAP <texture name>

[New in 860:] This command is the same as the TEXTURE command, except the texture’s edge blending is set to “clamped” as opposed to “wrapped”. This will cause the texture to correctly tile when it is a subsection of an orthophoto, but not when the texture repeats like a land-use.

TEXTURE_LIT_NOWRWAP <texture name>

[New in 860:] This command is the same as the TEXURE_LIT command, except the texture’s edge blending is set to “clamped” as opposed to “wrapped”. This will cause the texture to correctly tile when it is a subsection of an orthophoto, but not when the texture repeats like a land-use.

NO_ALPHA

[NEW in 860:] This command tells X-Plane to ignore the alpha channel of the texture. Some textures may have special “noise” alpha channels that aren’t useful for basic texturing; this command can be used to strip out the alpha data in the sim, allowing the texture to be used for multiple purposes.

LOAD_CENTER

X-PLANE 920: This command estabishes that this texture will be used at a certain location, specified by the lat/lon taken to be the texture’s center. By also specifying theapproximate terrain size when placed (in meters) and textures size (in pixels), X-Plane will load the texture with variable resolution based on the general distance from the user to the texture. As the user flies, X-plane will periodically reload the texture.

LOAD_CENTER affects loading of the base texture and night texture if it exists. A texture that uses LOAD_CENTER should only be referenced once by one art resource per DSF tile. For optimal performance, the texture should be in DDS format, so that reloads at lower resolution are fast.

LOAD_CENTER 
LOAD_CENTER 42.70321 -72.34234 4000 1024

Example file:

A
850
DRAPED_POLYGON

TEXTURE concrete.png
SCALE 25 25
LAYER_GROUP taxiways 0
SURFACE concrete

Object String (.str) File Format Specification

Object strings are objects placed along a bezier curve. They are used primarily to build airport taxiway lights but can be used to place any kind of object desired.

Object string files are standard X-Plane 8 text files starting with a header and then commands. The # defines a comment.

A
850
OBJECT_STRING

Object strings are used by defining polygons in the DSF file. The polygon may have windings – only lat and lon coordinates are needed. The polygon parameter is used to indicate the spacing of objects in meters.

If two coordinates are provided (lon, lat) then the string is made of line segments. But if it is made of four coordinates (lon, lat, control lon, control lat) then it is interpretted as bezier curves.

The commands define the string of objects.

OFFSET <distance>

The offset command defines how far to the right of the line segment (as defined by traveling along the segment) the objects are to be placed. Positive numbers are to the right, negative to the left, and zero is right on the line.

OBJECT <random 1> <random 2> <object>

The object command specifies an object to put in the chain – all objects are alternated as the chain is laid out. Objects are placed heading along the chain plus a clockwise offset between random 1 and random2.

The object name can be the name of a library object, found in a different scenery package, or an object found relative to the .str file.

Example file:

A
850
OBJECT_STRING

OBJECT 0 inset_centerline_txy.obj
OFFSET 0

Terrain Type (.ter) File Format Specification

X-Plane Terrain Type (.ter) files instruct X-Plane on how to paint terrain patches. This file format specification discusses the contents of .ter files and describes how X-Plane combines a DSF file with a .ter file to create a mesh. Terrain type files separate non-image terrain data from DSF files and the sim itself, allowing terrains to be shared between scenery packages and easily updated.

You may use a bitmap file (.bmp or .png) directly without using .ter files. This is described at the end of the specification.

X-Plane Terrain Rendering Techniques

X-Plane’s rendering engine is capable of performing a few different mesh effects. We will catalogue these effects before describing how a .ter file invokes them.

• Base Texture. The most simple way for X-Plane to draw terrain is to map a texture onto the ground.
• Night Lighting Texture. X-Plane can overlay a second night lighting texture on top of the base texture when simulating night. The second terrain texture is added to the base texture, but is not affected by the sim’s ambient lighting levels. A night lighting texture could be used to draw reflections from street lights, etc. The use of night lighting textures is similar to night lighting textures for aircraft and objects.
• Alpha channel. If the base texture contains an alpha channel, it can be used to render parts of the base texture translucent or transparent, revealing other terrain beneath it.
• Alpha mask. A separate grayscale texture may be used to mask out parts of a texture. This is different from the base texture’s alpha channel in that the mask may be applied with in a different position or with different stretching. (This effect is similar to the border masks from the X-Plane 7 landuse system.)
• Projection. A texture may be aligned with specific mesh triangles (similar to X-Plane 7) or projected onto the terrain. When a texture is projected, each pixel covers a constant area of the earth rather than a constant number of triangles. X-Plane 8.20 allows the projection angle to be customized; previous versions require projection straight down.
• Compositing. X-Plane 8 can combine two textures (the base texture and the composite texture). X-Plane blends pixels from the base and composite texture using the base texture’s alpha mask. However, the blend is modulated by a separate parameter that is applied to each vertex of the mesh. (In the default scenery this is used to blend rock/soil textures with vegetation textures. The parameter on the mesh controls how much vegetation covers the rock, and the alpha mask on the rock defines where vegetation peeks through.) If the mesh does not contain a parameter to blend terrain, then starting with X-Plane 8.02 X-Plane will randomly vary the terrain.

WARNING:

 As of X-Plane 820, compositing produces artifacts on some hardware and is not recommended.

[X-Plane 9] As of X-Plane 9, compositing is deprecated and not recommended.

• Composite borders (820). X-Plane can fade out a texture via dithering instead of blending, by comparing the texture’s alpha to the border mask’s alpha.
• Auto-Variation (900). X-Plane can mix your terrain together with itself (offset a bit) to create a less repetitive looking terrain.

Terrain Type File Structure

Terrain type files are text files, following the standard X-Plane 3-line header structure, followed by a series of commands, one per line.

A 800 TERRAIN

All bitmaps are specified with file extensions. Directory separators may be colons, forward or back slashes. Commands are case sensitive. Lines are separated by spaces and not tabs.

BASE_TEX

This specifies the base texture for the terrain.

BASE_TEX <filename> BASE_TEX Crops:FlatCrops.png

LIT_TEX

This specifies the night lighting texture for the terrain, if one is to be used. If you want to use a night lighting texture and you have a .ter file you must include this – X-Plane will not look for a texture with the same name as the base texture plus the extension _LIT.

LIT_TEX <filename> LIT_TEX Crops:FlatCropsNight.png

BORDER_TEX

This specifies an additional border texture to be used as an alpha mask. If this command is present, a separate alpha mask is used, otherwise it is not.

BORDER_TEX <filename> BORDER_TEX border.png

COMPOSITE_TEX

This specifies an additional texture to be composited with the base texture. The alpha from the base texture is used to determine where the composite texture will show through. High percentages on the mesh indicate more of the composite texture – low percentages indicate more of the base texture.

COMPOSITE_TEX <filename> COMPOSITE_TEX Vegetation:Grass_green.png

NO_ALPHA

This tells X-Plane not to use the alpha from the base texture for transparency, even if alpha is present. If this command is not included and X-Plane has alpha in the base texture, that alpha will be used.

NO_ALPHA

PROJECTED

This tells X-Plane that the texture must be projected. The base, composite, and lit textures may be projected; a separate alpha mask never is. If this command is present, the texture is projected at the given resolution, otherwise the DSF file must specify how the texture is applied to the mesh on a per-triangle basis.

The numbers indicate how many meters the entire texture will cover in the texture’s horizontal and vertical axes.

PROJECTED <x_scale> <y_scale> PROJECTED 4000 4000

BUMPY

X-PLANE 802: This command specifies how “bumpy” a terrain acts if the plane taxis on it. X-Plane’s terrain bumpiness is implemented by adding a pair of sign waves to the elevation of each terrain patch; as the plane taxis over the terrain, each wheel moves up and down. You can specify the frequency of bumps and the height difference.

Frequency parameters are the number of bumps per meter divided by 2PI. Amplitude is the displacement up or down in meters.

If this command is omitted, X-Plane’s default bumpiness is used. This is a displacement of +/- 0.025 meters vertically and a frequency of 0.16 meters and 0.04 meters for the two sets of sign waves.

BUMPY <freq 1> <amp 1> <freq 2> <amp 2> BUMPY 1.0 0.025 4.0 0.025

WET

X-PLANE 802: This command declares terrain to be wet. Without this command, all terrain is land. When this command is added, the terrain behaves like water. This command only affects the physics model; visually the terrain is rendered as normal. This command does not cause the terrain to change color to orange at sunset, for example.

WET

COMPOSITE_BORDERS

X-PLANE 820: Normally when you have a separate border alpha texture, X-Plane looks at the S&T coordinates of each vertex and applies thet mask explicitly. (If S&T coordinates are needed for the basic terrain, they are read first – see the bottom of this doc for more info.)

When you enable composite bordering, the bordering algorithm changes. The alpha of the terrain is compared to the alpha of the border texture and the terrain is only drawn where the alpha of the border texture is more than that of the terrain.

A typical usage of this is: the alpha mask of the terrain contains a high frequency pattern that picks pixels. The border mask is a horizontal gradient. The S border texture coordinate is then used to “fade out” the terrain by selecting less pixels over a distance. The T coordinate doesn’t matter.

This is different from a regular alpha blend in that pixels in the border area are either fully the drawn or not drawn at all. This means that you won’t get strange color effects from the blending of two pixels.

This is different from a regular mask effect in thata, because it is essentially one-dimensional, the border area can wrap a polygonal area arbitrarily.

COMPOSITE_BORDERS

BASE_TEX_NOWRAP

X-PLANE 820: This is the same as the BASE_TEX command, except that texture wrapping is turned off. With texture wrapping, a texture will naturally repeat. With wrapping off, the edge color is extended indefinitely.

You will need the no-wrapping tex commands when using orthophotos that tile; they guarantee that filtering does not introduce artifacts across terrain borders.

BASE_TEX_NOWRAP <file> BASE_TEX_NOWRAP base_tex.png

COMPOSITE_NOWRAP

X-PLANE 820: This is the same as the COMPOSITE_TEX command, except that texture wrapping is turned off. With texture wrapping, a texture will naturally repeat. With wrapping off, the edge color is extended indefinitely.

COMPOSITE_NOWRAP <file> COMPOSITE_NOWRAP base_tex.png

LIT_TEX_NOWRAP

X-PLANE 820: This is the same as the LIT_TEX command, except that texture wrapping is turned off. With texture wrapping, a texture will naturally repeat. With wrapping off, the edge color is extended indefinitely.

LIT_TEX_NOWRAP <file> LIT_TEX_NOWRAP base_tex.png

BORDER_TEX_WRAP

X-PLANE 820: This is the same as the BORDER_TEX command, except that texture wrapping is turned on. In the original texture commands, borders were assumed to be non-wrapped to allow version-800-style borders to work properly. If you need to have a border that can wrap with itself thsi command is needed.

BORDER_TEX_WRAP <file> BORDER_TEX_WRAP base_tex.png

PROJECT_ANGLE

X-PLANE 820:This command lets you control the angle from which the base texture is projected when projective texturing is used. X,Y,Z forms a vector to rotate project from, and a forms an angle to rotate around that projected vector om degrees. X Y and Z must form a vector of length one. Without this command, all textures are projected straight down.

This command can be used to avoid distortion and stretching when projecting a texture onto highly sloped terrain.

PROJECT_ANGLE <x> <y> <z> <a> PROJECT_ANGLE 1 0 0 0

COMPOSITE_PROJECT_ANGLE

X-PLANE 820:This command is the same as the PROJECT_ANGLE command except it affects the composite texture layer.

COMPOSITE_PROJECT_ANGLE <x> <y> <z> <a> COMPOSITE_PROJECT_ANGLE 1 0 0 0

PROJECT_OFFSET

X-PLANE 820: This command lets you offset the base point where a projected texture’s lower left corner is projected. While you cannot arbitrarily pick a point in space on the earth where the projection is tied to, you can offset it relative to the default projection scheme, allowing a texture to be used in a way where it will not line up with the normal usage. The offset is given in meters and offset the texure horizontally and verically.

The main use for this is to try to hide tiling effects in textures.

PROJECT_OFFSET <x> <y> PROJECT_OFFSET 2500 140

COMPOSITE_PROJECT_OFFSET

X-PLANE 820: This command is the same as PROJECT_OFFSET but for the composite layer.

COMPOSITE_PROJECT_OFFSET <x> <y> COMPOSITE_PROJECT_OFFSET 2500 140

SURFACE

X-PLANE 850: This command specifies the bumpiness of the terrain as one of the named surface codes. the naems are the same as in the OBJ8 ATTR_HARD command – see the OBJ spec for more info.

SURFACE <surface> SURFACE concrete

AUTO_VARY

X-PLANE 900: This command specifies that the terrain should be automatically varied (if X-Plane has this capability). Note that auto-variation requires pixel shaders to be enabled by the user.

AUTO_VARY

LOAD_CENTER

X-PLANE 920: This command estabishes that this texture will be used at a certain location, specified by the lat/lon taken to be the texture’s center. By also specifying theapproximate terrain size when placed (in meters) and textures size (in pixels), X-Plane will load the texture with variable resolution based on the general distance from the user to the texture. As the user flies, X-plane will periodically reload the texture.

LOAD_CENTER affects loading of the base, night, and composite texturse if they exist. A texture that uses LOAD_CENTER should only be referenced once by one art resource per DSF tile. For optimal performance, the texture should be in DDS format, so that reloads at lower resolution are fast.

LOAD_CENTER LOAD_CENTER 42.70321 -72.34234 4000 1024

How X-Plane Applies Terrain Types to the Mesh

X-Plane’s terrain mesh contains an arbitrary number of data planes. The first 5 numbers for each vertex represent the longitude, latitude, elevation, and normals (north and east fractions) for that point; the rest of the parameters (if present) are combined with the terrain type for that part of the mesh.

X-Plane’s basic algorithm is to use the parameters from the mesh by applying the rules below. For example this means that the texture coordinates for a border mask might be in items 6 and 7 of the mesh if there are no terrain texture coordinatse, but items 8 and 9 if there are, because terrain texture coordinates are higher priority if present.

1. If the base terrain texture is not projected, two coordinates are used as S and T parameters to map the base texture onto the vertex.
2. If there is a separate (border) alpha mask, two coordinates are used as S and T parameters to map the border mask onto the vertex.
3. If the terrain has a composite texture, one coordinate is used as a blend between the base and composite texture.

Library (library.txt) File Format Specification

Revision History:

• 2023-01-25: Updated for X-Plane 1200 – seasonal export commands
• 2019-08-12: Updated For X-Plane 1110 – SEMI_DEPRECATED, PUBLIC <date> status keywords for WED
• 2013-07-23: Updated For X-Plane 1040 – REGION_DREF command

Library.txt files are text files that sit directly inside a scenery package and tell X-Plane how to use the objects and other graphic resources in other parts of the flight simulator. Without a library.txt file a scenery package’s contents are used for its own DSF and ENV files, but with a library.txt file a scenery package can replace the models and artwork from other parts of the simulator.

Library files work by mapping virtual paths to files in the scenery package. One virtual path can be mapped to multiple graphic resources; in many cases X-Plane will randomly pick between the choices to create more scenery variety.

A region is any set of 1×1 DSF file locations; regions are specified as a series of rectangles along latitude and longitude lines. The union of all such rectangles forms a region.

Scenery packages are prioritized alphabetically within the Custom Scenery folder (all custom packages have priority over the default scenery which is in Resources/Default scenery). Within a scenery package, all objects have equal priority, but objects that are not regionalized must be first.

Objects and facades can be mapped to virtual paths multiple times. X-Plane will randomly pick among the definitions to increase variety. However other artwork types (terrain, beaches, roads, etc.) cannot be multiply mapped.

Library.txt files consist of a 3-line header, followed by commands. The first line is A or I – this code traditionally indicates line endings but is actually ignored by X-Plane. The second line is the file version number (currently 1200) and the third line is “LIBRARY”.

A
1200
LIBRARY

Library commands are interpreted from the top of the file down. This means that:

• Regions must be defined before their rects can be defined.
• Regions must be defined before they are used.

EXPORT <virtual path> <real path>

The export command maps the object from the current scenery package with the given real path (relative to the scenery package) to a virtual path.

If multiple export commands are provided within a scenery package for the same virtual path and the resource type supports multiple definitions, X-Plane picks randomly amongst all of the given definitions.

The use of an EXPORT command within a scenery package blocks out definitions of the virtual path from lower priority scenery package; EXPORT effectively replaces artwork.

You can use an object in your scenery package without putting it in a library. If an object is not in a library, it will not be used by any other package.

Note: The on-disk paths given in all EXPORT and related lines must come from within your own scenery pack. Paths outside your scenery pack (e.g., ../some-other-scenery-pack/myobject.obj) are not supported.

EXPORT_RATIO <quantity> <virtual path> <real path>

The export ratio command is just like the EXPORT command, except that the object is interleaved with other objects at a given ratio. (The implicit radio of regular “EXPORT” objects is 1.) You can use this command to control the mix of objects.

EXPORT_EXTEND <virtual path> <real path>

New To X-Plane 820: the EXPORT_EXTEND command works just like the EXPORT command except it does not inhibit the placement of objects from lower priority packages. These objects will be randomly mixed with objects from other packages. If another package of higher priority then uses EXPORT, it will block the EXPORT_EXTEND command. In other words, EXPORT_EXTEND merges with lower-priority packages, but the highest priority package has the choice to merge or replace.

REGION_DEFINE <name>

New To X-Plane 840: The REGION_DEFINE command begins defining a region. All following REGION_RECT commands will add to this region. You must define a region before you can use it.

Warning: region names are currently global. For this reason we recommend using a region name based on your package name and company, as well as the region itself.

REGION_ALL

REGION_ALL specifies the region being specified via REGION_DEFINE to contain the entire surface of the Earth. It is equivalent to REGION_RECT -180 -90 179 89

REGION_RECT <w> <s> <e> <n>

New To X-Plane 840: The REGION_RECT command adds a rectangular set of DSFs to the region that is currently being defined. The region will end up as the union of all rectangles. Rectangles must include whole DSFs; partial DSFs cannot be specified.

The boundaries are inclusive; REGION_RECT -118 32 -117 33 would include four DSFs: +32-118.dsf, +32-117.dsf, +33-118.dsf, +33-117.dsf.

REGION_BITMAP <file name>

New in 850: Starting in X-Plane 850 you can list ta 360×180 gray-scale PNG file consisting of black and white pixels. Black pixels will be considered out of the region and white pixels in the region. This replaces any previously defined rects for the region and should generally be used on its own. The bottom left of the bitmap represents the south pole and the international dateline; the top right represents the north pole and international dateline.

REGION <name>

New To X-Plane 840: The REGION command limits the EXPORT and EXPORT_EXTEND commands to only act in the named region. Before the first REGION command, objects are exported to the entire world. REGION limits objects placed in DSFs, but not objects placed by X-Plane.

EXPORT_EXCLUDE <virtual path> <real path>

New to X-Plane 850: The EXPORT_EXCLUDE command maps a file to the library just like the export command, but also excludes any export definitions in lower priority packs and below this export in this scenery pack.

Export-exclude is useful because it only “exports and blocks” lower priority definitions if its region requirement is met. This lets you define an export_exclude “override” in a scenery pack with a region, and then follow it with a world-wide export. The higher priority export_exclude directive will block out the world-wide case if and only if you are in the region. This lets you make a multi-region library in a single scenery pack.

EXPORT_BACKUP <virtual path> <real path>

New to X-Plane 860: The EXPORT_BACKUP command maps a file to the library just like the export command, except the particular file is treated as the lowest priority when finding artwork for a given virtual path.

The intention of this command is to allow a scenery package to provide minimal artwork for its DSFs while using other package’s artwork even if that other package isn’t higher priority. In other words, this maps a file as the artwork of last resort.

New to X_Plane 1200: The path mapping can optionally depend on the season, by replacing the existing commands EXPORT, EXPORT RATIO, EXPORT_EXCLUDE and EXPORT_EXTEND by the following:

EXPORT_SEASON <seasons> <virtual path> <real path>
EXPORT_RATIO_SEASON <seasons> <quantity> <virtual path> <real path>
EXPORT_EXTEND_SEASON <seasons> <virtual path> <real path>
EXPORT_EXCLUDE_SEASON <seasons> <virtual path> <real path>

They function just as their obvious legacy counterparts, save for the added argument which is a whitespace free, comma separated list of one or more of “spr sum fal win”. Seasonal and legacy export commands are mutually exclusive for any one given virtual path. Sufficient seasonal export commands must be given to cover all four seasons.

REGION_DREF <dataref> <comparison> <value>

New to X-Plane 10.40: Define a region in a library pack, and X-Plane will only load those art assets when datarefs written into the library.txt file evaluate to true. Datarefs can come from the sim or a plugin; all six conditionals (< <= == != > >=) are available.  If more than one REGION_DREF line is present, all must evaluate to true to use the region.

PUBLIC [date]

By default, all items in the library are public. You may explicitly mark them public by using this command. Also takes an optional date. Ex: PUBLIC 20170101

PRIVATE

This command is for Laminar Research internal use only. Once used, everything after it is private until PUBLIC is specified again.

DEPRECATED or SEMI_DEPRECATED

New in WED 1.7: Use of these commands will hide the item from the WED UI. Library items marked with the DEPRECATED command are already or will soon be removed and should not be used in scenery. SEMI_DEPRECATED is a weaker warning, used for items that will be removed further in the future. SEMI_DEPRECATED items will pass Gateway validation, while DEPRECATED ones will not.

X-Plane 10 Autogen Scenery File Format

X-Plane 10 introduces new autogen file formats.  This document presents detailed information on the formats of these files and is intended for programmers who are creating content-editing tools for X-Plane.

X-Plane 10 Autogen Overview

X-Plane 10 autogen art asset types are art assets designed to create a significant quantity of scenery using a formula and basic geometric information from a DSF file.  At the core of the autogen system is an autogen “tile” – that is, a rectangular area of texture placed over the terrain, with 3-d attached to that texture.

X-Plane 10 supports 3 autogen formats:

• Autogen points (.agp files) are single tiles placed at a specific lat/lon heading in a file.  Usage of autogen points is similar to placing an individual 3-d OBJ model, but the autogen point art asset can contain a ground texture, several objects, facades, and vegetation.  Thus the .agp allows for the placement of an entire scene in one location.
• Autogen blocks (.agb files) fill an approximately rectilinear 4-sided polygon with a 2-d grid of tiles.  Autogen blocks are used to create regular city blocks with varying size and slight variations in their side angles.
• Autogen strings (.ags files) follow the perimeter of an irregular polygon, placing strings of tiles along some or all of the sides.  Autogen strings are used to put autogen into irregularly shaped parts of cities and towns.

This document covers only the common aspects of all autogen files and the .agp format.

Basic Autogen Concepts

An autogen art asset defines one or more tiles.  Each tile is an individual textured rectangle with zero or more 3-d annotations drawn on top of it.  The annotations take the form of objects, forest vegetation placements, and faces.

The look of the annotations are defined by separate art files already used in X-Plane (OBJ for models, FAC for facade polygons and FOR files for vegetation); the autogen file defines the placement of the annotations on the base tile and the texturing/shading properties of the base tile.

The autogen base tile may be omitted; in this use case the autogen tile can still serve as a vehicle for arranging several objects in correct relative position.  When the base tile is omitted, the art asset still includes texture coordinates as if the tile exists, but X-Plane will skip tile processing entirely, improving performance.

The base tile is textured using the standard shader; standard shading options apply including tiling and detailing.

Texture coordinates in autogen tiles are referred to in pixels.  There are two things to note about this scheme:

First, X-Plane gets the size of your base tile texture (in pixels) from the autogen text file, not from the actual image on disk!  This is done because the image is loaded much later than the autogen is built – this is part of X-Plane’s multi-core loading strategy.

Therefore if you resize the texture, your autogen will not need to be edited; the placement of autogen annotations is done in a proportional manner, using the declared texture size.  (If you widen your texture, adding extra space you will need to change the declared size of the texture because this is not a proportional resizing of your texture.

Second, you annotate autogen in pixel coordinates even if the tile is hidden and the tile texture is blank.  This is not a problem because you can declare any texture size you want – for all practical purposes the texture size simply forms a grid on which to work.

Autogen Point Commands

TEXTURE_SCALE <width pixels> <height pixels>
TEXTURE_WIDTH <meters>

These commands define the scaling of the base tile texture (the albedo of the shader provided to the AGP).  The texture is assumed to be width pixels and height pixels; the texture is then mapped into the sim so that width_pixels is mapped to meters and the aspect ratio of the pixels are square.  Both of these directives are required.

VEGETATION <path for .for>
OBJECT <path for .obj>
FACADE <path for .obj>

These commands establish the art assets to be used for vegetation, objects and facades.  The facades and objects are referred to by zero-based index based on the order of the load directives in the AG file.  Only one forest file may be specified.  No art asset loading directive is required.

HIDE_TILES

This directive instructs X-Plane to not render the base tiles at all.  If you are using autogen points as a container for groups of objects, use this directive, not a transparent texture, to hide the tile.

TILE_LOD <distance in meters>

This sets the distance at which autogen tiles fade out from view.  The default is 20 km.

LAYER_GROUP <offset index> <group name>

This sets the layer group in which the tiles appear; the default group is “footprints”, a new group in X-Plane 10 that occurs after airports but before roads.

SLOPE_LIMIT <min pitch> <max pitch> <min roll> <max roll>

If present, this sets a set of slope limits for terrain pitch and roll at the point where the AGP is placed.  If you imagine the AGP as an airplane placed at the location and heading specified on the DSF, the limits represent the maximum the plane could pitch up and down and roll to the right (negative numbers would be nose down and roll left).

This directive is only considered when an autogen point is placed by library path!  When an autogen point is placed by library path, slope limit screens out some objects, and may result in no autogen point being placed.  When an autogen point is placed by a direct relative path, it is always placed, regardless of slope.

Commands for Specifying Tiles

Autogen points can have more than one tile; when more than one tile is present, a random one is picked by the sim for variety.  A tile directive defines a tile; all commands that follow apply to that tile until the next tile occurs.

TILE <left pixel> <bottom pixel> <right pixel> <top pixel>

This defines the tile texture.  All annotations that occur must be within the bounds of the tile.  Autogen point files must define at least one tile.

ROTATION <n>

If present, the rotation directive specifies a new orientation for the tile; n is the number of 90 degree CCW turns to make (and defaults to 0).  In their default orientation, an autogen point placed at heading zero in a DSF will have its bottom edge aligned to the north.  Since this orientation is somewhat counter-intuitive compared to other X-Plane art assets, an author may want to use ROTATION 2 to rotate the tile.

ANCHOR_PT <x pixel> <y pixel>

If present, this defines what point on the tile texture will be aligned to the DSF placement point.  If not present, the center of the tile is used.

GROUND_PT <x pixel> <y pixel>

If present, this defines what point on the tile texture will be used to align the tile with the ground vertically.  If not present, the center of the tile is used.

CROP_POLY <x pixel> <y pixel< [...<x pixel> <y pixel>]

If present, this defines a clockwise convex polygon that is used to crop the base tile.  The crop polygon should include at least 3 point pairs.  If omitted, the tile is not cropped.

Commands That Add Annotations to a Tile

All annotations are given using pixel coordinates, and those coordinates must be within the tile that was most recently specified with a TILE directive.

OBJ_DRAPED <x pixel> <y pixel> <heading> <index> [<lo> <hi>]
OBJ_GRADED <x pixel> <y pixel> <heading> <index> [<lo> <hi>]
OBJ_SCRAPER <x pixel> <y pixel> <heading> <index> <min> <max> <step> [<lo> <hi>]
OBJ_DELTA <x pixel> <y pixel> <heading> <height offset> <index> [<lo> <hi>]

These commands add an annotated OBJ model to the autogen.  The object is positioned with its origin matching <x pixel> and <y pixel>, with a heading matching the autogen point, plus a clockwise offset of <heading> degrees.

If present at the end, lo and hi are index numbers (1-6) matching X-Plane’s six levels of object rendering.  The object is randomly placed more frequently as the rendering setting goes from <lo> to <hi>.  So the indices 2 4 would mean that the OBJ is never seen at setting 1, is seen rarely a setting 2, somewhat at setting 3, and always at setting 4, 5 and 6.

X-Plane provides three vertical alignment behaviors for object placement:

• OBJ_DRAPED places the object on the terrain directly below the object’s origin.
• OBJ_GRADED places the object at the elevation of the terrain on the tile’s ground point.  If the OBJ_DELTA syntax is used (X-Plane 10.10 and later) a vertical offset in meters from the height of the terrain at the tile’s ground point can be provided.
• OBJ_SCRAPER places the object is placed at the terrain height at the tile’s ground point.  Then, if the autogen element has an AGL height associated with it in the DSF, the object is moved up (for every amount of the AGL past <min> by <step> meters, not to exceed the delta of <max> – <min>).  This scheme matches the placement scheme for facade scrapers – see the facade specification for more details.

Note: autogen points do not support an AGL height in a DSF.  Therefore the OBJ_SCRAPER directive will act like the OBJ_GRADED directive.  The documentation of OBJ_SCRAPER is provided for reference, but is only useful for autogen string and block elements.

Designer’s note: the intention of the ground point is to allow multiple objects in a single AGP to be vertically sinked.  To set this up: locate the ground point at the same location as the “master” object and then set all objects (the master and slave objects) to be graded.  The master object will sit on the ground, and the vertical relationship between the master and slaves will not change.

FAC <index> <height> <x pixel> <y pixel> [...<x pixel> <y pixel>]

This places a facade of <height meters> – the list of points defines the clockwise boundary of the facade on the texture.

TREE <x pixel> <y pixel> <heading> <width> <layer>

This places a single autogen tree.  The tree is placed at the pixel location specified and rotated by the amount of the AG tile and then additionally clockwise by heading.  The tree will be scaled to be “width” meters wide; a tree will be randomly picked from “layer” in the forest file.

TREE_LINE <x start> <y start> <x end> <y end> <layer>

This  builds a line of trees from the start pixel to the end pixel, randomly picking trees from the layer; the spacing approximates the spacing provided by the forest files.