Vector Network (.net) File Format Specification

Revision History:
    12/26/07   Revised for XP900
     7/13/06   Revised for XP850
     9/ 8/05   Revised for XP820
    11/19/04   Initial Draft

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 1024x1024 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>

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