Scripting (math expressions)

Scripting

Many aspects of polytone can support Math Expression Scripting. This allows you to add simple math expressions in your jsons to define more intricate behaviors.

All epression must be in a string format and can use some custom defined variables as well as some statically defined ones.

The return value of each expression must be a number between 0 and 1. If it is not it will be clamped to the nearest value.

Things that support these are

• Colormap xGetter
• Colormap yGetter
• Particle Parameters (all)
• Some things in Custom Colors

The language used is very simple and is powered by Exp4J library. You can read about it here on its official documentation: https://www.objecthunter.net/exp4j/#Usage

Here is an example of a simple expressions that returns the abslolute value of a block position with some added randomness.

"xGetter": "0.2 + abs(POS_X) + rand() * 0.2"

... Or you can just return a constant number. Sometime simple is better!

"yGetter": "0.5"

Variables and Functions

The functions and variables accesible to each expression changes depending on the object the expression belongs to.

Here is a list of all globally available Variables and Expressions. Note that whats' in parentesys is the name of the argument.

All functions follow their standard definition, basically they are what you would expect.

Globbal Variables
pi
π
e
φ

Global Functions
abs(val)
acos(val)
asin(val
atan(val)
atan2(y, x)
cbrt(val)
ceil(val)
cos(val)
cosh(val)
exp(val)
floor(val)
log(val)
log10(val)
log2(val)
sin(val)
sinh(val)
sqrt(val)
tan(val)
tanh(val)
signum(val)
rand()
gaussian()
noise(a,b)
max(a,b)
min(a,b)
step(val, threshold)
smoothstep(val, edge0, edge1)
lerp(delta, start, end)
red(packedColInt)
green(packedColInt)
blue(packedColInt)
alpha(packedColInt)
color(floatAlpha, floatRed, floatGreen, floatBlue)

Operators	Explanation
a == b	equals
a + b	addition
a - b	subtraction
a * b	multiplication
!a	factorial
a > b	greater
a < b	less than
a >= b	greter of or equal
a <= b	less than or equal
a ^ b	power
a / b	division
a % b	modulo

These are variables that can be used in any expression

Global Variables
TIME
DAY_TIME
SUN_TIME
RAIN
POS_X
POS_Y
POS_Z
SKY_LIGHT
BLOCK_LIGHT
TEMPERATURE
DOWNFALL
PLAYER_X
PLAYER_Y
PLAYER_Z
DISTANCE_SQUARED
PLAYER_SPEED_SQUARED
RENDER_DISTANCE

Here will be a list of function and variables specific to certain scopes:

Colormaps

Functions	Explanation
state_prop_i(index)	Gets the blockstate property of the block with the given index and returns the index of the value it has.
state_prop(index)	Same as the one above but returns normalized float value from 0 to 1 instead. If your block has just 1 property you can easily use this single function as your X Getter to have the x axis map to each property state (I.E. for crop blocks)

Variables	Explanation
POS_X	Block position X
POS_Y	Block position Y
POS_Z	Block position Z
DOWNFALL	Downfall (Humidity) Biome parameter at that block position
TEMPERATURE	Temperature Biome parameter at that block position
DAMAGE	Damage value of the provided itemstack (only makes sense for item colormaps)
TIME	Current game ticks time (only makes sense for non-block colormaps)
DAY_TIME	Current day ticks time (only makes sense for non-block colormaps)
RAIN	Current precipitation amount. 0 for clear, 0.5 for rain, 1 for thunder (only makes sense for non-block colormaps)

Particle Expressions (Particles Modifiers, Custom Particles Tickers, Particle Sound and Particle Emitters)

Variables	Explanation
SCALE	Initial particle scale
LIFETIME	Max particle lifetime
AGE	Current particle Age
RED	Initial particle red
GREEN	Initial particle green
BLUE	Initial particle blue
ALPHA	Initial particle alpha
SPEED	Initial particle speed
X	Initial particle x
Y	Initial particle y
Z	Initial particle z
DX	Initial particle delta x
DY	Initial particle delta y
DZ	Initial particle delta z
CUSTOM	Custom Particle Type "custom" variable value
TIME	Gametime in ticks. i.e use to have color varying particles
DAY_TIME	Current day ticks time (only makes sense for non-block colormaps)
RAIN	Current precipitation amount. 0 for clear, 0.5 for rain, 1 for thunder (only makes sense for non-block colormaps)

Block Expressions (Block Particle Emitters, Block Sound Emitters, Custom Particle Initializer)

Functions	Explanation
state_prop_i(index)	Gets the blockstate property of the block with the given index and returns the index of the value it has.
state_prop(index)	Same as the one above but returns normalized float value from 0 to 1 instead. If your block has just 1 property you can easily use this single function as your X Getter to have the x axis map to each property state (I.E. for crop blocks)

Variables	Explanation
POS_X	Block position X
POS_Y	Block position Y
POS_Z	Block position Z
TIME	Gametime in ticks. i.e use to have color varying particles
DAY_TIME	Current day ticks time (only makes sense for non-block colormaps)
RAIN	Current precipitation amount. 0 for clear, 0.5 for rain, 1 for thunder (only makes sense for non-block colormaps)
BLOCK_LIGHT	Block Light value at position. From 0 to 15
SKY_LIGHT	ky Light value at position. From 0 to 15

Custom Noises

As mentioned above there is already a pre made noise() function. This is a simplex perlin noise with one octave of 1 and seed of 0.

Incase you want different types of noises you can define your own Perlin Noises!

You'll be able to do so in polytone/noises.

The noise definition has 2 parameters, a seed and an octaves. Both are self explanatory if you know what perlin noise is.

Here's an example definition

{
  "seec": 42,
  "octaves": [
    -5, 1, 2
  ]
}

To then use these noises in your expressions you'll be able to reference them following this naming scheme: noise_[noise namespace]_[noise name] or just noise_[noise name] if they have been defined under the minecraft namespace.

Here's an example using a noise with path mypack:mynoise

{
  "some_expression": "noise_mypack_mynoise(TIME, 0)"
}