Data\Expression
Expressions are a powerful feature of the DreamEditor that allows you to write formulas and plug them into various fields of game data. They're useful for creating things like damage formulas, where certain weapon types (fire, nature, armored) will deal more or less damage to different "armor" types (water, earth, light) as arbitrarily defined with tags. See notion guide "Using Expressions."
Similar to Validators, expressions are evaluated and return a result. Expressions are more flexible as they can be configured to write user defined formulas, and unlike validators they can return numeric or boolean values depending on context.
In numeric cases, true is treated as 1
and false is treated as 0
. In boolean cases, non-zero numbers are treated as true
and 0 is treated as false
. Note that expressions can also be used as validators.
The most common use case for expressions are for creating custom damage formulas, such as damage = ([caster]STRENGTH * 10) - [target]ARMOR)
, where STRENGTH
and ARMOR
are arbitrary attributes defined as tags.
Supported Fields
Expressions can be plugged into a number of existing data fields and can also be used with data binding in custom UI. These are the currently supported data fields:
- Behavior/PeriodicInterval
- Effect/ApplyBehavior/Duration
- Effect/Damage/DamageAmount
- Effect/EnumerateUnitList/StepCount
- Effect/Heal/HealAmount
- Effect/ModifyUnit/ModifyMana/Amount
- Effect/ModifyUnit/ModifyShield/Amount
- Mover/Orbiting/Radius
As of version 0.10.x and up, Effects now have a universal field expression section where you can overwrite any numeric effect field with an expression by specifying its field path. The expression will be evaluated right before the effect is cast using the same caster/source/target info as passed to the effect itself.
Value
These are the types of values you can include or reference in expression formulas.
Constant
Returns a constant value.
Bool Value
Returns true or false.
Int32 Value
Returns an integer value.
Double Value
Returns a floating point number (with decimal).
Random
Returns a random number between the min and max value.
Int32 Value
MessageType: RangeInt
Returns an integer value.
Double Value
MessageType: RangeDouble
Returns a floating point number (with decimal).
Damage Amount
The damage amount is multiplied by this value (default 0).
Returns the literal damage value when used within a damage effect.
Multiplier
Heal Amount
The heal amount is multiplied by this value (default 0).
Returns the literal heal value when used within a heal effect.
Multiplier
Tag Count
Returns the tag count of a specific tag on a unit.
Unit
EnumType: ValidatorExpressions.UnitLocation
Which unit is evaluated.
Tag Name
Which tag is evaluated.
Unit Level
Returns the level of a unit. Currently limited in usefulness.
Unit
EnumType: ValidatorExpressions.UnitLocation
Which unit is evaluated.
Ability Level
Returns the level of an ability. Currently limited in usefulness.
Ability
Which ablity is evaluated.
Wildsky Upgrade Level [Wild Sky]
Returns the level of a wild sky upgrade.
Data Upgrade
Which upgrade is evaluated.
Upgrade Level
Returns the level of an upgrade.
Upgrade
Which upgrade is evaluated.
Remaining Path Distance
Returns the remaining path distance for a unit with waypoints.
Unit
EnumType: ValidatorExpressions.UnitLocation
Which unit is evaluated.
Unit Ability Cooldown
Returns the current cooldown remaining for an ability.
Unit
EnumType: ValidatorExpressions.UnitLocation
Which unit is evaluated.
Ability
Which ablity is evaluated.
Use Cooldown Period
When checked, the expression returns the total cooldown duration, rather than time remaining.
Health
Returns the current health of a unit.
Unit
EnumType: ValidatorExpressions.UnitLocation
Which unit is evaluated.
Max Health
Returns the max health of a unit.
Unit
EnumType: ValidatorExpressions.UnitLocation
Which unit is evaluated.
Health Fraction
Returns the current health fraction of a unit.
Unit
EnumType: ValidatorExpressions.UnitLocation
Which unit is evaluated.
Mana
Returns the current mana of a unit.
Unit
EnumType: ValidatorExpressions.UnitLocation
Which unit is evaluated.
Max Mana
Returns the max mana of a unit.
Unit
EnumType: ValidatorExpressions.UnitLocation
Which unit is evaluated.
Mana Fraction
Returns the current mana fraction of a unit.
Unit
EnumType: ValidatorExpressions.UnitLocation
Which unit is evaluated.
Shield
Returns the current shields of a unit.
Unit
EnumType: ValidatorExpressions.UnitLocation
Which unit is evaluated.
Max Shield
Returns the max shields of a unit.
Unit
EnumType: ValidatorExpressions.UnitLocation
Which unit is evaluated.
Shield Fraction
Returns the current shield fraction of a unit.
Unit
EnumType: ValidatorExpressions.UnitLocation
Which unit is evaluated.
Behavior Stack Count
Returns the current stack count of a behavior on a unit.
Unit
EnumType: ValidatorExpressions.UnitLocation
Which unit is evaluated.
Behavior
Which behavior is evaluated.
Behavior Elapsed Time
Returns the elapsed time that a behavior has been on a unit.
Note that this duration is reset to 0 when the stack count is refreshed.
Unit
EnumType: ValidatorExpressions.UnitLocation
Which unit is evaluated.
Behavior
Which behavior is evaluated.
Behavior Duration
Returns the duration that a behavior has been on a unit.
Returns the maximum duration of a behavior on a unit. Note that this duration is not extended when the stack count is refreshed.
Unit
EnumType: ValidatorExpressions.UnitLocation
Which unit is evaluated.
Behavior
Which behavior is evaluated.
Add Expressions
Returns the sum of the listed expressions.
Functionally similar to Add but used as an expression value rather than a top-level operator.
Effect Critical Hit
Returns 1 if the effect tree is the result of a critical hit with a weapon or ability.
This can be used to create damage expressions that deal increased damage on critical hits. For example this psuedo-expression would cause a damage effect to deal 150% damage on critical hit.
Multiply( EffectCrticial * DamageAmount(1) * Constant(0.5) )
Swap out the constant for value derived from tag count) to support dynamic critical hit damage multipliers.
Units Distance
Returns the distance between units.
From Unit
EnumType: ValidatorExpressions.UnitLocation
To Unit
EnumType: ValidatorExpressions.UnitLocation
Divide
Divide a value by another.
Multiply
Multiply multiple values together. Supports nested expressions.
Subtract
Subtract a value from another.
Add
Add multiple values together. Supports nested expressions.
Compare
Compares two values/expressions and returns true or false based on the result.
Logic Not
Returns the flipped value or expression (true becomes false, false becomes true).
Logic And
Returns true if all listed values/expressions are true.
Logic Or
Returns true if any listed values/expressions are true.
Named Expression
Used to reference another expression. This is useful for combining multiple expressions or breaking complex expressions into smaller abstractions.
Exponent
Returns value to the power of another. Similar to the ^
operator in Lua.
Modulo
Returns the remainder of a value after being divided by another. Similar to the %
operator in Lua.
If
Returns the sum of the Values expressions if the Compare condition returns true. Otherwise returns the same of the Else Values expressions.