Important
Versions 1.2.7 and newer require Java 11 or higher to work!
This is due to some required dependencies needing it.
The Math-Expansion is an Expansion for PlaceholderAPI which allows you to do math-expressions.
Supported are all expression supported by EvalEx, which this Expansion uses. See the examples below for some features.
The expansion has two specific Placeholder patterns to use.
Used for normal calculations while using the default decimal count and rounding behaviour
Used for calculations using your own decimal count and rounding behaviour.
Either value is optional and not providing one uses the default values set in the Config.
Math-Expansion supports all common math expressions such as
Those expressions can be used as-is without any real problem. Just keep in mind that expressions follow common logic which is that multiplication and division come before addition and substraction.
If you want specific expressions to be done first, even tho logic would prioritize others can you put them into brackets (i.e. (1+2)*3 would result in 1+2 being done first before multiplying by 3).
You can use any placeholders from PlaceholderAPI that return valid numbers.
When using placeholders will you need to use the curly brackets format ({some_placeholder}) rather than the percent placeholders.
As an example can you use {server_online} in your expressions to use the amount of online players in your server.
Due to how PlaceholderAPI handles placeholders can you not use the percent symbol (%) inside math expressions, as PlaceholderAPI would assume this to be the end of a placeholder.
To bypass this limitation does the Math-Expansion add a [prc] placeholder that you can use. This text will be replaced with an actual percent symbol before doing calculations.
Warning
The[prc]can NOT be used for placeholders in PlaceholderAPI. See the Previous section for more info.
Certain expressions cannot be reproduced with letters in the Math-Expansion. For example can
Because of this does EvalEx, the library used by Math-Expansion, provide specific custom patterns that allow to do these kinds of special calculations.
To f.e. do the above expression would you use SQRT(100*10) as the expression, which would now get the square root of
EvalEx offers a lot of different formats you can use, so check out their readme for more information.
Note: Those patterns are case-insensitive.
Sometimes an expression can return a relatively large number such as 3.333333....
The Math-Expansion does by default only show the first three decimals of a number, turning the above shown one into 3.333.
If you want to lower or increase the amount of decimals without altering the config option can you set your own decimals count using the advanced placeholder-pattern.
For example will %math_5:_8+1.234567% set the amount of decimals to 5, resulting in the returned number looking like this: 9.23457
Note
The final number depends on what rounding behaviour has been set.
By default, is the Math-Expression using Half Up as rounding behaviour, which means that numbers between 1 and 4 will be rounded down while numbers 5 to 9 will be rounded up.
If you would like to use a different rounding behaviour while not altering the config option can you provide a valid rounding behaviour in the advanced placeholder-pattern like this: %math_:ceiling_8+1.2222%
The above shown expression would - assuming a default decimals count of 3 is used - result in 9.223 even tho by normal standards would it be 9.222.
You may find more detailed explanations and examples of this option on the wiki.
The expansion adds a few specific settings to the config.yml of PlaceholderAPI, which can be changed if desired.
The Debug option enables or disables the expansion's debug mode.
With debug enabled will warnings also print an exception, if the warning is a result of an exception.
This is mostly useful for support and could increase the size of your server log files.
Sets the amount of decimal points (digits after the dot) should be shown by default in the final number.
The default value - which is also used whenever an invalid value has been set in the config - is 3 meaning a number such as 123.456789 will be displayed as 123.457.
Keep in mind that the actual number also depends on what rounding behaviour is used.
If the number is lower than 0 will it default to 0.
When true, disables the printing of warnings such as this one:
[00:00:00 WARN]: [PlaceholderAPI] [math] Invalid Placeholder detected!
[00:00:00 WARN]: [PlaceholderAPI] [math] Placeholder: %math_1-%
[00:00:00 WARN]: [PlaceholderAPI] [math] Cause: '1-' is not a valid Math Expression
It is recommended to not enable this option as it would otherwise make it more difficult to detect and find wrongly formatted placeholders.
The default rounding behaviour to use.
When the number returns more decimals than what should be displayed will it get rounded to the set decimal count.
Example: 5.684 with half up as rounding (Default) and a decimal count set to 2 returns 5.68 while a decimal count of 1 returns 6.7.
The default rounding is half-up which means that any number greater or equal to 5 is rounded up and anything below is rounded down.
Take a look at the wiki for a list of supported options.
Math-expansion uses EvalEx for evaluating the math-expressions.
Check the repository for available math-expressions.
Take a look at the CHANGELOG.md for all versions and their changes.