Introduction to Rules

Learn how SpeedTree uses the concept of Rules to make it easier to manipulate models within individual and team workflows.

Overview

SpeedTree Rules are Lua scripts that allow you to design a simple, customized editing interface made of various controls that let you easily manipulate the existing properties of your models beyond the default capabilities of the Modeler.

With the use of Rules in the Modeler, you can:

Simplify and speed up your modeling process by focusing on a selected set of properties that you adjust often, in sequence, or in a combined way.
Make it easy for multiple contributors to manipulate specific aspects of the model in a controlled way.
Test different variants of the same model in a nondestructive way and compare them in a single scene.

How Rules work

The primary function of a Rule is to create a user control that allows you to manipulate a specific aspect of your model with its existing properties. To understand the way a Rule works, you can conceptually divide it in three functional layers:

Functional layer	Purpose
Rule definition	Set the Rule type and parameters according to the user control you need in the interface.
Value processing	Transform the output of the user control into a value (or a set of values) suitable for the properties involved in the aspect of the model you want to manipulate.
Property assignment	Assign the processed values originating from the user control to one or more properties of your model.

Note

With a straightforward Rule that controls a single property, you can skip the value processing part if you make the Rule definition and the property assignment directly fit together. However, the value processing step becomes necessary as soon as you design a more complex Rule that controls curves or multiple properties.

To learn about the base requirements to structure a Rule script and get it functional, refer to Anatomy of a Rule.

Rule types

Rules allow you to create different types of user controls. Each one corresponds to a specific Rule definition function that you have to include in the Rule script.

Control type	Display
Slider
Checkbox
Drop-down box
Randomizer

Rule capabilities and use cases

Rules allow you to get restrictive or extended control over the properties of your models.

Here are some of the main capabilities they can add on top of the default controls of the Modeler:

Capability	Description	Use case example
Range limitation	Manipulate a property value in a specific range between predefined minimum and maximum values.	Edit the size of your tree while keeping its proportions within a range that suits your modeling context.
Property combination	Manipulate multiple properties in a combined way with a single user control.	Manipulate the growth of your tree with a single slider that reliably controls the trunk length, radius, and other relevant properties at the same time.
Scale normalization	Manipulate properties using a normalized scale.	Get a relevant perception when you manipulate an aspect of your tree that is conceptually more a proportion or a percentage than a number.
Curve interpolation	Manipulate property curves with interpolation between two predefined states.	Automatically adjust the profile curve of branches to gradually simulate gravity effects as the branches get longer.

Best practices and general facts about Rules

Add Rules once you're comfortable with the SpeedTree properties and how they impact your model and each other.
Rules work best when most parts of the model are created using relative properties. For example, when lengths are based on a percent of the parent's length instead of an absolute value.
Don't set any property value more than once in a script. Use a Lua variable to store the results of complex calculations and then set the property once with that variable.
If you compose two rules that impact the same property, the last rule executed wins.

Tip

Use SpeedTree's search syntax to set what generators to modify in a Rule.