Documentation

SpeedTree Modeler

SpeedTree Modeler

Introduction to Rules

Learn how SpeedTree uses the concept of Rules to make it easier to manipulate models within individual and team workflows.
Read time 4 minutesLast updated 2 hours ago

Rules give you a customized, Lua-scripted interface for manipulating model properties beyond what the Modeler exposes by default.

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 definitionSet the Rule type and parameters according to the user control you need in the interface.
Value processingTransform 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 assignmentAssign 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
Rule UI with the two examples of sliders
Checkbox
Rule UI with a checkbox example
Drop-down box
Rule UI with a drop-down box example
Randomizer
Rule UI with a randomizer example

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 limitationManipulate 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 combinationManipulate 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 normalizationManipulate 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 interpolationManipulate 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.

Additional resources