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.