Revision History:
	 3/20/12   Updated for X-Plane 1000
	 12/26/07  Updated for X-Plane 900
	 1/8 /06   Updated for X-Plane 860
	 7/19/06   Initial Draft

A .for file describes how to build 3-d trees out of a texture. Forests are built by creating a polygon in a DSF file and using a .for file for the definition. The DSF polygon may have multiple windings, allowing holes to be cut out of the forest. The DSF polygon needs only lon/lat pairs to define the boundary. The DSF parameter is a number from 0 to 255, specifying the relative forest density (255 is most dense).

The forest file is essentially a set of rectangles describing where in the texture each tree resides.

In X-Plane 10, some of the randomization for forests can be specified via perlin noise.  The parameters are four pairs of amplitude and wavelengths – the amplitude is a ratio from 0 to 1 and the wavelength is in meters.  For example:

choice_params 500 0.75 10 0.25 0 0

sets up a perlin noise pattern to pick tree groups with the groups mostly changing about every 500 meters.  The second wave with 10 meters and 25% power helps “muddle” the edge of the transitions.

In X-Plane 10, a forest can be rendered by filling, drawing trees along lines, or putting a single tree on each polygon point.  See the DSF usage specification for more info on encoding the polygon parameter.

A .for file has a standard X-Plane header:


The rest of the .for file contains commands that specify the forest file. Lines starting with a # are comments.

TEXTURE <filename>

This defines the texture to be used for the forest. The entire forest must be built out of a single texture file. The file name is specified relative to the .for file, just like OBJ8 files. Lit textures are not allowed for forests.

LOD <max lod>

This defines the farthest distance the trees can be seen. Lower values cause forests to disappear faster but result in faster frame rate.

[X-PLANE 9] In X-Plane 9, the LOD command is ignored; X-Plane calculates the viewing distances for all forests based on user settings. X-Plane will attempt to draw the forest for as long of a distance as possible, with a density approaching what is specified in the scenery file.

SCALE_X <x scale>

SCALE_Y <y scale>

These define the coordinate scale that is used to define the texture coordinates for the forest. This does not have to be the same as the size of your texture. Basically all texture coordinates are interpreted as if on a texture of these dimensions and then fit to the actual texture. (This command is provided to allow you to easily input numbers read off Photoshop rather than working in fractions.)

SPACING <x spacing> <z spacing>

This defines how far apart the trees are in meters. Smaller numbers pack the forest tighter and cause the sim to run slower (since more trees must be used to fill an area. The dimensions are in meters.

RANDOM <x spacing> <z spacing>

This defines how much each tree may deviate from a perfect grid filling. So a random of 0 0 means a perfect grid. The spacings are in meters.

TREE <s> <t> <w> <h> <offset> <frequency> <min h> <max h> <quads> <type> <notes>

Each tree command (there can be more than one) defines a tree. Each tree is defined by a quad in the texture. The parameters are:

  • s – the horizontal texture coordinate of the lower left corner of the rectangle.
  • t – the vertical texture coordinate of the lower left corner of the rectangle.
  • w – the width of the tree texture rectangle.
  • y – the height of the tree texture rectangle.
  • offset – the distance from the left to the center of the tree in pixels.
  • frequency – the percentage of the time this tree is used. The sum of all percentages of all trees must add up to 100%.
  • min height – the minimum height of this tree type in meters.
  • max height – the minimum height of this tree type in meters.
  • quads – the number of polygons used to make the tree – can be 1 to 4.
  • type – there are multiple types of trees in each forest, numbered starting at 1. Each type of tree is individually placed, so you can put down trees and then shrubs in the same area.

Each tree is built from 1-4 quads. The texture dimensions define the aspect ratio and texture used. The quads are scaled based on the possible height range. You can specify where the center of the tree is – it doesn’t have to be the center of the texture, allowing for asymmetric trees.

[X-PLANE 9] X-Plane 9 limits the number of quads to two at most, and will reduce a tree to one quad based on distance from the viewer and rendering settings. So the number of quads parameter should be considered a maximum. (X-Plane 9 will not promote a one-quad tree into a two-quad tree.)

SKIP_SURFACE <surface type>

[New to 860:] Starting with X-Plane 860, you can use one or more SKIP_SURFACE directives to tell X-Plane not to put trees down on a certain surface type. The legal surface codes are the same ones allowed for OBJ8 ATTR_hard commands. You can use this command more than once to keep trees off many surface types.

Warning: because X-Plane builds both trees and other scenery types while you fly, in small pieces, you cannot use SKIP_SURFACE to keep trees off of scenery elements that are built during flight. (This is all scenery types except terrain.) For example, if you use SKIP_SURFACE concrete to try to keep trees off of roads, only trees that are “planted” by X-Plane after a road is bulit will be properly excluded.

Y_QUAD <left> <bottom> <width> <height> <offset_center_x> <offset_center_y> <width> <elevation> <rotation>

[New to 1000:] X-Plane 10 allowsf or an optional vertical base quad in a tree.  The UV map is established via a quad (from the lower left corner) – the pixel offset establishes where the tree trunk sits on the 2-d quad.

The tree has a width parameter specifying the width of the quad (the aspect ratio is defined by the UV map) and an elevation for how far off the ground the quad is.  Both of these parameters are described in the unit of pixels of the vertical billboard.  In other words, if the vertical billboard of a tree is 100 pixels tall and you specify an elevation of 15 pixels, the horizontal billboard is always 15% of the way up the tree (whatever its final height is).  The motivation behind using vertical-billboard pixels here is to allow the UV map resolutions of the horizontal and vertical quads to be different; by sizing the horizontal tree in terms of the vertical one, a tree of fixed proportions can be built.

GROUP layer percent

[New to 1000:] X-Plane 10 can group trees into clusters – the groups should be consecutive in the file.  The layer parameter is the same as the layer of a tree itself – and all trees in a group should share the group’s layer.  The percentage of all groups should add up to 100%.

X-Plane will select trees by group when perlin noise is used, creating forest clusters.  When trees are in a group, the percent occurence of all trees within a single group should add up to 100%.

DENSITY_PARAMS <perlin params>

[New to 1000:] this changes the pattern of tree density to follow perlin noise.  Note that the density is also affected by the polygon forest density (0-255) in the DSF, so this parameter effectively only changes the shape of trees for partial density forests.

CHOICE_PARAMS <perlin params>

[New to 1000:] this changes the pattern of tree selection to follow perlin noise.  Combined with forest groups, this can be used to organize a forest into tree stands of one group of trees or another.

HEIGHT_PARAMS <perlin params>

[New to 1000:] this changes the randomization of height from truly random tree height variance to perlin noise, which can create clusters of height changes.


[New to 1005:] this disables shadow casting for the forest.

Example file:


# Conifer cold wet
#This tells us the bitmap that will be used for these trees.
TEXTURE forest.png

#This tells us how far away trees disappear - in this case 5 km.
#(This is a bit too soon - 10 km or 20 km looks better.)
LOD 5000

#This defines the texture size for the coordinates given below.
SCALE_X 1024
SCALE_Y 1024

#Tree spacing: place a tree and shrub every 20 meters.
#Vary their placement by up to 10 meters in any direction.
RANDOM 20 20

#low-left coord tex size center percentage    ----height----
# tree  s 	t 	w 	y 	offset occurrence    	min 	 max  	quads 	type 	name
TREE 	44	896	52	127	25	12.5		10	28	1	1	connifer 1
TREE 	194	896	44	127	22	12.5		10	28	2	1	connifer 2
TREE 	238	896	65	127	32	12.5		10	28	1	1	connifer 3
TREE 	443	896	66	127	33	12.5		10	28	3	1	connifer 4
TREE 	584	896	77	127	39	12.5		10	28	1	1	connifer 5
TREE 	712	896	62	127	32	12.5		10	28	2	1	connifer 6
TREE 	777	896	61	127	29	12.5		10	28	1	1	connifer 7
TREE 	840	896	72	127	36	12.5		10	28	2	1	connifer 8