Density Chance Expressions
As mentioned in the world_gen page, Density and Chance can both utilize an expression to increase their customization. Expressions are a formula using common mathematical operations to obtain a result dependent on a few predefined variables.
To utilize the full power of this feature a basic notion of mathematics and noise maps is expected.
Expressions can be extremely powerful if used correctly, here are a few simple examples to show what they can do.
Using sin for this is probably not realistic, but it shows off the capabilities of this tool.
As we will see, the noise functions can accept parameters to modify their sampling rate, as well as be scaled and offset to achieve different effects. In this case, the range has been moved to -2 ~ 2, which then gets clamped to 0-1 by the selector.
This shows both the use of the map function and how the variables can be used for more than sampling noise. Here the chance ranges from 1 at sea-level to 0 at y=120, making for some pretty bald looking mountains and hills while valleys remain lush and full.
The is() function selects for a range of species, allowing you to give different species different chances.
All examples we have seen so far apply expressions to the chance selector, but let's not forget that they can be applied to density as well.
The density selector however does not have access to the following:
- y coordinate: The disc has not been placed yet so the height is not defined.
- radius: Density is what defines this value, so logically it does not exist yet.
- is() function: Species are selected after this step as well.
Using expressions is simple, one must only write the mathematical operation in the usual notation. The result of this operation should be between 0 and 1 (higher values are capped to 1 and lower values are capped to 0).
All white space characters are ignored and the expression is case insensitive.
If an invalid number is calculated (for example "0/0" or "sqrt(-1)") then the entire expression will fail and default to 0.
Operators are used in-order, with parameters left and right of them (except for unary operators, which only take a parameter on the right)
- Summation
+ - Subtraction
- - Product
* - Division
/ - Modulo
% - Negation
-(unary)
- Greater than or equal
>= - Less than or equal
<= - Equal
== - Not equal
!= - Greater than
> - Less than
<
Results of comparisons will be 1 if true and 0 if false.
- And
&& - Or
|| - Xor
^ - Not
!(unary)
Values are consider true if >= 0.5 and false otherwise. The returned values will be 1 if true and 0 if false.
These variables can be used almost anywhere* inside an expression and allow sampling information from the world.
-
x: x coordinate. -
y: y coordinate.- Can only be used by Chance expressions, in Density expressions y is always 0.
-
z: x coordinate. -
radius: The radius of the tree being generated.- Can only be used by Chance expressions, in Density expressions radius is always 0.
-
pi: The constant pi.
* Variables cannot be used inside the seed and octave parameters of the noise functions.
Functions take a certain amount of parameters and return a value based on the operation done.
-
min(a,b,c,...): Minimum value of all the parameters. Can have any number of parameters. -
max(a,b,c,...): Maximum value of all the parameters. Can have any number of parameters. -
avg(a,b,c,...): Average value of all the parameters. Can have any number of parameters. -
sqrt(a): Square root of a. -
pow(a,b): b raised to the power of a. -
exp(a): e raised to the power a. e is the euler number. -
lerp(v,a,b): Linear interpolation of the value v from a to b. (?) -
map(v,a1,b1,a2,b2): Maps the value v from the range a1,b1 to the range a2,b2. -
clamp(v,a,b): Clamps the value v between a and b. -
abs(a): absolute value of a. If positive it stays the same, if negative it's flipped to be positive. -
log(a,b): The logarithm of a on base b. Parameter b is optional, if omitted the euler number e is used as the base.
-
if(c,t,f): Applies t if the conditional c is true, applies f otherwise. -
is(a,b,c,...): Given a list of species ids, it returns 1 if the species is included, 0 otherwise. Can have any number of parameters.- Can only be used by Chance expressions, in Density expressions species is always
NULL_SPECIES. - Cannot be used inside the
seedandoctaveparameters of noise functions.
- Can only be used by Chance expressions, in Density expressions species is always
-
perlin(x,y,z,s,o1,o2,o3,...): Perlin noise. (?)- x y and z are the sampled coordinates. s is the noise seed. The o parameters are the octaves of the noise.
- All parameters are optional. By default the coordinate values are divided by 128.
-
simplex(x,y,z,s): Simplex noise. (?)- x y and z are the sampled coordinates. s is the noise seed. Simplex does not have octaves.
- All parameters are optional. By default the coordinate values are divided by 128.
-
noise(x,y,z,s,o1,o2,o3,...): PerlinSimplex noise. A hybrid noise used by Minecraft world generation.- x y and z are the sampled coordinates. s is the noise seed. The o parameters are the octaves of the noise.
- This noise does not sample the y coordinate so it goes unused. The parameter must still be included but will be ignored.
- All parameters are optional. By default the coordinate values are divided by 128.
-
sin(a): sine -
cos(a): cosine -
tan(a): tangent -
arcsin(a): arcsine -
arccos(a): arccosine -
arctan(a): arctangent -
arctan2(b,a): 2-argument arctangent. (?)
-
debug(a): Prints a debug line in console, returns a.