> For the complete documentation index, see [llms.txt](https://docs.myarc.icu/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.myarc.icu/en/menu-configuration/menus/math-expressions.md).

# Math expressions

When building dynamic shops, upgrade trees, or stat panels, you often need to multiply a player's chosen quantity by a unit price, apply discounts and rounding, and display the result or check whether they can afford it. ArcMenu includes a unified math expression engine that works the same way across **condition comparisons**, **balance and points actions**, and **`{math: ...}` calculation placeholders**.

Evaluation follows a simple order: ArcMenu first replaces any ordinary placeholders inside the expression (such as `{meta:input-x}` or `%player_level%`) with the current player's values, and then calculates the math formula.

## Typical scenario: quantity × unit price

Suppose a player sets a purchase quantity `{meta:input-x}` using an [Arcitx text input](/en/feature-configuration/arcitx.md) or plus/minus buttons, and each item costs `24`. You can first verify that the entered quantity is valid and then check whether their budget covers the total:

```yaml
# Verify that the quantity is an integer between 1 and 64
condition: '{meta:input-x} >= 1 && {meta:input-x} <= 64 && {meta:input-x} == floor({meta:input-x})'
```

Next, check whether the player's balance covers the total cost (the example below uses a fixed budget of `1000`; on a live server, replace `1000` with your economy plugin's placeholder such as `%vault_eco_balance%`, since there is no built-in variable named `money`):

```yaml
condition: '1000 >= {meta:input-x} * 24'
```

Tip: If the purchase quantity comes from an Arcitx input box, the player must click the `submit` region bound to that input box before the value is written to `{meta:input-id}`.

## Operators and number formats

Expressions accept integers, decimals (such as `24`, `1.5`, `.5`, and `5.`), and scientific notation (such as `1e3` and `1e-3`). Write all multiplications explicitly with `*` (for example, `2 * (3 + 4)` rather than `2(3 + 4)`).

| Operator          | Meaning and precedence rules                                                                               | Examples and results                                 |
| ----------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `( )`             | Parentheses. Highest precedence; overrides normal evaluation order.                                        | `(2 + 3) * 4` → `20`                                 |
| `^`               | Exponentiation (power). Higher precedence than unary signs, and chained powers evaluate **right to left**. | `2 ^ 3 ^ 2` ($2^{(3^2)}$) → `512`                    |
| `+`, `-` (unary)  | Positive and negative signs. Lower precedence than exponentiation.                                         | `-2 ^ 2` → `-4`; `(-2) ^ 2` → `4`; `2 ^ -2` → `0.25` |
| `*`, `/`, `%`     | Multiplication, division, and remainder. The sign of `%` matches the dividend.                             | `3 * 24` → `72`; `7 % 3` → `1`; `-7 % 3` → `-1`      |
| `+`, `-` (binary) | Addition and subtraction.                                                                                  | `1 - -2` → `3`                                       |

## Built-in math functions

Function names are case-insensitive, and multiple arguments are separated by commas (`,`). You can nest functions and operators freely—for example, `max(1, min(64, floor({meta:input-x})))` clamps any number to an integer between 1 and 64.

| Function syntax    | Arguments           | Description                                                                                                                       | Examples and results                     |
| ------------------ | ------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| `abs(x)`           | 1 argument          | Returns the absolute value of `x`.                                                                                                | `abs(-3.5)` → `3.5`                      |
| `min(x, ...)`      | 1 or more arguments | Returns the smallest of the given arguments.                                                                                      | `min(5, 2, 8)` → `2`                     |
| `max(x, ...)`      | 1 or more arguments | Returns the largest of the given arguments.                                                                                       | `max(1, 3)` → `3`                        |
| `floor(x)`         | 1 argument          | Rounds down toward negative infinity to the largest integer not greater than `x`.                                                 | `floor(2.9)` → `2`; `floor(-1.1)` → `-2` |
| `ceil(x)`          | 1 argument          | Rounds up toward positive infinity to the smallest integer not less than `x`.                                                     | `ceil(2.1)` → `3`; `ceil(-1.1)` → `-1`   |
| `round(x)`         | 1 argument          | Rounds to the nearest integer. Halfway values (`.5`) round **away from zero** (`HALF_UP`) for both positive and negative numbers. | `round(2.5)` → `3`; `round(-2.5)` → `-3` |
| `round(x, places)` | 2 arguments         | Rounds `x` to `places` decimal places. `places` must be an integer from `0` to `15`.                                              | `round(2.675, 2)` → `2.68`               |

## Where to use math expressions

### 1. Directly in conditions

On either side of a comparison operator (`==`, `!=`, `>`, `>=`, `<`, `<=`, `is`, `is not`) in [Conditions](/en/menu-configuration/menus/conditions.md), write the math expression directly without wrapping it in `{math: ...}`:

```yaml
condition: '1000 >= round({meta:input-x} * 24 * 0.95, 2)'
```

Inline `{condition=...}` options at the end of individual actions support the exact same syntax:

```yaml
actions:
  right:
    - 'tell: &aQuantity is within budget. {condition=1000 >= {meta:input-x} * 24}'
```

Keep the difference between outer YAML quotes and inner operand quotes in mind: outer single quotes `'...'` only mark the YAML string boundary and do not stop evaluation. To compare a literal string like `3*4` as plain text rather than calculating it, wrap each operand in backticks, such as ``condition: '`3*4` == `3*4`'``.

### 2. Directly in balance and points actions

The numeric parameter for `give-money`, `take-money`, `set-money`, `give-points`, `take-points`, and `set-points` is evaluated directly by the math engine:

```yaml
actions:
  right:
    - 'take-money: round({meta:input-x} * 24 * 0.95, 2)'
```

All six actions require the final calculated value to be **greater than `0`**. Vault balances support decimals (using `round(expression, 2)` is recommended to keep two decimal places), whereas PlayerPoints requires an integer result, so wrap discounted formulas in `floor`, `ceil`, or single-argument `round`.

### 3. With `{math: ...}` in text, commands, and variables

In frontend text (`content`), tooltips (`tooltip`), command arguments, and variable actions like `set-meta` or `set-data`, values are treated as plain text by default. Write `{math: expression}` explicitly in these places whenever you want ArcMenu to calculate the expression and substitute the numeric result.

Make sure any variable used in the formula already holds a number before the menu evaluates it (unset variables expand to `null` and cannot be multiplied). For example, set an initial quantity with `set-meta: input-x 1` on the button that opens the shop menu:

```yaml
frontend:
  total:
    type: text
    content: '&fTotal price: {math: {meta:input-x} * 24}'
    size: 4
    update: 20

backend:
  calculate:
    width: 60
    height: 18
    actions:
      right:
        - 'set-meta: total {math: {meta:input-x} * 24}'
        - 'tell: &aTotal recorded as: {meta:total}'
```

Compare the two forms:

* `set-meta: total 3 * 24`: Stores the literal text `3 * 24`.
* `set-meta: total {math: 3 * 24}`: Stores the calculated result `72`.

`{math: ...}` placeholders can nest up to 64 levels deep and are evaluated from the innermost expression outward—for example, `{math: {math: 2 + 3} + 9}` evaluates the inner `5` first and then outputs `14`. When variables change while a menu is open, configure an `update` interval on the frontend text element or run a `refresh` action to update the on-screen value; see [Placeholders and text formatting](/en/text-formatting/text-placeholders.md).

## Precision and error handling

* **Display formatting**: Calculations use double-precision floating-point numbers (`Double`) internally. When `{math: ...}` formats a result as text, it rounds to 15 significant digits, strips trailing zeros, and always outputs standard decimal notation rather than scientific notation. As a result, `{math: 0.1 + 0.2}` cleanly outputs `0.3`. When comparing two complex decimal formulas with `==` in a condition, wrap them in `round(expression, places)` to avoid tiny floating-point rounding differences.
* **Safety limits and error reporting**: Division by zero, remainder by zero, non-finite results (`Infinity` or `NaN`), unknown function names, wrong argument counts, mismatched parentheses, or expression/placeholder nesting deeper than 64 levels are rejected as invalid:
  * **In conditions**: The condition evaluates to `false` and logs the character position and reason to the console. Even if wrapped in `not`, an invalid expression never becomes true.
  * **In actions**: Execution of the current action chain stops immediately (earlier actions that already ran are not rolled back), and the error is logged to the console.
  * **In frontend text or editor previews**: The specific error location in the formula is reported directly so you can quickly find and fix the configuration.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.myarc.icu/en/menu-configuration/menus/math-expressions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.