11 Formulas

garbagemule edited this page 2023-05-07 11:49:33 +02:00

Table of Contents

• Introduction
• Macros
• Reference
• Constants
• Variables
• Operators
• Functions
• Extensions

On this page:

• Introduction
• Macros
• Reference
  • Constants
  • Variables
  • Operators
  • Functions
• Extensions

Introduction

MobArena supports custom formulas in certain parts of the wave configurations:

• Wave growth in Default Waves
• Swarm amounts in Swarm Waves
• Boss health in Boss Waves

A formula is just a mathematical expression like 2+3. Formulas are resolved at runtime during arena sessions, and they support fixed value constants and runtime variables, as well as various mathematical operators and functions.

Here is an example of a Swarm Wave that spawns twice as many slimes as there are players currently alive in the arena, up to a maximum of 20:

swarm2:
  type: swarm
  wave: 12
  monster: slime
  amount: min(20, <live-players> * 2)

MobArena comes with a small bag of predefined formulas in formulas.yml called macros. These can be used instead of manually typing in the same formula multiple times all over the config-file. It is possible to redefine or remove existing formulas, and to add entirely new, custom formulas.

Macros

Formula macros are the best way to reuse formulas, because they allow you to write a given formula once and then just reference it by name later. Macros are defined in the formulas.yml file, which consists of four different sections:

• global: globally available macros that can be referenced from anywhere
• wave-growth: can only be used in the growth property of Default Waves
• swarm-amount: can only be used in the amount property of Swarm Waves
• boss-health: can only be used in the health property of Boss Waves

The global section defines macros that can be referenced anywhere a formula can be used. The other three sections are only available to a specific property. This means that the predefined top-up macro in the global section can be used as a wave growth formula or a boss health formula - both will work the same. However, because the macro low is defined in both the swarm-amount section and the boss-health section, the macro will resolve different formulas depending on whether it is used as a swarm amount in a Swarm Wave or as boss health in a Boss Wave. This also means that using it for the wave growth property in a Default Wave will result in an error, because low isn't defined in the wave-growth section, nor in the global section.

Reference

The following sections describe the constants, variables, operators, and functions available for use in formulas.

Constants

Constants are keywords (constant) that are bound to fixed numeric values.

• pi: 3.141592...
• e: Euler's number

Variables

Variables are words in angled brackets (<variable>) that resolve a numeric value at runtime. They resolve to different values depending on the state of the arena session.

• <current-wave>: the number of the current wave, e.g. 1 for the first wave, 2 for the second, etc.
• <final-wave>: the number of the final wave as given in the arena settings
• <initial-players>: the number of players alive at the start of the session
• <live-players>: the number of players currently alive in the session
• <dead-players>: the number of players not currently alive in the session
• <min-players>: the minimum number of players required to start the arena as specified in the arena settings
• <max-players>: the maximum number of players allowed in the arena as specified in the arena settings
• <max-players>: the maximum number of players allowed in the arena as specified in the arena settings
• <live-monsters>: the number of monsters currently alive in the session

Operators

Simple mathematical infix binary operators like addition, subtraction, etc.

• +: addition
• -: subtraction
• *: multiplication
• /: division
• %: modulo
• ^: exponentiation

Additionally, the following unary operators are supported:

• -: negation

Functions

Unary mathematical functions like square root, trigonometric functions, etc.

• sqrt(x): square root
• abs(x): absolute value
• ceil(x): round up
• floor(x): round down
• round(x): round to closest integer
• sin(x): sine
• cos(x): cosine
• tan(x): tangent

Additionally, the following binary functions are supported:

• min(a, b): minimum value of a and b
• max(a, b): maximum value of a and b

Extensions

The following parts of the Formula system can be extended by other plugins:

• Constants: Bind a fixed numeric value to a given keyword.
• Variables: Resolve custom variables from an arena instance at runtime.
• Operators: Introduce new unary or binary operators.
• Functions: Extend the function catalog with more unary or binary functions.

To register extensions, grab a hold of MobArena's FormulaManager instance via the main plugin class:

MobArena plugin = (MobArena) Bukkit.getPluginManager().getPlugin("MobArena");
FormulaManager formulas = plugin.getFormulaManager();

Then register the desired extensions:

// Register `tau` as a constant
formulas.registerConstant("tau", Math.PI * 2);

// Register `<exploding-sheep>` as a variable
formulas.registerVariable("exploding-sheep", arena -> {
    MonsterManager monsters = arena.getMonsterManager();
    Set<LivingEntity> sheep = monsters.getExplodingSheep();
    return sheep.size();
});

// Register `@` as a new binary operator that works like normal
// subtraction, except with flipped operands.
formulas.registerBinaryOperator("@", 2, true, (a, b) -> b - a);

// Register `up` as a new unary function that adds 1 to its input.
formulas.registerUnaryFunction("up", v -> v + 1);

Note that extensions must be registered before MobArena's onEnable() runs for the registrations to take effect. The FormulaManager is available after MobArena's onLoad() has executed. This means that plugins extending MobArena's Formula system should have loadbefore: [MobArena] in their plugin.yml file, and they should register extensions during their own onEnable() method.