Use custom attributes in expressions

It’s often helpful to add a custom attribute to an object and use it in an expression. You can use a custom attribute to control a combination of other attributes. You can also use a custom attribute as a variable—a place to store a value temporarily to be read by other attributes.

Custom attributes have no direct effect on any characteristic of an object.

See Assign to a custom attribute for details on how to add and use a custom attribute with particles.

Example

Suppose you’ve given a NURBS sphere named Planet a circular, orbiting motion in the XY plane with this expression:

Planet.tx = sin(time);
Planet.ty = cos(time);

Planet orbits the origin at a radius of 1 unit.

In the following steps, you’ll create a custom attribute named distance to increase the radius of Planet’s orbit over time.

Note

The small balls in the preceding figure show the circular path of Planet. They’re in the figure only to help you visualize the motion. They aren’t part of the animation or expression.

To add a custom attribute to alter the orbit

Select Planet.
Select Modify > Add Attribute.
In the Add Attribute window, enter distance in the Long Name text box.
Make sure Make attribute: Keyable is on.
Set Data Type to Float, and Attribute Type to Scalar.
Set Minimum to 1, Maximum to 10, and Default to 4.
Minimum and Maximum set the lowest and highest values you can enter for the attribute in the Attribute Editor or Channel Box.

Default sets the default value displayed for the attribute.

An expression isn’t bound by the Minimum and Maximum values. The attribute receives whatever value you assign it in the expression.

The expression can read the Default value or any other value you set in the Attribute Editor or Channel Box.
Click Add to add the attribute, then close the Add Attribute window.
The distance attribute appears in the Attributes list of the Expression Editor for Planet. You can now set or read the value of the attribute in any expression.
Edit the expression to this:
```
Planet.tx = distance * sin(time);
Planet.ty = distance * cos(time);
```
Multiplying the sin(time) and the cos(time) by the distance attribute makes Planet circle the origin at a distance specified by the value of the distance attribute. See Useful functions for details on the sin and cos functions.

Because you gave the distance attribute a default value of 4 when you added it to Planet, playing the animation makes Planet circle the origin at a distance of 4 grid units from the origin.

You can make the expression control the distance attribute over time.
Edit the expression to this:
```
distance = time;
Planet.tx = distance * sin(time);
Planet.ty = distance * cos(time);
```
By setting distance to the value of time, Planet’s orbiting distance increases as playback time increases. Planet moves in a steady outward spiral as the animation plays.

Instead of using an expression to control distance, you can keyframe its value over time.

For example, by keyframing a distance value of 1 at frame 1 and a value of 10 at frame 200, Planet moves in a steady outbound spiral as you play the 200 frames. Planet’s distance increases in a linear interpolation from 1 to 10 as the animation plays.

You can animate the distance attribute with keyframes or with an expression, not with both.

TipIf an expression controls an attribute and you want to control it with keyframes instead, delete all statements that assign values to the attribute, then click the Edit button. Use the Channel Box to reset the attribute’s value to an initial value, then set keyframes as desired.
If keyframes control an attribute and you want to control it with an expression instead, click the attribute’s text box in the Channel Box, then select Channels > Delete Selected. Assign values to the attribute name in an expression as desired.