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.
- 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.
- 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.
- If the terrain has a composite texture, one coordinate is used as a blend between the base and composite texture.