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
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>
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.
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.
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:
ROAD_TYPE <subtype> <width> <length> <texture> <red> <green> <blue>
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:
SEGMENT <near lod> <far lod> <start lat> <start vert> <start tex> <end lat> <end vert> <end tex>
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:
WIRE <near lod> <far lod> <lateral offset> <vertical offset> <droop ratio>
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:
OBJECT <name> <lateral offset ratio> <rotation> <force on ground> <placement frequency> <placement offset>
[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.
[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:
SEGMENT_HARD <index> <lod> <lod> <dx1> <dy1> <s1 <dx2> <dy2> <s2> <surf>
[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.
CAR <reverse> <lateral offset> <velocity> <spawn ratio> <traffic type>
[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>
[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.
[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.
[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>
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