Speed Tree

Document Summary: How to use SpeedTree Actors in the editor.

Document Changelog: Created by Ryan Brucks.

Overview

This document serves a guide to bringing SpeedTree content from the SpeedTreeCAD tool into Unreal Engine 3. Specific functionality of SpeedTree actors within UE3 will be described. This includes how to import trees, how to add them to the world, how to create and assign materials, and what properties you can modify.

This document also includes instructions and scripts needed for exporting custom leaf meshes from 3DS Max and into SpeedTreeCAD.

Importing Speed Trees

Importing SpeedTrees into UnrealEd is as easy as importing any other file type. Choose the menu option File->Import, change the file type to "SpeedTree (*.spt)", and browse to the spt file you want to import. Be sure that this spt file has been exported from SpeedTreeCAD for real-time use. Doing this creates the composite map, generates billboards, and sets the texture coordinates in the spt file to use the new composite map. Importing a tree that hasn't been exported from SpeedTreeCAD won't crash, but you will probably run into a few problems with textures, and you won't have any billboards.

Double-clicking on the icon of the SpeedTree in the browser window will bring up the editor for that SpeedTree. Major editing of the tree should still take place inside of SpeedTreeCAD, but within UnrealEd, you can change the random seed for the tree, sink the tree into the ground and change the LeafStaticShadowOpacity.

LeafStaticShadowOpacity is the chance that the a given leaf will block a lighting trace. When at 1 (the default), all traces hit the leaves and the shadow will be exactly the shape of the leaves. Setting it to 0.5 makes it less likely for light traces to hit leaves; therefore, some light will penetrate and the darkest part of the shadow come from the center of the tree where there are more leaves overlapping and thus more chances for light traces to hit leaves. Setting it to 0 would make the leaves cast no shadow. Different values will work better for different trees here, so it’s a good idea to try a few settings.

The editor window is also where materials are applied to the SpeedTree, much like how materials are applied to static meshes. Importing textures for the tree and making the materials is covered in depth in the Setting Up Materials section. Once the materials are created, they are applied to the tree by assigning them to the materials slots on the tree. Material assignments can also be overridden per placed SpeedTree instance. There are slots for branches, fronds, leaves, and billboards. Often, the same material is used for leaves, fronds, and billboards. There are 4 separate slots in case things like normal mapping, self-shadowing, etc. are to be used on only parts of the tree. SpeedWind parameters are now exposed for the tree. What these parameters mean in regards to the wind effects on the tree is thoroughly covered in the SpeedTreeCAD user reference section on SpeedWind.

Setting Up Materials

SpeedTrees in Unreal Engine 3 take advantage of the material editor built into UnrealEd to allow for all of the material effects possible on other surfaces to be on the trees as well. The materials on the various parts of the tree can be as simple or complicated as you want. Basically, materials for the SpeedTrees are created the same way as any other material. Import the textures, make a new material, and hook the corresponding texture outputs to the material.

Composite Maps and Billboards

Importing Composite Textures

SpeedTrees use noise stored in the Alpha channel of the diffuse texture to transition between different Tree LODs. To avoid automatic mip-mapping blurring the alpha mips (and thus ruining the transition), make sure to select ‘Dither Mip-maps alpha?’ when importing the diffuse texture.

Of course, the normal map for a composite map should be imported as TC_NormalMap. NOTE: When you export composite maps from SpeedTreeCAD, be sure that the option "Include Mipmaps" is NOT selected.

Creating Composite Materials

It is suggested that you use a Composite map for your Trees, since fronds, leaves and billboards can all then use the same material. Even if you do not use composite maps, the material setup is the same for all three. Currently, Branches must always use a separate material due to limitations with how SpeedTree creates UV mapping coordinates on tree trunks/branches.

For the composite and/or billboard materials, hook the texture alpha to the OpacityMask, set the blending mode to BLEND_Masked, and set the OpacityMaskClipValue to 0.33333. That number corresponds to a pixel value of 84 (out of 255), which is the lowest cutoff for alpha in any texture created by SpeedTreeCAD. In order for smooth level of detail (LOD) transitions occur, the alpha from the VertexColor must be added to the material's alpha. LOD switching occurs through a process of alpha fizzling, where the uniform noise in the alpha channel of the texture allows for one LOD to fizzle out while another fizzles in. To get this to occur, the SpeedTree utilizes the VertexColor in the shader when it is rendering. Adding the VertexColor alpha to the alpha channel essentially allows the OpacityMask to cut out holes in the texture.

Branches

Importing Branch Textures

Branch textures are usually imported with default settings. If you want your branches and trunks to fizzle out before billboards appear, you will need to manually add noise to the alpha channel of one your branch diffuse texture, and select ‘Dither Mip-maps alpha?’ when importing that texture.

Of course, the normal map for a branch material should be imported as TC_NormalMap.

Creating Branch Materials

Branch materials are used on the Trunk and the Branches of a Speed Tree. The standard setup is pictured below. If you want your branches and trunks to fizzle out before billboards appear,

You will also need to add the Vertex Color alpha to the diffuse alpha and plug it into the OpacityMask input of the branch material.

Instancing

You may be able to significantly cut down on the amount of time spent creating new materials if you use material instancing to texture the trees. This will allow you to have very few master materials; new instances can be created simply by changing the texture parameters. All texture samples should be TextureSampleParameter2Ds. You can also include some color controls which will then allow you to give some subtle color variation to your different tree actors by overriding the material assignments on the Speed Tree Actors. Multiplying the Diffuse by a VectorParameter is the easiest way to do this. Multiply the RGB of the VectorParameter by the Alpha output to get independent brightness control. Make sure the default values of the VectorParameter are all 1.

If this approach is to be taken, you will need at least two master materials: one for Composite Maps and one for Branches. If a composite map is used to contain everything possible (leaves, fronds, and billboards), then you should be able to tweak the color of the tree by changing the properties of only one instance, rather than having to tweak the Leaves and Billboards separately to keep them matching. For information on creating a MaterialInstance, see the Instanced Materials guide.

Using SpeedTree Actors

SpeedTrees can be placed in the scene using SpeedTreeActors. These actors will then reference the SpeedTree that you previously imported into the browser. The easiest way to accomplish this is to select the SpeedTree in the browser, then right click somewhere in your level and select "AddActor->Add SpeedTree: *", where * is the name of the SpeedTree in the browser.

SpeedTreeActor Properties

Double clicking on the SpeedTreeActor that was placed will bring up the actor properties window. Expanding the SpeedTreeComponent section will allow you to adjust parameters specific to this actor. Many of these parameters are similar to those found on any actor component, but the ones specific to SpeedTreeComponents will be explained here.

bUseBillboards, bUseBranches, bUseFronds, and bUseLeaves enable this actor to show these parts of the tree. The default is for all of these to be enabled. Turning off leaves, for example, is useful for making a tree look dead amidst other trees.

LodLevelOverride is useful for forcing a tree to appear at a certain level of detail (LOD). This parameter can be set to a number between 0.0 (the lowest detail, a billboard) and 1.0 (the highest, full geometry). Setting this parameter to -1.0 allows the tree to compute the correct LOD level based on the distance the camera is away from it. The parameters LodNearDistance and LodFarDistance control how near or far away the camera must be for the highest and lowest LOD levels to occur.

For a SpeedTree to light correctly, it must accept lights (bAcceptLights). SpeedTrees light with static vertex directional lighting. Their lighting channels can be modified just like that of a static mesh.

In order for collision to occur correctly, the various collision parameters (CollideActors, BlockActors, etc) should be enabled. The SpeedTree should also have been exported from SpeedTreeCAD with collision primitives in place.

Manipulating SpeedTreeActors

SpeedTreeActors can be moved and rotated like any other actor in the viewport windows. When you select them, they highlight blue and the gizmo handles appear so that you can move them. The default units for SpeedTrees are much bigger than the units used in UE3, so trees brought in straight from the SpeedTree Tree Library will probably be very small. You can scale them in UE3, but it is probably easier to scale them in SpeedTreeCAD during the composite map export process. Changing the size and size variance parameters on the Global tab in SpeedTreeCAD to be 10x bigger is usually an adequate adjustment. NOTE: When scaling a SpeedTree, the collision will only respect uniform scaling. Non-uniform scaling will not affect the tree’s collision.

Using Decolayers

SpeedTrees can also be added to a level with the use of decolayers. This allows you to paint trees onto the terrain. To add a SpeedTree decolayer to your terrain, open up the terrain actor's properties and go to the Terrain group. Find the Decolayers set and click the little circle icon to add a new decolayer.

Name the decolayer by setting the Name parameter. Then click the circle icon on the Decorations set to add a new decoration to this decolayer.

Next, expand the decoration you just added and find the Factory parameter set. Click the down arrow to choose the factory you want to use for this decoration and choose "SpeedTreeComponentFactory" from the list. Since SpeedTrees are pretty big for a decolayer decoration, you will probably want to set the Density parameter higher. Changing it to 0.1 is a good start.

Next, select the SpeedTree you want to use in the browser window. Then find the SpeedTree parameter under the OriginalComponent set in the decoration. Click the arrow to use the selected SpeedTree.

Once the decolayer is set up correctly, you can switch to the terrain tool, select the decolayer you just created, and paint it onto the terrain.

Wind Effects

Currently, SpeedTrees sway gently along the x-axis.

Exporting Custom Leaf Meshes

Custom leaf meshes allow you to have more control over the look of your trees and often give superior visual quality to camera-facing leaves (although the benefits of camera facing leaves are clear for large trees that need to look very filled in).

Please see the SpeedTreeCAD help documentation for how to import these SpeedTree leaf meshes and place them on your tree. Using custom leaf meshes does not change the Tree export, or the UE3 import process.

When making leaf meshes, it is a good idea to make a cluster of leaves all growing from the origin, as SpeedTreeCAD will place the meshes along branches and allow you to rotate and offset them from their local pivot.