BigWorld's source code ships with support for SpeedTreeRT 4.2 turned off by default. A few steps need to be followed in order to enable support in the game client and tools:

For a SpeedTree to be available in World Editor, or to be loaded from a chunk file into a space within the game client, the following resource files need to exist in the resources tree:

For each tree, these files should reside in the same folder. More than one tree can coexist in the same folder, as long as no filename clash occurs.

For performance reasons, we assume that all trees use a composite map for the frond, leaf, and billboard textures. For details on how to have a tree to use composite maps, see the SpeeTreeCAD's User Manual.

To take advantage of SpeedTreeCAD's alpha noise cross-fading feature (a fundamental feature which use we highly recommend), you will also need an accompanying .texformat^[1] filefor the composite texture map, or an appropriate wildcard entry in <texture_detail_levels>.xml. For details, see Level of detail.

Optionally, you can have a SpeedWind.ini file in this same folder if you require finer control over how this tree wind animates. For details, see Wind animation.

Once the resource files are in place, trees are ready to be used within World Editor. To insert a tree, either drag a .spt file from the Asset Browser panel^[2] into the viewport, or select the desired .spt file and press Enter.

Once a tree has been added, it can be selected, moved, rotated, and scaled like any other model in World Editor. You can do this interactively (see Mouse controls) or by editing the trees' properties in the Properties panel (see Properties panel). In the Properties panel, you can also edit the name of the .spt file and the seed number used to generate the tree geometry. The results of editing a tree's properties can be immediately previewed in the viewport.

If a tree cannot be loaded during chunk loading then a red box model will be rendered in its place. The box can still be manipulated and most of its properties edited with the exception of its seed. Any changes will be saved and restored if that tree is loaded in the future.

BigWorld uses SpeedTree's new SpeedWind library to animate trees swaying to the wind. SpeedWind's parameters can be tuned and previewed from within SpeedTreeCAD, and then saved as a .ini file. This file can then be loaded into BigWorld's 3D engine to control how trees animate.

A global .ini file is used by default for all trees. Optionally, a unique SpeedWind.ini file can be tied to a specific tree, by placing it in the same folder as the .spt file (the name of the file is required to be SpeedWind.ini). If neither file is present, then SpeedWind's engine will be setup with its default parameters.

Although SpeedWind's parameters define how a tree should animate given a wind of certain direction and strength, the actual wind's direction and strength fed into SpeedWind's engine is provided by BigWorld's dynamic weather system, conveying a convincing and immersive experience for the player.

BigWorld's 3D engine fully supports SpeedTree's LOD model. Branches and fronds switch detail levels discretely, while leaves and billboards LODs cross-fade according to the distance to the camera.

By default, the actual LOD level of a tree — a value that ranges from 0 (minimum detail) to 1 (maximum detail) — is a linear function based on the distance from the tree's origin to the camera's eye position. The lodFar and lodNear parameters define the distance interval within which the trees' LOD levels will vary. In the default LOD mode, the LOD function is the same for all trees.

Optionally, you can rely on SpeedTree's engine to compute the LOD level for each tree based on parameters contained in the .spt file (which can be edited from SpeedTreeCAD). Roughly speaking, they work in the same way as explained above, but with specific near and far values for each tree. This allows a more fine-grained control of LOD transitions, and a better match between what is previewed on SpeedTreeCAD and what is rendered on the tools and the client. The only drawback is that relying on SpeedTreeRT for the LOD computation is a bit slower than letting BigWorld do it.

You can switch between this two LOD modes by editing the lodMode parameter in SpeedTree's XML file (for details, see XML file) or interactively, via watchers (for details, see Watchers). The parameters lodNear and lodFar are also accessible this way.

The lodOverlap parameter defines how much overlapping should happen during the cross-fading of LOD levels. The valid range goes from 0 to 2. The default value is 1. This parameter is also accessible via XML file and watchers.

Leaves and billboards, when phasing in or out their LODs, cross-fade their alpha test values in order to smooth level transitions. This technique requires composite texture maps with homogeneous noise baked into the alpha channel and pre-generated mipmaps. Also, BigWorld's auto mipmapping generation should be disabled for this texture map.

To disable the automatic generation of mipmaps in BigWorld, you will need to setup a .texformat^[3] file for each tree's composite texture map, which is illustrated below:

<root>
  <mipCount>       -1    </mipCount>
  <horizontalMips> true  </horizontalMips>
  <mipSize>        0     </mipSize>
</root>

Example .texformat file

The example above configures the following:

A more general way of achieving this is by adding a wildcard entry to <texture_detail_levels>.xml. The entry should match all composite maps used by SpeedTree, and define the same attributes shown above. An example of a wildcard entry is illustrated below:

<detailLevel >
  <prefix>         speedtree </prefix>
  <contains>       composite </contains>
  <mipCount>       -1        </mipCount>
  <horizontalMips> true      </horizontalMips>
  <mipSize>        0         </mipSize>
</detailLevel >

Example <texture_detail_levels>.xml entry

For details on how to create texture maps with alpha noise and pre-generated mipmaps, see SpeedTreeCAD' User Manual.

The first time a tree is loaded, BigWorld uses the collision geometry specified in the .spt file to generate the BSP trees that will populate the collision scene in a space. In the game client, you can preview these BSP trees by enabling the SpeedTree/BSP watcher (for details, see Watchers). In World Editor, enable the General Options panel's Show list box's Scenery → BSP item (for details, see General Options panel).

If the engine has write access to the resource path, then a cache of the BSP tree will be saved, to speed upload time in the future. This cache file will be re-created whenever the .spt file is modified.

Once a tree's BSP tree has been inserted into the collision scene, it will be used in all collision queries in the engine, including line-of-sight, navigation paths generation, static lighting, and more. When loaded from within World Editor, if a tree has no collision geometry defined, then a temporary BSP tree in the shape of a box will be created, to allow the world builder to select and interact with the tree. This temporary BSP tree is not cached, and will not be created when the tree is loaded into the game client.

For details on how to define a tree's collision geometry, see SpeedTreeCAD's User Manual.

Normally, the server is not built to use SpeeTreeRT, and requires the BSP files to be present in the resource path in order to load SpeedTrees into the collision scene. The recommended approach is to check all SpeedTree BSPs into the repository so that they will be accessible to the server. When running the server, if the associated BSP file is not available when loading a SpeedTree, then it will fail to load (the chunk will be loaded successfully, though).

All game-specific settings related to rendering SpeedTrees are defined in a XML file, which actual name is defined in resources.xml (for details, see the document Client Programming Guide's section Overview→ Configuration files → File resources.xml) , under the system/speedTreeXML tag, and defaults to speedtree/speedtree.xml.

This file is read upon initialisation of BigWorld's 3D engine. For details on these tags, please see inline comments in fantasydemo/res/speedtree/speedtree.xml.

In both the game client and World Editor, several watchers (for details, see the document Client Programming Guide's section Debugging → Watchers) are available to instantly customise and debug the behaviour of SpeedTrees.

The list below describes them (all watchers listed are prefixed by SpeedTree/):

The watchers LOD Mode, LOD Near, LOD Far, and LOD Overlap are read from SpeedTree's XML file when the engine is initialised. Modifying them via WebConsole's ClusterControl module (for details, see the document Server Operations Guide's section Cluster Administration Tools → WebConsole) does not modify the contents written into the file.

The list below describes some errors that you might come across when implementing SpeedTree: