Forest (.for) File Format Specification

Revision History:
	12/26/07   Updated for X-Plane 9
	 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).

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

A
800
FOREST

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 filename 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 framerate.

[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 intepretted 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 assymetric 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.

Example file:

A
800
FOREST

# 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.
SPACING 50 50
#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

SKIP_SURFACE water