View source for Editor Property Expressions

[[category:Editor]]
= Introduction =
Number properties (Ints and Floats) in the editor can use expressions to help automate some common tasks.

{| class="wikitable"
! Type !! Details
|-
| int || An whole number with no decimal places. Can be between -2,147,483,648 and 2,147,483,647
|-
| float || A number with decimal places. Precision drops on higher numbers.
|}

For example, you can do simple math, such as {{code|12 + 16.5}} to get the result of {{code|28.5}}. It also supports correct order-of-operations, so {{code|8 + 16 * 2}} will give the correct result of 40 instead of 48. It also supports parenthesized expressions, so {{code|(8 + 16) * 2}} will give 48 if that's what you want.

Note that expressions only work when the property is applied, they will not be retained afterwards. So if you use it to set random offsets, and then want to change those random offsets, you'll need to undo and enter the expression again.

= Operators =

(Lower precedence happens earlier)

{| class="wikitable"
! Operator !! Description !! Precedence
|-
| + || Adds the left operand to the right operand || 3
|-
| - || Subtracts the right operand from the left operand || 3
|-
| * || Multiplies the left operand by the right operand || 2
|-
| / || Divides the left operand by the right operand || 2
|-
| % || Divides the left operand by the right operand and returns the remainder || 2
|- 
| (   ) || Parenthesized expression, will always be evaluated first from left-to-right. || 0
|}

= Constants =
There are also a few more advanced constants and functions that are available, such as:

{| class="wikitable"
! Constant !! Type !! Description
|-
| v || int/float (Depending on Property type) || The current value of the property. If you wanted to offset a value by 12, you can just do {{code|v + 12}}. If you want to halve a value, {{code|v / 2}} will do the job.
|-
| i || int || The index of the current selection. This is useful if you select multiple objects, and want to have each object have a different value. For example, if you wanted to evenly space several objects along the X axis, starting at 96 with a 32 unit gap between each, you could set the X value of the transform to {{code|96 + i * 32}}.
|-
| count || int || The number of objects that have been selected. This is useful if you want to evenly distribute a value in a range, so if you wanted the value to go between 0 and 2 at even intervals between all of the selected objects, you can do {{code|i / count * 2}}.
|}

{{note|info|Note that constants and functions are case insensitive.}}

= Functions =

== rand ==
* {{code|rand(max)}} and {{code|rand(min, max)}}: Allows you to generate a random value. 

{{note|todo|'''Fix randomization'''
At current, {{code|rand}} will be randomized every time you type into the textbox, and will also be rerandomized when the value is committed, so the in-editor preview can't be trusted.
 
We should instead have something that sets a random seed when editing starts, and only re-seed it once editing ends. Maybe with a hotkey to rerandomize?}}

= Internal Details =
== Type Promotion ==
Internally, values are treated as {{code|float}}s if they contain a decimal point, and {{code|int}}s otherwise. If you mix an {{code|int}} and a {{code|float}} in an operation, the value will always be promoted to a {{code|float}}, with the exception of the division operator which will **always** promote to a {{code|float}}.

{{code|v}} will be treated as either an {{code|int}} or a {{code|float}} depending on the type of property that is currently being used.

Note that the expression will automatically convert back to the type of the property on submission. If in an {{code|int}} property, any fractional part of a float will be discarded, and if in a {{code|float}} property, it will be converted to a {{code|float}} which may result in a lack of precision.