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.