User Tools

Site Tools

SpeedTree Mesh Utilities for 3ds Max

Learn how to use the 3ds Max® SpeedTree Importer Script.

SpeedTree ships with two MaxScripts, 'SpeedTree FBX Importers' and 'SpeedTree Mesh Utilities', which aids in the process of creating custom mesh assets in 3ds Max for use in the SpeedTree Modeler. This help page explains how to properly use this set of utilities.

Loading The Utility

The SpeedTree Mesh Utilities were written in in the MaxScript language and must be loaded in the same manner as any other MaxScript.

The launcher script is located here → “[SpeedTree Modeler Install Dir]/Scripts/3ds Max/SpeedTree Utility Launcher”. Run the script in 3ds Max by selecting the menu item MaxScriptRun Script and browsing to the location described above.

Exporting and Importing Mesh Assets

STM/OBJ Mesh Export

Use the SpeedTree Mesh Utilities to export geometry for use within the SpeedTree Modeler as 'Mesh Assets'. The first selected object will be listed in the utility panel (“Box001” in the image to the right). The triangle count and dimensions for the selected object appear below the object's name. At least one object must be selected before exporting is enabled.

Override Offset
Mesh assets are oriented in the SpeedTree Modeler by using the scene origin of the source scene. If your object has been moved away from the scene origin, this offset will carry over to the Modeler. When this option is checked, the object will be oriented around its local pivot point instead. This option is useful if your 3ds Max scene contains more than one objects, and their positions in the scene are arbitrary.

Model Format
Use this drop-down to switch between exporting 'STM' and 'OBJ' meshes.

Export Mesh

To export a single object, press the “Export Mesh” button. A save dialog will appear allowing the user to specify a filename for the exported geometry, keying off of the “Model format” property.

Mapping coordinates must be present in the object before it is exported. Additionally, textures applied to leaf meshes should not tile, so adjust your applied 3ds Max materials accordingly (disable both U and V tiling) and ensure that all texture coordinates are in the 0.0 → 1.0 range. Tiling textures will not render correctly once compiled into a shared atlas.

Export By Material

To export multiple objects at once, press the “Export Selected By Material” button. As the description states, this option will export one mesh per material in your current selection.

Example Usage

As an example, if you have two objects selected, and Object 1 has three materials assigned (let's call them “blue”, “green”, and “red”), and Object 2 has two materials assigned (“green” and “yellow”), the exporter will export 4 meshes, one for each material it found – “blue”, “green”, “red”, and “yellow”. The “green” mesh will contain parts of both Object 1 and Object 2, since both had “green” assigned to some of their faces. This is a convenient way to divide up geometry for use in the SpeedTree Modeler, since in the Modeler any one mesh can only ever have a single material assigned to it.

STM Mesh Import

The “STM Mesh Import” group is used to import mesh assets ONLY in 'STM' format. 'STM' formatted meshes are distributed with the SpeedTree Model Library, or can be exported from the 'Mesh Asset' bar from embedded mesh assets.

PLEASE NOTE: This is not an importer for full 3D tree models made with SpeedTree. Full 3D tree models need to be imported and processed via the SpeedTree FBX Processor utility. Please refer to that section of this help page for more info.

Weld Mesh

When enabled, imported STM files are “welded”, meaning faces with smoothed normals and contiguous texture coordinates are combined into shared elements.

Only use this option with “real-time” 'STM' meshes (meshes with less than 1,000 triangles). Heavier meshes will load, but may take a long time to do so, due to the added complexity of sorting and welding the mesh together.

Show Normals

When enabled, an “Edit normals” modifier will be added to the imported mesh object.

Show Vertex Colors

When enabled, vertex color display will be enabled on the imported mesh object.

Import Mesh (.stm)

Imports an 'STM' file into the scene using the options above. Use 3ds Max's built-in OBJ importer for importing 'OBJ' files.

Mesh Tools

The SpeedTree Mesh Tools aid in the creation of custom mesh assets, whether you are exporting to 'STM' or 'OBJ'. Options are included for editing normals, geometry, and textures.

Project Normals


Due to the nature of typical real-time leaf meshes (blade-like and low detail), using the face normals may not the best option when the model is imported into the SpeedTree Modeler. Usually normals need to be pushed “outward” so the tree lights as if it these thin faces have volume. That's where the “Project normals” utility becomes useful.


When the Mesh Tools utility has been set to a floating dialog (via the “□” icon near the top right corner of the utility), the “auto-update” property becomes visible. This is because, for normals to be shown in the viewport, 3ds Max must have the “Modify” tab visible, which is not possible when working with the docked Mesh Tools utility. When enabled, the results of changing any of the Project Normals properties described below will update instantly, instead of requiring a manual press of the “Project Normals Now” button.

Projection Style

The “projection style” can be set to “Spherical” or “Cylindrical”. This will alter the method used for projecting the normals, as depicted below:

Projection Axis

The “projection axis” can be set to the X, Y, or Z axis, depending on how your model is oriented.


The “skew” parameter is used to alter the origin of the normals projection. Values greater than zero push the projection away down the “projection axis”. A skew value of zero projects the normals from the object's center.

Project Normals Now

Pressing this button will project the normals of the selected object. Two new modifiers will be added, a “Projection Mesh” modifier and a “Projected Normals” modifier. It is recommended to only perform this operation on “editable mesh” or “editable poly” objects, without any existing modifiers.

Flip Normals

This tool will mirror the selected normals on the desired object over any axis combination. If no normals are selected, all normals will be flipped.

Geometry Tools

The tools in the “Geometry Tools” section will alter the actual geometry of your object. Please use these tools with caution, as it will not be easy to recover the earlier version of the objects once the scene is saved.

Set Pivot To

By pressing this button, the object's pivot point is moved to the selected option in the combobox. The available options are:

  • Origin: This option will move the selected object's pivot to the scene origin [0, 0, 0].
  • Center: This option will move the pivot to the center of the object.

Remove Thin Faces

By pressing the button labeled “Remove faces <”, any faces with an area less than the number shown in the spinner to the right will be removed. Thin (low area) triangles can cause issues in the Modeler if used as a colliding mesh force, so it's better to remove them before using the mesh with the tree. This tool works best with “editable mesh” geometry, since “editable poly” geometry does not have a true face sub-level.

Use this spinner (Range: 0 → 0.04 generic units) to provide the minimum allowable area for each face in the mesh. Faces that do not pass the test are removed from the object.

Convert to "Tri-Foil"

This tool is primarily intended for use with meshes generated from within the SpeedTree Modeler through the “Generate mesh…” tool, then imported into 3ds Max. Since meshes created this way are usually planar on the XY plane, bringing them into 3ds Max and processing them with this button will automatically create a 3D mesh similar to the “Tri-Foil” leaf mesh sample that ships with the SpeedTree Modeler. The advantage to creating a custom “tri-foil” over using the shipped version is that custom “tri-foils” can be tailored to the texture they will be paired with, eliminating much more transparent texture area.

Texture Tools

The tools in the “Texture Tools” group are primarily for editing and diagnosing texture coordinates issues.

Select Streaked Triangles

Objects with “streaked” texture coordinates may render unpredictably in real-time applications, such as game engines. This is because part of the lighting calculation (specifically, calculating bi-normals and tangents) depends on a texture coordinate look-up in many 3rd party applications. Pressing this button will select any faces that have “streaked” texture coordinates.

Use this tool on an “editable mesh” object for best results, since “editable poly” objects do not have a true face sub-level.

Clamp Detail Tex Coords

This tool will clamp (or “streak”) the detail layer of texture coordinates on either the selected faces or the entire object if no faces are selected. This is useful for creating a “decal” style set of texture coordinates that do not repeat all over the model. The clamped section corresponds to the upper-left corner of the image, so it is best to use detail textures with transparency in this corner. When exported as STM or FBX, detail texture coordinates can be carried over to the SpeedTree Modeler.

Add Detail Layer To Material

This option will change a “bitmap” diffuse texture map to a “composite” map type. Once pressed, the user is prompted to choose a detail texture. Once a detail texture is selected from the file browser, the material applied to the object is altered to properly display both the base and detail layers. This is a useful shortcut when modeling custom meshes that contain two sets of texture coordinates.

World Building

World Building Tools

Forest Data Exporter

Use the options in the “Forest Data Exporter” group to extract a forest data file from the current 3ds Max scene. The Forest Data Exporter will find groups of instance objects and group them together for exporting.

Export Selection
This button will export forest data gleaned from the current object selection set, using the options below:

The format of the forest data export. SWA is a newer format intended to replace STF. Please see the sub-topic below, “Differences Between SWA and STF” for more info.

Add “.SRT” to entries
This option will suffix the entry names of each scene object with a “.SRT” extension. If your scene setup is intended to be used with the SpeedTree SDK, complete filenames for each entry must include the “.SRT” extension, even if your scene objects in 3ds Max are not actual SpeedTree models.

Save selection set
A 3ds Max selection set will be created using the the SWA/STF filename provided during export. This will make it easy to retrieve the selection set later if changes need to be made.

Rename In Selection

When working with large sets of instances, it can become difficult to rename the individual instances if the necessity arises. The “Rename in selection” tool makes this easy by parsing any string out of object names in the selection and replacing that string with any substitute string. A practical example of this would be to change the name of all instances starting with “LiveOak” to be changed to “../Trees/LiveOak”. That relative filepath will be rolled into the “LiveOak” forest entry, in case the location of your forest data file is not in the same location as your tree files.

Find string
The string to parse out of the name of each object in the current selection set.

The replacement string to substitute for the “find string” wherever it is found.

Rename In Selection
This button will perform the “Rename in selection” operation.

Forest Data Importer

SpeedTree Forest Data can be imported into 3ds Max via two different file types, 'SWA' (SpeedTree World Building ASCII) or 'STF' (SpeedTree Forest). To import forest data in either format, choose the applicable button in the Forest Data Importer property group.

The named entries in the forest data file will need to be assigned to objects already in your 3ds Max scene. If scene objects exist that match the entry names exactly, they will automatically be selected as the source object for that entry's group of instances. Otherwise, the user will be prompted to select a scene object from a dialog in order to create instances from it. Pressing “Cancel” will bypass the current entry from being processed, but the script will continue until it reaches the last forest entry.

Differences Between SWA and STF

Both SWA and STF formats contain the transform data of an arbitrary number of object instances for an arbitrary number of forest entries. However, SWA is a newer format intended to replace STF. While STF is deprecated, it still supported as of this release. STF can only support rotations about the Z axis, while SWA supports arbitrary rotations. Additionally, SWA supports both relative and absolute filepaths for each forest entry.

Using this method along with mental ray or V-ray Proxy objects will allow an artist to design and render a scene with billions of triangles (thousands of high detail trees), without needing to manipulate a single tree within the 3ds Max viewport. Make sure that both the 3ds Max scene and the SpeedTree world building setup are using the same working units and scale to ensure proper alignment.

Convert Units & Transforms

Unit Converter

When using specific units in either the SpeedTree Modeler or your final application, you can use this simple unit converter to resize mesh assets before importing them into the Modeler. For instance, trees in the SpeedTree Model Library are loosely modeled in feet, but you may be modeling a colliding mesh asset in meters, since your project uses meters (optionally, you could enable the “Use display units” option in the “STM/OBJ Mesh Export” group to simply export the mesh at a different size).

Conversion Options

  • Size and Position - Size, position, or both size and position can be scaled to the desired units. Check whichever should be applied.
  • From - The starting units that the model was creating in.
  • To - The target units to convert the model into. Use the special case “Scene units” to convert to the units in the current MAX file.

The resulting scale is displayed below the conversion options.

"Unitize" Mesh

To “unitize” the mesh means to take the longest extent and make it exactly 1 unit long. The “Scale results by” option will take this one-unit-long mesh and scale it by the assigned amount. This is useful for quickly making multiple meshes the same size.

Copy Transforms

Use the “Copy Transforms” tool to quickly borrow the position, rotation, or scale of another object in the scene. Optionally, the target being copied from can be hidden after the copy, if the selected object is intended to replace the target.