An Autogen String art asset is an art definition to place a large number of tile-based scenery buildings around a polygonal shape. AG strings are designed to cover highly irregular shapes (including shapes with holes for lakes) in a “best-fill” manner.
The AG string contains:
- A number of tile definitions – X-Plane picks from the tiles to place autogen.
- Spelling and selection rules that specify which tiles are used under which use cases.
- Global properties affecting use of the art asset.
Since the AG String is a type of autogen, all autogen directives may be used.
DSF Usage
Autogen strings are specified as a DSF polygon feature. The sequences of contours in the polygon are treated as independent poly-lines (e.g. 3 points in a contour sequence define two lines) such that:
- The outermost winding is counterclockwise; holes in the polygon are clockwise.
- No edges overlap, and every winding is fully closed (two adjacent windings share and duplicate a vertex).
- Contours are ordered so that tile-spawning contours are first in the DSF.
The polygon parameter low 8 bits define the number of contours that have tiles attached to them. Contours are ordered so that the “tile-spawning” contours come first.
The polygon parameter high 8 bits are the height of any buildings within the AG element divided by four, for a maximum height of 1024 meters (in 4 meter increments).
Tiles are placed in the contour order from the DSF file; it is recommended to try to keep windings as close to a counter-clockwise circulation as possible.
AGString-Wide Properties
CREASING_ANGLE left-crease-degrees right-crease-degrees
The crease angle specifies how many degrees the boundary of the AG-polygon must turn for a vertex in the polygon boundary to be considered a “corner”. The assumption is that for very small angle changes, the poly-line is to be considered a single continuous side. The crease angle is a change in heading of the edge, first for left turns, then right turns. The default crease angle is 30 degrees for both.
FILL_LAYER layer-number
The fill layer directive specifies which layer of the .for file associated with this autogen is used to flood-fill the interior of the AG string with trees after tile placement completes. Trees are selected randomly from this layer.
HIDE_TILE
This directive causes the ground tiles to not be drawn at all. If you do not need ground tiles (e.g. the ground markings are accomplished via OBJ draped textures) then HIDE_TILE is much more efficient than using a 100% alpha clear ground tile.
SHARE_Y
Normally the elevation for buildings on the ground (for graded autogen buildings) is picked on a per-tile basis, using the GROUND_PT directive. If SHARE_Y is enabled, then for every atomic spelling of tiles that is placed, all graded buildings in the atomic spelling share the ground point of the first tile that is placed.
The intention of this directive is to let you model a single building across multiple tiles in parts and get the same vertical placement for all graded buildings.
Tile Specification Properties
These properties add additional per-tile data, specific to AG Strings, in addition to what is legal in all autogen.
TILE_ID id
This specifies the ID number of the next tile, for spelling purposes. If TILE_ID is omitted, tiles are assigned integers in file order starting from 0. TILE_ID is recommended to let authors understand which tile is which.
TILE left bottom right top
This defines a new tile, whose coordinates are specified in texture pixels. Annotations and markings must follow the tile they apply to.
STOP_PT s t
This defines a “stop-point” – that is, a barrier that may not be penetrated. When the tile is placed, it will be moved so that the stop point is within the DSF polygon; when a tile is placed, it will be slid so that it does not cover previously placed stop points.
If a tile cannot be placed without a stop point being out of bounds (e.g. the stop point would be in a lake) the tile is skipped. Use stop points to ensure that 3-d elements are not covered or under the road grid.
PIVOT_LEAD_PT s t
PIVOT_TRAIL_PT s t
The pivot lead and trail points define connection points when a 3-tile articulated corner is used. The three tiles will be placed so that, counterclockwise, the previous tile’s lead point will be co-located with the next tile’s trailing point and the angle change between the first and second tile is the same as the second and third tile.
Tile Selection Properties
The autogen string’s tiles are placed by:
- Placing corner tiles in the DSF contour order, counter clockwise along each contour.
- Placing edge tiles along the sides of the contours filling in space and
- Placing “caps” at the end of each side to cover the last tile.
GROUP group-id tile-id [tile-id … [tile-id]]
Tiles may optionally be placed into groups for selection – each group defines one group with a set of tiles. A tile may be in zero, one, or many groups. Group IDs must be positive integers.
Corner Selection Properties
The corner selection properties specify that a tile may be used to fill in the corner of a polygon. Tiles can be used in more than one corner directive, or in corner and edge directives.
CORNER angle-min-degrees angle-max-degrees id1 [id2 id3]
This specifies that tile id1 (or the three-tile id1,id2,id3 triplet) form a corner, as long as the angle of the corner is within the degree range specified.
All angles are measured in degrees of turn when walking along the outside of the DSF contour; therefore a right turn (a reflex corner) is a positive turn. A simple square block has four turns of -90 each.
CORNER_LEN min-len1-meters max-len1-meters angle-min-degrees angle-max-degrees min-len2-meters max-len2-meters group-id tile-id1 [tile-id2 tile-id3]
This operates just like corner, but with additional restrictionss for selecting the tile: if group-id is not zero, the previous corner that was placed must be within group-id, or this corner must be first. Len1 and len2 specify ranges in meters that the previous and next edge must fit within. Thus CORNER_LEN gives the author more certainty about when a corner is used.
Note: the length of the side is measured as the length of a single line segment, even if the preceding contour has several small segments all below the crease angle. Thus CORNER_LEN will only work when the DSF polygon is made of a few large segments, not a long string of small angle changes.
CORNER_PAIR angle1-min-degrees angle1-max-degrees length-min-meters length-max-meters angle2-min-degrees angle2-max-degrees group-id tile-id1 [tile-id2 tile-id3]
CORNER_PAIR works like CORNER_LEN, except that it places two consecutive corners. The angles are for the first and second corner preceding counter clockwise, and the length is the length of the single side between them. Thus this lets authors place pairs of matched corners where they are close together in expected situations.
ATOMIC_SPELLING_CORNER min-len1-meters max-len1-meters angle-min-degrees angle-max-degrees min-len2-meters max-len2-meters group-id tile-id1 [tile-id2 tile-id3]
This works just like CORNER_LEN with one special behavior: tile placement is “atomic”. Atomic placement means that if not all three tiles can be placed, then no tiles are placed, and a different corner is tried.
The intention of atomic corners is to allow authors to build 3-tile articulated corners where the art assets do not look correct without all three tiles. In a normal corner, any one tile may be eliminated, e.g. due to a collision with an interior hole in the polygon. With an atomic corner, the entire corner acts as an indivisible atom – it is either entirely placed or entirely skipped.
CORNER_ORDER index1 index2 index3
This command can follow any corner directive that specifies 3 tiles and indicates the order that the tiles are placed. Normally the tiles are placed middle, preceding, trailing, but this order can be customized, e.g. if the order is 2 1 0 then trailing, middle, then preceding are used.
The placement order affects two things: the tiles overlap based on placement order – the first tile placed is on the bottom. Second, the first tile placed defines the ground point for shared_y autogen.
PRIORITY_MARKER_CORNER
This directive specifies a group of corners to be considered. All corners within the priority group have equal probability of appearing, but one will be tried first before a corner from a lower priority group is considered.
Edge Selection Properties
SPELLING tile-id1 [tile-id2 […tile-id-n]]
This specifies that a list of tiles (specified by ID) in order will be used to fill an edge. Once all corners are placed, X-Plane randomly selects spellings to fill the edges with the best fit it can find. Spellings allow you to select adjacency to control the randomization process.
An autogen element should contain spellings with a range of lengths to fit various sized edges.
ATOMIC_SPELLING length-min-meters length-max-meters group-id tile-id1 [tile-id2 […tile-id-n]]
An atomic spelling functions like a spelling with the following extra behavior:
- The spelling is either entirely placed or discarded – individual tiles from the spelling don’t appear on their own due to collisions with other tiles.
- The spelling is only considered if the previously placed tile is within group-id, this is the first spelling of the side, or the group-id is 0.
- The length of the side (the single segment, not poly-line) is within len-meters.
Like atomic corners, the intention of atomic sides is to form multi-tile buildings that appear as a whole or not at all.
PRIORITY_MARKER
This defines a group of spellings that will be considered first (randomly within the group) before backup spellings are considered.
Cap Selection Properties
CAPS tile-id [tile-id [… tile-id]]
This marks a set of tile IDs as being eligible to be a cap. Caps are small tiles placed at the end of edges to cover the last tile placed. Caps are optional – if no cap is found, no cap is used. More than one CAPS directive may appear to specify caps.