> 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/text-formatting/text-placeholders.md). # Placeholders and text formatting Placeholders dynamically insert player status, menu arguments, saved variables, and math results into your menus. Frontend text nodes, hover tooltips, dynamic image paths, action arguments, and conditions all share the same placeholder and color formatting rules. ## Built-in player and preference placeholders ArcMenu provides player information and pointer preference placeholders out of the box without requiring extra extensions: | Placeholder | Description | | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | `%player_name%` | The player's username. | | `%player_uuid%` | The player's UUID string. | | `%player_world%` | The name of the world the player is currently in. | | `%player_x%`, `%player_y%`, `%player_z%` | The player's current coordinates, formatted to two decimal places. | | `%arcmenu_sensitivity%` | The player's mouse sensitivity multiplier (up to four decimal places, such as `1` or `1.4142`). | | `%arcmenu_sensitivity_level%` | The player's mouse sensitivity level from `1` to `9` (defaults to `5`). | | `%arcmenu_cursor_scale%` | The player's cursor scale multiplier (up to four decimal places). | | `%arcmenu_cursor_scale_level%` | The player's cursor scale level from `1` to `9` (defaults to `5`). | | `%arcmenu_lang_%` | Resolves a localized string for the player's current language, such as `%arcmenu_lang_samples.main.title%`. | The pointer preference placeholders also accept the aliases `%arcmenu_privatepointersensitivity%` and `%arcmenu_privatepointerscale%` (along with their `_level` variants). When PlaceholderAPI is installed on the server, these preference placeholders can also be used inside other plugins. On frontend text nodes, images, and backend tooltips, the `update` field controls how often placeholders are refreshed: ```yaml frontend: player-info: type: text content: '&f%player_name% &7in %player_world% (%player_x%, %player_z%)' size: 4 update: 20 ``` `update` accepts `-1` or a positive integer (measured in server ticks): * `-1` (default): Resolves once when the menu opens or when an explicit refresh is triggered, remaining static otherwise. * Positive integer (such as `20`): Automatically re-evaluates placeholders every N ticks (`20` ticks is roughly 1 second). ## State data, menu arguments, and session bindings ArcMenu supports three built-in state scopes, positional menu arguments, and session-scoped bindings provided by add-on plugins: | Recommended brace syntax | Percent-sign equivalent | Shorthand alias | Description | | ----------------------------- | ----------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------- | | `{meta:}` | `%arcmenu_meta_%` | `{m:}` | Temporary per-player in-memory data, cleared when explicitly deleted or when the server restarts. | | `{data:}` | `%arcmenu_data_%` | `{d:}` | Persistent per-player data saved to disk or the database. | | `{globaldata:}` | `%arcmenu_globaldata_%` | `{gdata:}`, `{g:}` | Server-wide persistent data shared across all players. | | `{0}`, `{1}`, `{2}`... | `%arcmenu_args_0%`, `%arcmenu_args_1%`... | — | Positional arguments passed when opening the menu (zero-indexed). | | `{session::}` | — | — | Data bound to the active session by an add-on plugin via the API. | ### Rules for reading arguments and input values * **Menu arguments**: When a menu is opened with `open: world-info survival hard`, `{0}` resolves to `survival` and `{1}` resolves to `hard`. Inside the menu, the `set-args` action can replace the active argument list. If you reference an argument index that was not provided, the brace form `{2}` stays literal as `{2}`, whereas `%arcmenu_args_2%` resolves to `null`. * **Unset state values**: Reading a `meta`, `data`, or `globaldata` key that has not been set resolves to the string `null`. See [Advanced actions](/en/menu-configuration/menus/advanced-actions.md) for instructions on writing and removing state values. * **Text input values**: Text captured through the chat `catcher` is stored in `{meta:input}` or `{meta:input-}`. Text committed through [Arcitx text input](/en/feature-configuration/arcitx.md) is stored in `{meta:input}` or `{meta:input-}`. ## PlaceholderAPI integration When PlaceholderAPI and the relevant expansions are installed, you can use placeholders from any third-party plugin directly inside menu text, tooltips, conditions, and actions—such as `%vault_eco_balance%` for economy balances or `%playerpoints_points%` for points. Dynamic frontend image paths and player head materials also resolve placeholders: * Dynamic images: `source: '/ranks/%vault_rank%.png'` (the resolved placeholder output must form a valid lowercase relative path). * Player heads: `material: ''`. ## Math calculation placeholders `{math: ...}` To calculate totals, discounts, or stat bonuses directly in the UI, wrap an expression in `{math: ...}`: ```yaml frontend: total-price: type: text content: '&fDiscounted total: &e{math: round({meta:amount} * 24 * 0.95, 2)} coins' size: 4 update: 20 ``` ### Evaluation order and usage tips 1. **Variables expand before evaluation**: ArcMenu first replaces `{session:...}`, language placeholders, `{meta:...}`/`{data:...}`, menu arguments `{0}`, built-in player placeholders, and PlaceholderAPI placeholders inside the expression, and then evaluates `{math: ...}`. 2. **Nesting is supported**: Math placeholders can be nested; inner `{math: ...}` blocks are evaluated first and substituted into the outer expression. 3. **Clean number formatting**: Trailing decimal zeros are stripped automatically, and results are formatted with up to 15 significant digits (for example, `3 * 24.0` outputs `72`). 4. **Initialize variables with numeric values**: An unset variable like `{meta:amount}` resolves to `null`, which prevents the math expression from evaluating and leaves the raw expression text visible. Initialize variables before or when the menu opens—such as running `set-meta: amount 1` in the entry action or under the menu's `events.open`. You can also use `{math: ...}` when storing data or running commands in actions. Writing `set-meta: total 3 * 24` stores the literal string `3 * 24`, whereas `set-meta: total {math: 3 * 24}` evaluates the expression and stores `72`. For the complete list of operators and functions, see [Math expressions](/en/menu-configuration/menus/math-expressions.md). ## Color codes and text styling Menu text supports standard Minecraft `&` formatting codes as well as 6-digit hexadecimal RGB colors: | Syntax | Effect | | -------------------- | ---------------------------------------------------------------------------------------------- | | `&0`–`&9`, `&a`–`&f` | Standard 16 Minecraft colors (e.g., `&f` white, `&7` gray, `&a` green, `&e` yellow, `&c` red). | | `&#RRGGBB` | Custom 6-digit hex RGB color, such as `c73ff`. | | `&l` | **Bold**. | | `&o` | *Italic*. | | `&n` | Underline. | | `&m` | ~~Strikethrough~~. | | `&k` | Obfuscated (rapidly changing characters). | | `&r` | Resets color and text formatting from that point onward. | ```yaml content: 'c73ff&lWelcome to the server! &r&7Select an option below.' ``` ### Fonts and color formats for other elements * **Custom fonts**: Set `font: namespace:path` on a frontend `text` node (defaults to `minecraft:default`). Any font present in the player's active resource pack can be referenced. See [Frontend element types](/en/menu-configuration/menus/frontend.md) for font size, alignment, and line-wrapping options. * **Shapes, images, and tooltip colors**: * On frontend `rectangle`, `line`, and `frame` nodes, `color` takes a quoted 6-digit hex string `'#RRGGBB'` (such as `'#182031'`), while transparency is controlled separately via `opacity` (`0` to `255`). * On frontend `image` and `gif` nodes, the optional tint field `color` accepts `'#RRGGBB'` or `'&#RRGGBB'`, with transparency controlled via `opacity` (`0` to `255`). * In `tooltip.yml`, plain tooltip background and border colors use 8-digit hex strings with an alpha channel: `'#AARRGGBB'`. * **Rich chat messages**: To send interactive chat messages with hover or click events when a button is clicked, use the `tellraw: ` action. --- # 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/text-formatting/text-placeholders.md?ask=&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.